seccomp-tools 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc7a6ded95dadf7826ae07868793839e0ffa417ed936ae8461ff5bb6b59ff135
-  data.tar.gz: 82a0f811819137309ea22d68fe21fec5d48aad7b96f142b981c57478146a47af
+  metadata.gz: 74e6aff6030647eb1f380b641cfe55b58717a22c3e5dc2a0187e6da9b74263e3
+  data.tar.gz: 2c0a322b81f7d4b950686dc5c72d565cad5e3a278f47a442d7271c0ac4e03417
 SHA512:
-  metadata.gz: 4d630e759687a7641d8cdeb4012a433a4fedc67c2f3e322c4cfaf041428e1199a2c46dd5db50c36a00a79a5b203f648f90345ac4ad6654b0cba93344c6737158
-  data.tar.gz: 23a441eb5cf55d3eb18a91a20e4b23a242e7b9b381dab81457ab3b087d9c53847e2d47be161c11305f213e629a23403b806e1a8e31e89adbd90443d1f79ef301
+  metadata.gz: 2a8793275d9dd37fc1ed1dc0abc67a07c9aca17f9aa4b03f26c2a0ce31b27861b64f0e85608588b47841a644ae98cb4b4c34460eef8a37c5ca3a6fa0664fbb01
+  data.tar.gz: f7ab61c28a821022989c3d1ef31ab9fb966e132d6211f861339d64bf9cdffe451f970d932a4d47a890220914bf8451a0fb35afdaca191391a6b0bea4d26f9227

data/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.7.0] - 2026-08-01
+
+### Added
+- `completion` command: print a shell completion script for bash, zsh or fish (e.g. `eval "$(seccomp-tools completion bash)"`).
+- `explain` command: summarize a whole filter as a per-action policy (which syscalls end in ALLOW/KILL/ERRNO, and under what argument constraints).
+- `audit` command: scan a filter for weaknesses and escape routes (missing architecture or x32 guard, permissive default, equivalent-syscall gaps, an open/read/write chain, dangerous syscalls reachable as ALLOW), with a `--format json` output.
+- RISC-V 64 (`riscv64`) architecture support across dump, disasm, asm and emu.
+- `dump --timeout SEC` to bound how long a traced program runs.
+- `dump` now handles `SECCOMP_MODE_STRICT`, emitting the equivalent filter (strict mode installs no BPF of its own).
+
+### Changed
+- disasm, emu and asm now share a symbolic BPF execution engine; disasm names arguments by the architecture inferred from the filter rather than the one declared on the command line.
+- `dump --pid` detects the target process's architecture (from its ELF header) instead of assuming the host's, so syscalls of a process built for another architecture are labelled correctly.
+- `dump`'s `-c`/`--sh-exec` now takes precedence over a positional executable.
+- `dump` warns when it finds no seccomp filter instead of printing nothing.
+- Commands that need an architecture now fail with a clear message when the host architecture cannot be detected and no `--arch` was given, instead of erroring deep inside a syscall-table lookup.
+- Colorized syscall names, gave warnings and info messages a color, and wrapped audit findings to 120 columns.
+
+### Fixed
+- Corrected 64-bit argument word order on big-endian (s390x) targets.
+- Fixed the disassembly of seccomp return actions via a shared action-label decoder.
+- The emulator now models division by zero as the kernel does (aborting the program with a kill) instead of raising.
+- Fixed a Bundler error on Ruby head.
+
+## [1.6.2] - 2025-11-23
+
+### Added
+- Ruby 3.4 support.
+- `-i`/`--ip` option to set the instruction pointer in emulation mode.
+
+### Changed
+- Raised the minimum Ruby version to 3.1 (dropped 3.0).
+- Declared `logger` as an explicit dependency (it is no longer a default gem).
+
+### Fixed
+- Bundled the license file and a missing runtime dependency in the gem.
+
+## [1.6.1] - 2023-12-25
+
+### Fixed
+- Stopped raising an error on a long direct jump.
+- Fixed wrong decompilation when the compiler optimized two branches to the same jump target.
+
+## [1.6.0] - 2023-09-19
+
+### Added
+- Rewrote the `asm` assembler on a yacc (racc) based grammar, supporting a more flexible and intuitive syntax.
+- `disasm --asm-able` to emit output that is valid input for `asm`.
+- `disasm --no-bpf` to hide the raw BPF bytes.
+- `<arch>.<syscall>` syntax in disasm and asm.
+- Support for `!` (bang) in `if` conditions.
+- Dumping seccomp filters on s390x.
+
+### Changed
+- Raise an error when a jump distance exceeds 255.
+- Sped up the assembler's scanner.
+
+## [1.5.0] - 2021-03-07
+
+### Added
+- x32 syscall support.
+- Dumping seccomp filters on aarch64.
+- Additional seccomp return actions.
+- Syscall-name aliases matching `ausyscall`.
+
+### Changed
+- Skip the (Linux-only) dump functionality gracefully when installing on macOS.
+- Migrated CI from Travis to GitHub Actions.
+
+## [1.4.0] - 2020-02-16
+
+### Added
+- Dumping seccomp filters from an existing process (`dump --pid`).
+- `A = -A` (negate) assembler syntax.
+- An internal logger.
+
+### Changed
+- Upgraded dependencies and dropped Ruby 2.3.
+
+## [1.3.0] - 2019-06-23
+
+### Added
+- Display of syscall arguments in the disassembly.
+- Support a syscall name (not just a number) in the emulator.
+- `c_source` and x86 `assembly` output formats for `asm`.
+- Assembler support for `mem[]`, `len`, and absolute jumps.
+- `sys_seccomp` on i386.
+
+### Fixed
+- A wrong regular expression in the tokenizer, and several reported bugs (#53, #54, #55).
+
+### Changed
+- Dropped an end-of-life Ruby version (2.2).
+
+## [1.2.0] - 2018-04-05
+
+### Added
+- `KILL_PROCESS` return action.
+- `ARCH_X86_64` in the assembler.
+- The `seccomp` syscall introduced in Linux 3.17.
+
+## [1.1.1] - 2017-12-01
+
+### Added
+- Show `errno` in the disassembly of an ERRNO return.
+- Assembler support for `st`/`stx`.
+
+### Fixed
+- `lsh`/`rsh` in the assembler.
+
+### Changed
+- More meaningful error messages.
+
+## [1.1.0] - 2017-09-29
+
+### Added
+- `asm` command: a seccomp BPF assembler.
+
+## [1.0.0] - 2017-06-10
+
+### Added
+- `emu` command: emulate seccomp rules against a hypothetical syscall.
+
+### Fixed
+- Branch handling in the disassembler.
+
+## [0.1.0] - 2017-06-08
+
+### Added
+- Initial release: the `dump` and `disasm` commands, ptrace-based dumping with `--limit` and `--output`, and i386 support.
+
+[Unreleased]: https://github.com/david942j/seccomp-tools/compare/v1.7.0...HEAD
+[1.7.0]: https://github.com/david942j/seccomp-tools/compare/v1.6.2...v1.7.0
+[1.6.2]: https://github.com/david942j/seccomp-tools/compare/v1.6.1...v1.6.2
+[1.6.1]: https://github.com/david942j/seccomp-tools/compare/v1.6.0...v1.6.1
+[1.6.0]: https://github.com/david942j/seccomp-tools/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/david942j/seccomp-tools/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/david942j/seccomp-tools/compare/1.3.0...v1.4.0
+[1.3.0]: https://github.com/david942j/seccomp-tools/compare/v1.2.0...1.3.0
+[1.2.0]: https://github.com/david942j/seccomp-tools/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/david942j/seccomp-tools/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/david942j/seccomp-tools/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/david942j/seccomp-tools/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/david942j/seccomp-tools/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,26 +1,31 @@
+[![Downloads](https://img.shields.io/gem/dt/seccomp-tools)](https://rubygems.org/gems/seccomp-tools)
+
+
+[![Gem Version](https://badge.fury.io/rb/seccomp-tools.svg)](https://badge.fury.io/rb/seccomp-tools)
 [![Build Status](https://github.com/david942j/seccomp-tools/workflows/build/badge.svg)](https://github.com/david942j/seccomp-tools/actions)
-[![Code Climate](https://codeclimate.com/github/david942j/seccomp-tools/badges/gpa.svg)](https://codeclimate.com/github/david942j/seccomp-tools)
-[![Issue Count](https://codeclimate.com/github/david942j/seccomp-tools/badges/issue_count.svg)](https://codeclimate.com/github/david942j/seccomp-tools)
-[![Test Coverage](https://codeclimate.com/github/david942j/seccomp-tools/badges/coverage.svg)](https://codeclimate.com/github/david942j/seccomp-tools/coverage)
+[![Maintainability](https://qlty.sh/gh/david942j/projects/seccomp-tools/maintainability.svg)](https://qlty.sh/gh/david942j/projects/seccomp-tools)
+[![Code Coverage](https://qlty.sh/gh/david942j/projects/seccomp-tools/coverage.svg)](https://qlty.sh/gh/david942j/projects/seccomp-tools)
 [![Inline docs](https://inch-ci.org/github/david942j/seccomp-tools.svg?branch=master)](https://inch-ci.org/github/david942j/seccomp-tools)
 [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/github/david942j/seccomp-tools/)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](http://choosealicense.com/licenses/mit/)
 
 # Seccomp Tools
-Provide powerful tools for seccomp analysis.
+Powerful tools for seccomp analysis.
 
-This project targets to (but is not limited to) analyze seccomp sandbox in CTF pwn challenges.
-Some features might be CTF-specific, but also useful for analyzing seccomp of real cases.
+This project is aimed primarily (but not exclusively) at analyzing seccomp sandboxes in CTF pwn challenges.
+Some features are CTF-specific, but they're just as useful for analyzing real-world seccomp filters.
 
 ## Features
-* Dump - Automatically dumps seccomp BPF from execution file(s).
-* Disasm - Converts seccomp BPF to a human readable format.
+* Dump - Automatically dumps seccomp BPF from executables.
+* Disasm - Converts seccomp BPF to a human-readable format.
   - With simple decompilation.
   - With syscall names and arguments whenever possible.
   - Colorful!
-* Asm - Makes writing seccomp rules similar to writing codes.
+* Asm - Makes writing seccomp rules as easy as writing code.
 * Emu - Emulates seccomp rules.
-* Supports multi-architecture.
+* Explain - Summarizes a filter as a per-action policy (which syscalls are allowed/killed, and when).
+* Audit - Scans a filter for weaknesses and escape routes (missing arch/x32 guards, dangerous syscalls, ...).
+* Multi-architecture support.
 
 ## Installation
 
@@ -29,11 +34,11 @@ Available on RubyGems.org!
 $ gem install seccomp-tools
 ```
 
-If you failed when compiling, try:
+If compilation fails, try:
 ```
-sudo apt install gcc ruby-dev
+sudo apt install gcc ruby-dev make
 ```
-and install seccomp-tools again.
+then install seccomp-tools again.
 
 ## Command Line Interface
 
@@ -46,40 +51,44 @@ $ seccomp-tools --help
 # List of commands:
 #
 # 	asm	Seccomp bpf assembler.
+# 	audit	Assess a seccomp filter for weaknesses and escape routes.
+# 	completion	Print a shell completion script.
 # 	disasm	Disassemble seccomp bpf.
-# 	dump	Automatically dump seccomp bpf from execution file(s).
+# 	dump	Automatically dump seccomp bpf from executable(s).
 # 	emu	Emulate seccomp rules.
+# 	explain	Summarize a seccomp filter as a per-action policy.
 #
 # See 'seccomp-tools <command> --help' to read about a specific subcommand.
 
 $ seccomp-tools dump --help
-# dump - Automatically dump seccomp bpf from execution file(s).
-# NOTE : This function is only available on Linux.
+# dump - Automatically dump seccomp bpf from executable(s).
+# NOTE: This command is only available on Linux.
 #
-# Usage: seccomp-tools dump [exec] [options]
-#     -c, --sh-exec <command>          Executes the given command (via sh).
-#                                      Use this option if want to pass arguments or do pipe things to the execution file.
-#                                      e.g. use `-c "./bin > /dev/null"` to dump seccomp without being mixed with stdout.
+# Usage: seccomp-tools dump [EXEC] [options]
+#     -c, --sh-exec <command>          Executes the given command (via sh) and dumps its seccomp.
+#                                      Use this to pass arguments or pipe things to the executable.
+#                                      e.g. use `-c "./bin > /dev/null"` to keep the program output out of the result.
+#                                      Takes precedence over the positional argument.
+#     -l, --limit LIMIT                Dump only the first LIMIT installed filters.
+#                                      Only meaningful when the input is an executable or --pid. Default: 1
+#                                      An executable is killed once it reaches LIMIT.
+#     -p, --pid PID                    Dump the seccomp filters installed on an existing process.
+#                                      You must have CAP_SYS_ADMIN (e.g. be root) to use this option.
+#     -t, --timeout SEC                Timeout (seconds) for the execution. Default: no timeout
+#                                      This option is ignored when --pid is given.
 #     -f, --format FORMAT              Output format. FORMAT can only be one of <disasm|raw|inspect>.
 #                                      Default: disasm
-#     -l, --limit LIMIT                Limit the number of calling "prctl(PR_SET_SECCOMP)".
-#                                      The target process will be killed whenever its calling times reaches LIMIT.
-#                                      Default: 1
-#     -o, --output FILE                Output result into FILE instead of stdout.
+#     -o, --output FILE                Write output to FILE instead of stdout.
 #                                      If multiple seccomp syscalls have been invoked (see --limit),
-#                                      results will be written to FILE, FILE_1, FILE_2.. etc.
-#                                      For example, "--output out.bpf" and the output files are out.bpf, out_1.bpf, ...
-#     -p, --pid PID                    Dump installed seccomp filters of the existing process.
-#                                      You must have CAP_SYS_ADMIN (e.g. be root) in order to use this option.
-
+#                                      results are written to FILE, FILE_1, FILE_2, etc.
+#                                      For example, with "--output out.bpf" the output files are out.bpf, out_1.bpf, ...
 ```
 
 ### dump
 
-Dumps the seccomp BPF from an execution file.
-This work is done by utilizing the `ptrace` syscall.
+Dumps the seccomp BPF from an executable, using the `ptrace` syscall.
 
-NOTICE: beware of the execution file will be executed.
+NOTE: the target executable is actually run, so be careful with untrusted binaries.
 ```bash
 $ file spec/binary/twctf-2016-diary
 # spec/binary/twctf-2016-diary: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.24, BuildID[sha1]=3648e29153ac0259a0b7c3e25537a5334f50107f, not stripped
@@ -124,7 +133,7 @@ $ seccomp-tools dump spec/binary/twctf-2016-diary -f raw | xxd
 
 ### disasm
 
-Disassembles the seccomp from raw BPF.
+Disassembles raw seccomp BPF into a readable format.
 ```bash
 $ xxd spec/data/twctf-2016-diary.bpf | head -n 3
 # 00000000: 2000 0000 0000 0000 1500 0001 0200 0000   ...............
@@ -157,21 +166,22 @@ $ seccomp-tools disasm spec/data/twctf-2016-diary.bpf
 
 ### asm
 
-Assembles the seccomp rules into raw bytes.
-It's very useful when one wants to write custom seccomp rules.
+Assembles seccomp rules into raw bytes.
+Useful when you want to write your own seccomp rules.
 
-Supports labels for jumping and uses syscall names directly. See examples below.
+Supports jump labels and syscall names. See the examples below.
 ```bash
 $ seccomp-tools asm
 # asm - Seccomp bpf assembler.
 #
 # Usage: seccomp-tools asm IN_FILE [options]
-#     -o, --output FILE                Output result into FILE instead of stdout.
+#     -o, --output FILE                Write output to FILE instead of stdout.
 #     -f, --format FORMAT              Output format. FORMAT can only be one of <inspect|raw|c_array|c_source|assembly>.
 #                                      Default: inspect
 #     -a, --arch ARCH                  Specify architecture.
-#                                      Supported architectures are <aarch64|amd64|i386|s390x>.
-#                                      Default: amd64
+#                                      Supported architectures are <aarch64|amd64|i386|riscv64|s390x>.
+#                                      Default: auto-detected from the host machine.
+#                                      Set it when the filter targets an architecture other than the host.
 
 # Input file for asm
 $ cat spec/data/libseccomp.asm
@@ -259,7 +269,7 @@ $ seccomp-tools asm spec/data/libseccomp.asm -f raw | seccomp-tools disasm -
 
 ```
 
-Since v1.6.0 [not released yet], `asm` has switched to using a yacc-based syntax parser, hence supports more flexible and intuitive syntax!
+Since v1.6.0 [not released yet], `asm` has switched to a yacc-based parser, which allows a more flexible and intuitive syntax!
 
 ```bash
 $ cat spec/data/example.asm
@@ -300,7 +310,7 @@ $ seccomp-tools asm spec/data/example.asm -f raw | seccomp-tools disasm -
 
 ```
 
-The output of `seccomp-tools disasm <file> --asm-able` is a valid input of `asm`:
+The output of `seccomp-tools disasm <file> --asm-able` is valid input for `asm`:
 ```bash
 $ seccomp-tools disasm spec/data/x32.bpf --asm-able
 # 0000: A = arch
@@ -345,9 +355,11 @@ $ seccomp-tools emu --help
 #
 # Usage: seccomp-tools emu [options] BPF_FILE [sys_nr [arg0 [arg1 ... arg5]]]
 #     -a, --arch ARCH                  Specify architecture.
-#                                      Supported architectures are <aarch64|amd64|i386|s390x>.
-#                                      Default: amd64
+#                                      Supported architectures are <aarch64|amd64|i386|riscv64|s390x>.
+#                                      Default: auto-detected from the host machine.
+#                                      Set it when the filter targets an architecture other than the host.
 #     -q, --[no-]quiet                 Run quietly, only show emulation result.
+#     -i, --ip=VAL                     Set instruction pointer.
 
 $ seccomp-tools emu spec/data/libseccomp.bpf write 0x3
 #  line  CODE  JT   JF      K
@@ -368,6 +380,214 @@ $ seccomp-tools emu spec/data/libseccomp.bpf write 0x3
 
 ```
 
+### Explain
+
+Summarizes a whole filter as a per-action policy: which syscalls end in `ALLOW`, `KILL`, `ERRNO`, etc.,
+and under what argument constraints. The input can be a dumped BPF file, an executable (its seccomp is
+dumped first, like `dump`), or a running process via `--pid`.
+```bash
+$ seccomp-tools explain --help
+# explain - Summarize a seccomp filter as a per-action policy.
+#
+# Usage: seccomp-tools explain [options] [BPF_FILE|EXEC]
+#     -c, --sh-exec <command>          Executes the given command (via sh) and explains its seccomp.
+#                                      Use this to pass arguments or pipe things to the executable.
+#                                      e.g. use `-c "./bin > /dev/null"` to keep the program output out of the result.
+#                                      Takes precedence over the positional argument.
+#     -l, --limit LIMIT                Explain only the first LIMIT installed filters.
+#                                      Only meaningful when the input is an executable or --pid. Default: 1
+#                                      An executable is killed once it reaches LIMIT.
+#     -p, --pid PID                    Explain the seccomp filters installed on an existing process.
+#                                      You must have CAP_SYS_ADMIN (e.g. be root) to use this option.
+#     -t, --timeout SEC                Timeout (seconds) for the execution. Default: no timeout
+#                                      This option is ignored when --pid is given.
+#     -a, --arch ARCH                  Specify architecture.
+#                                      Supported architectures are <aarch64|amd64|i386|riscv64|s390x>.
+#                                      Default: auto-detected from the host machine.
+#                                      Set it when the filter targets an architecture other than the host.
+#                                      With an executable or --pid the architecture is auto-detected instead.
+
+$ seccomp-tools explain spec/data/libseccomp.bpf -a amd64
+# Seccomp policy for spec/data/libseccomp.bpf
+#
+# Architecture: amd64
+#
+#   ALLOW:
+#     write, close, dup, exit
+#
+#   ERRNO(5):
+#     <default> (any other syscall)
+#
+#   KILL:
+#     sys_number >= 0x40000000  (x32 ABI)
+#
+# Other architectures: KILL
+```
+
+A more involved example - the 0CTF/TCTF 2023 "Nothing is True" filter, which has separate 32/64-bit
+allowlists and argument checks on `open`, `mmap` and `execve`:
+```bash
+$ seccomp-tools explain spec/data/tctf-2023-nothing-is-true.bpf -a amd64
+# Seccomp policy for spec/data/tctf-2023-nothing-is-true.bpf
+#
+# Architecture: i386
+#
+#   ALLOW:
+#     exit, read, write, brk, mmap, munmap, exit_group
+#
+#   KILL:
+#     <default> (any other syscall)
+#
+# Architecture: amd64
+#
+#   ALLOW:
+#     close, munmap, brk, exit, exit_group
+#     open when filename == 0x31337 && flags == 0x0
+#     mmap when prot == 0x2
+#     execve when filename == 0x7ffea12f7d0e
+#
+#   KILL:
+#     sys_number >= 0x40000000  (x32 ABI)
+#     <default> (any other syscall)
+#
+# Other architectures: KILL
+```
+
+### Audit
+
+Scans a filter for weaknesses and likely escape routes - a missing architecture or x32 guard, a
+permissive (denylist) default, equivalent-syscall gaps (e.g. `execve` blocked but `execveat` not),
+an open/read/write chain, or dangerous syscalls reachable as `ALLOW` - and reports each with a
+severity. It runs on every supported architecture (architecture-specific quirks like amd64's x32 are
+applied only where they exist), and takes the same input as `explain` (a BPF file, an executable, or
+`--pid`).
+```bash
+$ seccomp-tools audit --help
+# audit - Assess a seccomp filter for weaknesses and escape routes.
+#
+# Usage: seccomp-tools audit [options] [BPF_FILE|EXEC]
+#     -c, --sh-exec <command>          Executes the given command (via sh) and audits its seccomp.
+#                                      Use this to pass arguments or pipe things to the executable.
+#                                      e.g. use `-c "./bin > /dev/null"` to keep the program output out of the result.
+#                                      Takes precedence over the positional argument.
+#     -l, --limit LIMIT                Audit only the first LIMIT installed filters.
+#                                      Only meaningful when the input is an executable or --pid. Default: 1
+#                                      An executable is killed once it reaches LIMIT.
+#     -p, --pid PID                    Audit the seccomp filters installed on an existing process.
+#                                      You must have CAP_SYS_ADMIN (e.g. be root) to use this option.
+#     -t, --timeout SEC                Timeout (seconds) for the execution. Default: no timeout
+#                                      This option is ignored when --pid is given.
+#     -a, --arch ARCH                  Specify architecture.
+#                                      Supported architectures are <aarch64|amd64|i386|riscv64|s390x>.
+#                                      Default: auto-detected from the host machine.
+#                                      Set it when the filter targets an architecture other than the host.
+#                                      With an executable or --pid the architecture is auto-detected instead.
+#     -f, --format FORMAT              Output format, one of <human|json>.
+#                                      Default: human
+```
+
+Auditing a denylist with several escape routes (the TokyoWesterns CTF 2016 "diary" filter):
+```bash
+$ seccomp-tools audit spec/data/twctf-2016-diary.bpf -a amd64
+# Seccomp audit of spec/data/twctf-2016-diary.bpf
+# Architectures: amd64
+#
+# [HIGH] Architecture is never validated
+#     The filter checks syscall numbers without ever comparing data[4] (arch). Numbers mean different syscalls under
+#     another AUDIT_ARCH, so the checks can be dodged by invoking through a different ABI (e.g. i386 numbering on amd64).
+#     fix:  Compare data[4] against your AUDIT_ARCH_* and KILL every architecture you do not explicitly handle.
+#
+# [HIGH] process_vm_readv is allowed (amd64)
+#     process_vm_readv reaches ALLOW - read another process's memory.
+#     fix:  Block process_vm_readv unless the program genuinely needs it.
+#
+# [HIGH] process_vm_writev is allowed (amd64)
+#     process_vm_writev reaches ALLOW - write another process's memory.
+#     fix:  Block process_vm_writev unless the program genuinely needs it.
+#
+# [HIGH] ptrace is allowed (amd64)
+#     ptrace reaches ALLOW - inspect/inject into other processes.
+#     fix:  Block ptrace unless the program genuinely needs it.
+#
+# [HIGH] Default action is ALLOW (denylist) (amd64)
+#     Any syscall the filter does not explicitly block is allowed; a denylist is bypassable by any syscall the author
+#     overlooked.
+#     fix:  Use an allowlist: default to KILL/ERRNO and permit only the needed syscalls.
+#
+# [HIGH] x32 ABI is not guarded (amd64)
+#     Syscalls blocked by their native number are reachable via their x32 number (nr | 0x40000000): open, clone, fork,
+#     vfork, execve, creat, openat, execveat.
+#     fix:  After the arch check, KILL when sys_number >= 0x40000000 (or jset 0x40000000).
+#
+# [MEDIUM] connect is allowed (amd64)
+#     connect reaches ALLOW - network access (exfiltration).
+#     fix:  Block connect unless the program genuinely needs it.
+#
+# [MEDIUM] socket is allowed (amd64)
+#     socket reaches ALLOW - network access (exfiltration).
+#     fix:  Block socket unless the program genuinely needs it.
+```
+
+Use `--format json` for CI or tooling:
+```bash
+$ seccomp-tools audit spec/data/gctf-2019-quals-caas.bpf -a amd64 -f json
+# {
+#   "stacked_filters": 1,
+#   "reports": [
+#     {
+#       "source": "spec/data/gctf-2019-quals-caas.bpf",
+#       "arches": [
+#         "amd64"
+#       ],
+#       "truncated": false,
+#       "findings": [
+#         {
+#           "id": "dangerous-allow",
+#           "severity": "medium",
+#           "title": "connect is allowed",
+#           "detail": "connect reaches ALLOW - network access (exfiltration).",
+#           "arch": "amd64",
+#           "syscalls": [
+#             "connect"
+#           ],
+#           "condition": null,
+#           "remediation": "Block connect unless the program genuinely needs it."
+#         },
+#         {
+#           "id": "dangerous-allow",
+#           "severity": "medium",
+#           "title": "socket is allowed",
+#           "detail": "socket reaches ALLOW - network access (exfiltration).",
+#           "arch": "amd64",
+#           "syscalls": [
+#             "socket"
+#           ],
+#           "condition": "family == 0x2 && type == 0x1 && protocol == 0x0",
+#           "remediation": "Block socket unless the program genuinely needs it."
+#         }
+#       ]
+#     }
+#   ]
+# }
+```
+
+## Shell Completion
+
+`seccomp-tools completion <bash|zsh|fish>` prints a completion script for the given shell. Load it from your shell's startup file:
+
+```bash
+# bash (~/.bashrc)
+eval "$(seccomp-tools completion bash)"
+
+# zsh (~/.zshrc, after `compinit`)
+eval "$(seccomp-tools completion zsh)"
+
+# fish (~/.config/fish/config.fish)
+seccomp-tools completion fish | source
+```
+
+To avoid the startup cost of evaluating it every time, write the script to the directory your shell loads completions from instead, e.g. `seccomp-tools completion zsh > "${fpath[1]}/_seccomp-tools"`.
+
 ## Screenshots
 
 ### Dump
@@ -385,12 +605,13 @@ $ seccomp-tools emu spec/data/libseccomp.bpf write 0x3
 - [x] x86
 - [x] arm64 (@saagarjha)
 - [x] s390x (@iii-i)
+- [x] riscv64
 
-Pull Requests of adding more architectures support are welcome!
+Pull requests adding support for more architectures are welcome!
 
 ## Development
 
-I recommend to use [rbenv](https://github.com/rbenv/rbenv) for your Ruby environment.
+I recommend using [rbenv](https://github.com/rbenv/rbenv) to manage your Ruby environment.
 
 ### Setup
 
@@ -409,4 +630,4 @@ I recommend to use [rbenv](https://github.com/rbenv/rbenv) for your Ruby environ
 
 Any suggestions or feature requests are welcome!
 Feel free to file issues or send pull requests.
-And, if you like this work, I'll be happy to be [starred](https://github.com/david942j/seccomp-tools/stargazers) :grimacing:
+And if you like this project, consider giving it a [star](https://github.com/david942j/seccomp-tools/stargazers) :grimacing: