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