Project: Firecracker (Runtime / Container Runtime)
File: seccompiler.md

Seccompiler-bin is a tool that compiles seccomp filters expressed as JSON files into serialized, binary BPF code that is directly consumed by Firecracker, at build or launch time. Seccompiler-bin uses a custom , detailed further below, that the filters must adhere to. Besides the seccompiler-bin executable, seccompiler also exports a library interface, with helper functions for deserializing and installing the binary filters. To view the seccompiler-bin command line arguments, pass the `--help` parameter to the executable. Example usage: ```bash ./seccompiler-bin --target-arch "x86_64" # The CPU arch where the BPF program will run. --input-file "x8664musl.json" # File path of the JSON input. --output-file "bpfx8664_musl" # Optional path of the output file. --basic # Optional, creates basic filters, discarding any parameter checks. ``` To view the library documentation, navigate to the seccompiler source code, in `firecracker/src/seccompiler/src` and run `cargo doc --lib --open`. Seccompiler is implemented as another package in the Firecracker cargo workspace. The code is located at `firecracker/src/seccompiler/src`. Seccompiler-bin is supported on the . Seccompiler-bin follows Firecracker's and version (it's released at the same time, with the same version number and adheres to the same support window). A JSON file expresses the seccomp policy for the entire Firecracker process. It contains multiple filters, one per each thread category and is specific to just one target platform. This means that Firecracker has a JSON file for each supported target (currently determined by the arch-libc combinations). You can view them in `resources/seccomp`. At the top level, the file requires an object that maps thread categories (vmm, api and vcpu) to seccomp filters: ``` { "vmm": { "default_action": { "errno" : -1 }, "filter_action": "allow", "filter": [...] }, "api": {...}, "vcpu": {...}, } ``` The associated filter is a JSON object containing the `default_action`, `filter_action` and `filter`. The `default_action` represents the action we have to execute if none of the rules in `filter` matches, and `filter_action` is what gets executed if a rule in the filter matches (e.g: `"Allow"` in the case of implementing an allowlist). An action is the JSON representation of the following enum: ```rust pub enum SeccompAction { Allow, // Allows syscall. Errno(u32), // Returns from syscall with specified error number. Kill, // Kills calling process. Log, // Same as allow but logs

Trace(u32), // Notifies tracing process of the caller with respective number. Trap, // Sends `SIGSYS` to the calling process. } ``` The `filter` property specifies the set of rules that would trigger a match. This is an array containing multiple or-bound SyscallRule objects (if one of them matches, the corresponding action gets triggered). The SyscallRule object is used for adding a rule to a syscall. It has an optional `args` property that is used to specify a vector of and-bound conditions that the syscall arguments must satisfy in order for the rule to match. In the absence of the `args` property, the corresponding action will get triggered by any call that matches that name, irrespective of the argument values. Here is the structure of the object: ``` { "syscall": "accept4", // mandatory, the syscall name "comment": "Used by vsock & api thread", // optional, for adding meaningful comments "args": [...] // optional, vector of and-bound conditions for the parameters } ``` Note that the file format expects syscall names, not arch-specific numbers, for increased usability. This is not true, however for the syscall arguments, which are expected as base-10 integers. In order to allow a syscall with multiple alternatives for the same parameters, you can write multiple syscall rule objects at the filter-level, each with its own rules. Note that, when passing the deprecated `--basic` flag to seccompiler-bin, all `args` fields of the `SeccompRule`s are ignored. A condition object is made up of the following mandatory properties: `index` (0-based index of the syscall argument we want to check) `type` (`dword` or `qword`, which specifies the argument size - 4 or 8 bytes respectively) `op`, which is one of `eq, ge, gt, ge, lt, masked_eq, ne` (the operator used for comparing the parameter to `val`) `val` is the integer value being checked against As mentioned eariler, we dont support any named parameters, but only numeric constants in the JSON file. You may however add an optional `comment` property to each condition object. This way, you can provide meaning to each numeric value, much like when using named parameters, like so: ``` { "syscall": "accept4", "args": [ { "index": 3, "type": "dword", "op": "eq", "val": 1, "comment": "libc::AF_UNIX" } ] } ``` To see example filters, look over Firecracker's JSON filters in `resources/seccomp`.