tools/README

This directory contains a number of tools related to policy, some of
which are used in building and validating the policy and others are
available for help in auditing and analyzing policy.  The tools are
described further below.

checkfc
   A utility for checking the validity of a file_contexts or a
   property_contexts configuration file.  Used as part of the policy
   build to validate both files.  Requires the sepolicy file as an
   argument in order to check the validity of the security contexts
   in the file_contexts or property_contexts file.

   Usage:
   checkfc sepolicy file_contexts
   checkfc -p sepolicy property_contexts

checkseapp
    A utility for merging together the main seapp_contexts
    configuration and the device-specific one, and simultaneously
    checking the validity of the configurations. Used as part of the
    policy build process to merge and validate the configuration.

    Usage:
    checkseapp -p sepolicy input_seapp_contexts0 [input_seapp_contexts1...] -o seapp_contexts

insertkeys.py
    A helper script for mapping tags in the signature stanzas of
    mac_permissions.xml to public keys found in pem files.  This
    script is described further in the top-level sepolicy/README.

post_process_mac_perms
    A tool to help modify an existing mac_permissions.xml with additional app
    certs not already found in that policy. This becomes useful when a directory
    containing apps is searched and the certs from those apps are added to the
    policy not already explicitly listed.

    Usage:
    post_process_mac_perms [-h] -s SEINFO -d DIR -f POLICY

      -s SEINFO, --seinfo SEINFO  seinfo tag for each generated stanza
      -d DIR, --dir DIR           Directory to search for apks
      -f POLICY, --file POLICY    mac_permissions.xml policy file

sepolicy-check
    A tool for auditing a sepolicy file for any allow rule that grants
    a given permission.

    Usage:
    sepolicy-check -s <domain> -t <type> -c <class> -p <permission> -P out/target/product/<board>/root/sepolicy

sepolicy-analyze
    A tool for performing various kinds of analysis on a sepolicy
    file.  The current kinds of analysis that are currently supported
    include:

    TYPE EQUIVALENCE
    sepolicy-analyze -e -P out/target/product/<board>/root/sepolicy

    Display all type pairs that are "equivalent", i.e. they are
    identical with respect to allow rules, including indirect allow
    rules via attributes and default-enabled conditional rules
    (i.e. default boolean values yield a true conditional expression).

    Equivalent types are candidates for being coalesced into a single
    type.  However, there may be legitimate reasons for them to remain
    separate, for example: - the types may differ in a respect not
    included in the current analysis, such as default-disabled
    conditional rules, audit-related rules (auditallow or dontaudit),
    default type transitions, or constraints (e.g. mls), or - the
    current policy may be overly permissive with respect to one or the
    other of the types and thus the correct action may be to tighten
    access to one or the other rather than coalescing them together,
    or - the domains that would in fact have different accesses to the
    types may not yet be defined or may be unconfined in the policy
    you are analyzing.

    TYPE DIFFERENCE
    sepolicy-analyze -d -P out/target/product/<board>/root/sepolicy

    Display type pairs that differ and the first difference found
    between the two types.  This may be used in looking for similar
    types that are not equivalent but may be candidates for coalescing.

    DUPLICATE ALLOW RULES
    sepolicy-analyze -D -P out/target/product/<board>/root/sepolicy

    Displays duplicate allow rules, i.e. pairs of allow rules that
    grant the same permissions where one allow rule is written
    directly in terms of individual types and the other is written in
    terms of attributes associated with those same types.  The rule
    with individual types is a candidate for removal.  The rule with
    individual types may be directly represented in the source policy
    or may be a result of expansion of a type negation (e.g. domain
    -foo -bar is expanded to individual allow rules by the policy
    compiler).  Domains with unconfineddomain will typically have such
    duplicate rules as a natural side effect and can be ignored.