david942j/seccomp-tools

Seccomp-tools is a Ruby-based toolkit for analyzing, constructing, and auditing Linux seccomp BPF filters. It provides capabilities to disassemble raw bytecode into human-readable assembly, assemble high-level rules into bytecode, and emulate or symbolically execute filters to verify their behavior. The system also includes an audit engine to detect security weaknesses and a dumper to extract active filters from running processes, supporting multiple CPU architectures.

17 changes.

This period established the seccomp-tools Ruby gem, introducing a modular CLI and core libraries for assembling, disassembling, and auditing seccomp BPF filters. Key features included a new audit engine, an emulator for filter simulation, and a C extension for process-level filter inspection via ptrace. The work also involved comprehensive test coverage and automated tooling for maintaining syscall data across multiple architectures.

8 changes.

This period focused on expanding seccomp-tools with a symbolic execution engine to analyze BPF filters across multiple architectures and an audit engine to detect security weaknesses. It also introduced an explain command to generate human-readable policy summaries and added shell completions for improved usability.

The library now includes a new disassembler module that converts raw BPF bytecode into a human-readable format. This tool emulates the filter execution to track register states, allowing it to infer and display syscall names and argument positions as comments within the disassembly output. Users can control the output verbosity via options to show or hide raw BPF fields and to toggle the inclusion of inferred argument details.

lib/seccomp-tools/disasm · high confidence

The \ext/ptrace\ directory now contains a C extension (\ptrace.c\) and build script (\extconf.rb\) that wraps Linux ptrace syscalls for the \SeccompTools::Ptrace\ Ruby module. This addition enables inspecting seccomp BPF filters of existing processes via \seccomp\_get\_filter\ and provides low-level utilities (such as \peekuser\, \attach\_and\_wait\, and \detach\) required for advanced process tracing and child-process following on Linux. The extension is compiled only on Linux; on other platforms it produces an empty object to ensure installation succeeds without errors.

ext · high confidence

A new executable script \bin/seccomp-tools\ has been added to the project. This script serves as the entry point for the command-line interface, invoking the \SeccompTools::CLI.work\ method with command-line arguments.

bin · high confidence

Users of bash, zsh, and fish shells can now enable tab-completion for seccomp-tools commands and arguments. The completions cover subcommands (asm, audit, disasm, dump, emu, explain, completion) and their specific flags (such as --arch, --format, --output, --pid, etc.), providing context-aware suggestions for options and file paths.

completions · high confidence

The seccomp-tools library now includes syscall number constant files for five additional architectures: aarch64, amd64, i386, riscv64, and s390x. These new files in \lib/seccomp-tools/consts/sys\_nr\ allow the tool to correctly identify and disassemble syscalls on these platforms, extending support beyond previously available architectures.

_lib/seccomp-tools/consts/sys\nr · high confidence

New Rake tasks have been added to automate the maintenance of seccomp-tools' syscall data and documentation. The \sys\_nr\ task fetches syscall number tables directly from the upstream Linux kernel source (defaulting to v7.1, configurable via \LINUX\_VERSION\) and regenerates the architecture-specific constant files, supporting amd64, i386, aarch64, riscv64, and s390x, including x32 ABI aliases. The \sys\_arg\ task parses Linux syscall prototypes to regenerate argument name constants. Additionally, the \readme\ task allows regenerating the README from a template by executing embedded shell commands, with safeguards to ensure it only runs on amd64 and fails loudly if commands produce no output or errors.

tasks · high confidence

The command-line interface has been refactored from a single monolithic handler into a modular architecture with a shared base class and distinct subcommand classes. This introduces new capabilities: the \asm\ command now assembles BPF bytecode into C arrays, source code, or assembly; the \audit\ command assesses filters for security weaknesses and escape routes; and the \completion\ command generates shell completion scripts for bash, zsh, and fish. Existing commands (\disasm\, \dump\, \emu\, \explain\) have been extracted into their own handlers, sharing common input parsing logic via the \FilterInput\ module and output handling via the \Base\ class, which also enforces architecture detection and file output serialization.

lib/seccomp-tools/cli · high confidence

The library is now available as a Ruby gem, providing a toolkit for working with seccomp BPF filters. Users can compile assembly into raw BPF using Asm.asm, disassemble raw BPF back into readable assembly with Disasm.disasm, capture installed filters via Dumper.dump, and test filters against hypothetical syscalls using the Emulator.

lib · high confidence

The \lib/seccomp-tools/explain\ directory introduces a new \explain\ command that analyzes a compiled seccomp filter and outputs a human-readable summary of its policy. This summary groups actions (such as ALLOW, KILL, or ERRNO) by architecture and specific conditions, making it easier to understand what a filter actually does. The implementation includes \Analysis\ to determine reachable paths and architecture splits, \PathFacts\ to extract syscall numbers and argument constraints, \QwordFusion\ to correctly reassemble 64-bit argument checks from 32-bit word operations, and a \Renderer\ to format these conditions into readable C-like expressions.

lib/seccomp-tools/explain · high confidence

Users can now write seccomp BPF rules using a human-readable assembly syntax (e.g., \A == read ? ok : next\) instead of manually constructing BPF instructions. This new compiler, located in \lib/seccomp-tools/asm\, parses assembly source code, resolves labels and jump targets, and emits raw BPF bytecode. It supports architecture-specific syscall names (e.g., \x86\_64.read\), arithmetic operations, conditional jumps, and scratch memory access, providing a higher-level interface for defining seccomp filters.

lib/seccomp-tools/asm · high confidence

The \lib/seccomp-tools/audit\ directory introduces a new audit engine that scans seccomp filters for common security weaknesses. It identifies issues such as permissive default actions (allowlists), dangerous syscalls being reachable, equivalent syscall gaps (e.g., \execve\ blocked but \execveat\ allowed), and the ability to read/write files (ORW chain). It also flags filters that do not validate the architecture, potentially allowing bypasses via different ABIs, and includes an architecture-specific check for the amd64 x32 ABI quirk. The engine provides findings with severity levels, details, and remediation advice, rendered in a human-readable report or JSON format.

lib/seccomp-tools/audit · high confidence

Seccomp-tools now includes a symbolic execution engine (SeccompTools::Symbolic::Executor) that analyzes classic BPF programs by exploring all possible execution paths simultaneously rather than running them with concrete inputs. This engine tracks symbolic values (Expr), path constraints (Constraint), and machine state (State) to produce a complete, input-independent description of a filter's behavior, including the specific conditions under which each return value is reached. It supports pruning infeasible branches and handles standard BPF operations like register manipulation, memory access, and arithmetic.

lib/seccomp-tools/symbolic · high confidence

Seccomp-tools has been updated to version 1.7.1, introducing a new Audit engine that scans seccomp filters for weaknesses and escape routes, and an Emulator that simulates filter execution against hypothetical syscalls. The release also adds support for dumping seccomp filters from existing processes via PTRACE\_SECCOMP\_GET\_FILTER, improves disassembly with syscall argument display, and adds architecture support for RISC-V 64-bit (riscv64).

lib/seccomp-tools · high confidence

The \lib/seccomp-tools/instruction\ module has been restructured from a procedural implementation into an object-oriented hierarchy. A new \Base\ class defines the interface for decompilation, symbolic representation, and state branching, while specific instruction types (ALU, JMP, LD, LDX, RET, ST, STX, MISC) are now distinct classes. This change improves the maintainability and clarity of the disassembler logic, allowing each BPF instruction class to encapsulate its own decompilation and state-transition rules.

lib/seccomp-tools/instruction · high confidence

The syscall argument names used in disassembly output have been updated to match the Linux 7.1 kernel definitions. This ensures that the tool displays accurate and current argument names for system calls, improving the clarity and correctness of the disassembled output for users analyzing system call behavior.

lib/seccomp-tools/consts · high confidence

Added seccomp test fixtures and build infrastructure; Added test coverage for audit, policy, dumper, emulator, and explain components; Added test coverage for new CLI subcommands and options; Added test coverage for the new symbolic execution engine; Added test fixtures and generator for seccomp assembly and BPF instructions; Added test suite for the disassembler; Added test suite for the new Racc-based assembler; Added tests for the explain command components.

This change introduces the initial release of the seccomp-tools gem, providing tools to analyze seccomp rules. The package includes the core library, a C extension for ptrace support, and shell completions for bash, zsh, and fish. It requires Ruby 3.1 or higher and bundles dependencies including logger and racc, along with development tools like RSpec, RuboCop, and YARD.

(dependencies) · high confidence

This change establishes the project's foundational structure by adding essential configuration and documentation files. It introduces a \.gitignore\ to exclude build artifacts and IDE files, an \.rspec\ configuration for test execution, and a \.rubocop.yml\ to enforce code style standards. Additionally, it provides a comprehensive \CHANGELOG.md\ documenting the tool's history from v0.1.0 through the unreleased version, and updates the \README.md\ with detailed usage examples for commands like \dump\, \disasm\, \asm\, \emu\, \explain\, and \audit\, along with shell completion instructions.

(repo-wide) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 78 → 77 (-0.4)
• Rubric changed (rubric-2026.09.15 → rubric-2026.10.1) — scores are not directly comparable.

• Code Health 100 → 100 (+0.0)
• Architecture 100 → 88 (-12.4)
• Maturity 69 → 69 (+0.0)
• Readiness 77 → 78 (+1.7)
• Security 88 → 91 (+2.3)

• Duplicate functionality: BPF#disasm appears to be a convenience wrapper around the standalone Disasm.disasm method. The BPF instance already holds raw and arch, making the standalone method redundant for users who have a BPF object.
• Hotspot: lib/seccomp-tools/asm/scanner.rb (lib/seccomp-tools/asm/scanner.rb)
• Inconsistent naming and argument structure for similar operations. dump takes a generic args object (likely a Syscall or similar), while dump_by_pid takes a raw pid. This splits the dumping logic between a high-level object method and a low-level procedural method, confusing the API surface.
• Redundant methods with identical names but different mutability semantics (bang vs non-bang) without clear distinction in signature or documentation context. In Ruby, validate! typically raises on error while validate returns boolean, but having both exposed on the same class without distinct behavior in the signature suggests duplication or confusion.

• Duplicate functionality across types. SeccompTools.BPF (an instruction object) has a disasm method, while SeccompTools.Disasm (a utility class) also has a disasm method. It is unclear if BPF.disasm delegates to Disasm.disasm or implements its own logic. This creates two entry points for the same operation.
• Projects may be oversized for their cohesion
• Redundant methods with ambiguous distinction. Having both validate! and validate suggests a mutation vs. read distinction or a strict vs. lenient mode, but without documentation, it is unclear if they perform different logic or if one is just an alias. In Ruby, ! often implies mutation, but Scanner properties are not shown as mutable in a way that suggests validate! modifies state differently than validate.

• 3 commits — 3 feature/other, 0 fixes

• (root) — 2 commits
• spec/data — 1 commit

• change: Drop facts a pinned value already implies from explain rules (#406)
• change: Place gen.rb's encoding comment where Ruby reads it (#405)
• change: Prune infeasible branches during the symbolic walk (#404)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

david942j/seccomp-tools was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.