code-intelligence.com/cifuzz@v0.40.0/third-party/minijail/tools/README.md (about)

     1  # Minijail tools
     2  
     3  ## generate_seccomp_policy.py
     4  
     5  This script lets you build a Minijail seccomp-bpf filter from strace output.
     6  This is very useful if the process that is traced has a fairly tight working
     7  domain, and it can be traced in a few scenarios that will exercise all of the
     8  needed syscalls. In particular, you should always make sure that failure cases
     9  are also exercised to account for calls to `abort(2)`.
    10  
    11  If `libminijail` or `minijail0` are used with preloading (the default with
    12  dynamically-linked executables), the first few system calls after the first call
    13  to `execve(2)` might not be needed, since the seccomp-bpf filter is installed
    14  after that point in a sandboxed process.
    15  
    16  ### Sample usage
    17  
    18  ```shell
    19  strace -f -e raw=all -o strace.txt -- <program>
    20  ./tools/generate_seccomp_policy.py strace.txt > <program>.policy
    21  ```
    22  
    23  ### Using linux audit logs to generate policy
    24  
    25  *** note
    26  **NOTE**: Certain syscalls made by `minijail0` may be misattributed to the
    27  sandboxed binary and may result in a policy that is overly-permissive.
    28  Please pay some extra attention when manually reviewing the allowable args for
    29  these syscalls: `ioctl`, `socket`, `prctl`, `mmap`, `mprotect`, and `mmap2`.
    30  ***
    31  
    32  Linux kernel v4.14+ support `SECCOMP_RET_LOG`. This allows minijail to log
    33  syscalls via the [audit subsystem][1] (Redhat has a nice overview [here][2])
    34  instead of blocking them. One caveat of this approach is that `SECCOMP_RET_LOG`
    35  does not log syscall arguments for finer grained filtering.
    36  The audit subsystem itself has a mechanism to log all syscalls. Though a
    37  `SYSCALL` event is more voluminous than a corresponding `SECCOMP` event.
    38  We employ here a combination of both techniques. We rely on `SECCOMP` for all
    39  except the syscalls for which we want finer grained filtering.
    40  
    41  Note that this requires python3 bindings for `auparse` which are generally
    42  available in distro packages named `python3-audit` or `python-audit`.
    43  
    44  #### Per-boot setup of audit rules on DUT
    45  
    46  Set up `audit` rules and an empty seccomp policy for later use. This can be
    47  done in the `pre-start` section of your upstart conf.
    48  
    49  `$UID` is the uid for your process. Using root will lead to logspam.
    50  
    51  As mentioned above, these extra audit rules enable `SYSCALL` auditing which
    52  in turn lets the tool inspect arguments for a pre-selected subset of syscalls.
    53  The list of syscalls here matches the list of keys  in `arg_inspection`.
    54  
    55  ```shell
    56  for arch in b32 b64; do
    57    auditctl -a exit,always -F uid=$UID -F arch=$arch -S ioctl -S socket \
    58             -S prctl -S mmap -S mprotect \
    59             $([ "$arch" = "b32" ] && echo "-S mmap2") -c
    60  done
    61  touch /tmp/empty.policy
    62  ```
    63  
    64  #### Run your program under minijail with an empty policy
    65  
    66  Again, this can be done via your upstart conf. Just be sure to stimulate all
    67  corner cases, error conditions, etc for comprehensive coverage.
    68  
    69  ```shell
    70  minijail0 -u $UID -g $GID -L -S /tmp/empty.policy -- <program>
    71  ```
    72  
    73  #### Generate policy using the audit.log
    74  
    75  ```shell
    76  ./tools/generate_seccomp_policy.py --audit-comm $PROGRAM_NAME audit.log \
    77      > $PROGRAM_NAME.policy
    78  ```
    79  
    80  Note that the tool can also consume multiple audit logs and/or strace traces to
    81  produce one unified policy.
    82  
    83  ## compile_seccomp_policy.py
    84  
    85  An external seccomp-bpf compiler that is documented [here][3]. This uses a
    86  slightly different syntax and generates highly-optimized BPF binaries that can
    87  be provided to `minijail0`'s `--seccomp-bpf-binary` or `libminijail`'s
    88  `minijail_set_secomp_filters()`. This requires the existence of an
    89  architecture-specific `constants.json` file that contains the mapping of syscall
    90  names to numbers, the values of any compile-time constants that could be used to
    91  simplify the parameter declaration for filters (like `O_RDONLY` and any other
    92  constant defined in typical headers in `/usr/include`).
    93  
    94  Policy files can also include references to frequency files, which enable
    95  profile-guided optimization of the generated BPF code.
    96  
    97  The generated BPF code can be analyzed using
    98  [libseccomp](https://github.com/seccomp/libseccomp)'s `tools/scmp_bpf_disasm`.
    99  
   100  ### Sample usage
   101  
   102  ```shell
   103  make minijail0 constants.json
   104  
   105  # Create the .policy file using the syntax described in the documentation.
   106  cat > test/seccomp.policy <<EOF
   107  read: allow
   108  write: allow
   109  rt_sigreturn: allow
   110  exit: allow
   111  EOF
   112  
   113  # Compile the .policy file into a .bpf filter
   114  ./tools/compile_seccomp_policy.py test/seccomp.policy test/seccomp.bpf
   115  
   116  # Load the filter to sandbox your program.
   117  ./minijail0 --seccomp-bpf-binary=test/seccomp.bpf -- <program>
   118  ```
   119  
   120  ## generate_constants_json.py
   121  
   122  This script generates the `constants.json` file from LLVM IR assembly files.
   123  This makes it easier to generate architecture-specific `constants.json` files at
   124  build-time.
   125  
   126  [1]: https://people.redhat.com/sgrubb/audit/
   127  [2]: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/chap-system_auditing
   128  [3]: https://docs.google.com/document/d/e/2PACX-1vQOeYLWmJJrRWvglnMo5cynkUe0gZ9wVsndLLePkJg6dfUXSOUWoveBBeY3u5nQMlEU4dt_vRgj0ifR/pub