Add a README.md to the tools/ directory am: a6b88f1927 am: 14bc30e4aa am: b61aa9afa3
Change-Id: Ibab57c2ed9ba8d006dd0a33ec5884a4244f216f7
diff --git a/README.md b/README.md
index 9933c9d..914c867 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,10 @@
See the [RELEASE.md](./RELEASE.md) document for more details.
+## Additional tools
+
+See the [tools/README.md](./tools/README.md) document for more details.
+
## Contact
We've got a couple of contact points.
diff --git a/tools/README.md b/tools/README.md
new file mode 100644
index 0000000..0a15a26
--- /dev/null
+++ b/tools/README.md
@@ -0,0 +1,66 @@
+# Minijail tools
+
+## generate_seccomp_policy.py
+
+This script lets you build a Minijail seccomp-bpf filter from strace output.
+This is very useful if the process that is traced has a fairly tight working
+domain, and it can be traced in a few scenarios that will exercise all of the
+needed syscalls. In particular, you should always make sure that failure cases
+are also exercised to account for calls to `abort(2)`.
+
+If `libminijail` or `minijail0` are used with preloading (the default with
+dynamically-linked executables), the first few system calls after the first call
+to `execve(2)` might not be needed, since the seccomp-bpf filter is installed
+after that point in a sandboxed process.
+
+### Sample usage
+
+```shell
+strace -f -e raw=all -o strace.txt -- <program>
+./tools/generate_seccomp_policy.py strace.txt > <program>.policy
+```
+
+## compile_seccomp_policy.py
+
+An external seccomp-bpf compiler that is documented [here][1]. This uses a
+slightly different syntax and generates highly-optimized BPF binaries that can
+be provided to `minijail0`'s `--seccomp-bpf-binary` or `libminijail`'s
+`minijail_set_secomp_filters()`. This requires the existence of an
+architecture-specific `constants.json` file that contains the mapping of syscall
+names to numbers, the values of any compile-time constants that could be used to
+simplify the parameter declaration for filters (like `O_RDONLY` and any other
+constant defined in typical headers in `/usr/include`).
+
+Policy files can also include references to frequency files, which enable
+profile-guided optimization of the generated BPF code.
+
+The generated BPF code can be analyzed using
+[libseccomp](https://github.com/seccomp/libseccomp)'s `tools/scmp_bpf_disasm`.
+
+*** note
+**Note:** This tool currently only works for native builds, since the generation
+of `constants.json` uses the same compiler toolchain that is used to build
+`minijail0` and `libminijail`.
+***
+
+### Sample usage
+
+```shell
+make minijail0 constants.json
+
+# Create the .policy file using the syntax described in the documentation.
+cat > test/seccomp.policy <<EOF
+read: allow
+write: allow
+rt_sigreturn: allow
+exit: allow
+EOF
+
+# Compile the .policy file into a .bpf filter
+./tools/compile_seccomp_policy.py test/seccomp.policy test/seccomp.bpf
+
+# Load the filter to sandbox your program.
+./minijail0 --seccomp-bpf-binary=test/seccomp.bpf -- <program>
+```
+
+[1]: https://docs.google.com/document/d/e/2PACX-1vQOeYLWmJJrRWvglnMo5cynkUe0gZ9wVsndLLePkJg6dfUXSOUWoveBBeY3u5nQMlEU4dt_vRgj0ifR/pub