ceccomp(1)

asm - ASSEMBLE

ceccomp asm [-c WHEN] [-a ARCH] [-f FMT] [TEXT]

Assemble TEXT to RAW. Use it to embed hand written filter rules into C code or to see the original code of some TEXT.

-c, --color WHEN

Determines when to display warnings and errors in color. If the value is auto, ceccomp will display color when the output target is a "tty". Can be auto, never or always. The default value is auto.

-a, --arch ARCH

Set to any architecture libseccomp supports. Will be used to determine the actual syscall number behind the name (for example, on x86_64, you could write "execve" instead of 59 like the basic example above). Your system arch will be taken if not set via uname. The default value on your system is x86_64.

-f, --format FMT

Determines how ceccomp produces binary-format bpf code. Can be hexfmt, hexline, raw or c-macro. You could find sample output in EXAMPLES section. The default value is hexline.

TEXT

Please check out TEXT GRAMMAR REFERENCE section to see how to write a rule by hand. Some examples will be displayed in EXAMPLES section.

disasm - DISASSEMBLE

ceccomp disasm [-c WHEN] [-a ARCH] [-e] [RAW]

Disassemble RAW to TEXT. Use it to see what does a filter do if you could not access filter via trace and have to manually extract the filter out.

-c, --color WHEN

Argument description can be found in asm - ASSEMBLE section. disasm may print more text in color including syntax highlighting for TEXT.

-a, --arch ARCH

Set to any architecture libseccomp supports. Will be used to determine how filtered syscall number in RAW filter is translated to syscall name (for example, on x86_64, the number 0x3b is translated to execve if is comparing syscall_nr, see the basic example above). The default value on your system is x86_64.

-e, --ebpf

Treat RAW as eBPF insn bytes instead of cBPF filter bytes. This flag is designed to test whether eBPF-to-cBPF conversion is working or not. To use this function, please dump installed eBPF insns migrated from seccomp filters in a process via eBPF or a kernel module. Any input not generated by kernel may lead to undefined behavior.

RAW

emu - EMULATE

ceccomp emu [-c WHEN] [-a ARCH] [-q] TEXT SYSCALL_NAME/SYSCALL_NR [ARGS[0] ARGS[1] ... ARGS[5] PC]

Emulate what will happen if syscall(SYSCALL_NR, ARGS[0], ARGS[1], ..., ARGS[5]) from PC is called following rules described in TEXT. Use it to see the result without actually running it in program or you don’t want to examine the filter rule manually. This subcommand can be used to automatically examining a filter.

-c, --color WHEN

Argument description can be found in asm - ASSEMBLE section. emu may print more text in color including syntax highlighting for TEXT and skipped statements.

SYSCALL_NAME/SYSCALL_NR

ARGS[0-5] and PC

-a, --arch ARCH

Argument description can be found in asm - ASSEMBLE section.

TEXT

-q, --quiet

Only print the eval result of the filter. For example, if last statement emulated is return KILL, then KILL is printed.

trace - TRACE FILTER IN RUNTIME

ceccomp trace [-c WHEN] [-q] [-o FILE] PROGRAM [program-args]
              [-c WHEN] [-q] -p PID [-s]

The first line captures filters PROGRAM loads in runtime by tracing it; the second line extract seccomp filters from PID, or trace PID to capture subsequent seccomp filters; once fetched filters, print them in TEXT. You can only choose one of the two formats above. Use this if running the program is the simplest way to fetch bpf filters or a program with seccomp filters installed is waiting for input.

-c, --color WHEN

Argument description can be found in asm - ASSEMBLE section. trace may print more text in color including syntax highlighting for TEXT.

-o, --output FILE

May be useful when PROGRAM produces quite a lot output in stderr. ceccomp allow user to close stdin and stdout to limit PROGRAM input and output, so ceccomp use stderr to print messages when running PROGRAM, set FILE if you want to see TEXT in some other file. Treat - as stdout.

PROGRAM

-p, --pid PID

Set to the pid you want to inspect. PID is conflict with PROGRAM; you could either run a program dynamically or examine a pid in one command. Without -s flag, trace pid will try to extract seccomp filter in PID via ptrace(PTRACE_SECCOMP_GET_FILTER), which may not be available in some systems. The pid here is actually process (thread) id, you can trace a thread or process.

-s, --seize

ONLY AVAILABLE FOR TRACE PID MODE. Set this flag will override trace pid behavior to attach to PID and keep tracing for seccomp filter loading like trace prog mode. This flag was introduced in version 4.0.

-q, --quiet

Set to suppress the extra [INFO] prints when detect process forking, exiting or seccomp filter loading. This flag was introduced in version 4.0.

probe - TEST COMMON SYSCALLS INSTANTLY

ceccomp probe [-c WHEN] [-o FILE] [-q] PROGRAM [program-args]

Run PROGRAM with program-args to captures FIRST seccomp filter, and then kill all children. Use it when a quick check against a program is needed, and detect potential seccomp rule issues.

All argument descriptions can be found in trace - TRACE FILTER IN RUNTIME section.

The output for this subcommand is the emulating result of common syscalls like execve, open and so on. If the filter itself is not capable of blocking syscalls, you could know that with a glance.

Typical output for this subcommand is described below, more detailed example could be found in EXAMPLES section.

open      -> ALLOW
read      -> ALLOW
write     -> ALLOW
execve    -> KILL
execveat  -> KILL
mmap      -> ALLOW
mprotect  -> ALLOW
openat    -> ALLOW
sendfile  -> ALLOW
ptrace    -> ERRNO(1)
fork      -> ALLOW

capture - CAPTURE FILTERS WITH EBPF

ceccomp capture [-c WHEN] [-p PID]

Capture seccomp filters in global scope if PID not set. The eBPF program will trace seccomp_check_filter kernel function, reliably intercepting seccomp filters that the kernel will load, WITHOUT race conditions compared to trace - TRACE FILTER IN RUNTIME. This function is named "global capture" below. Linux 5.15 is the lowest recommended kernel version to run this function on x86_64, other architecture may require higher kernel version to run this function.

If PID is set, an eBPF program to extract installed seccomp filters in the corresponding process (actually thread) will be installed. Note that inside kernel, pid is referred thread id and tgid is referred to process id. The eBPF program directly pulls eBPF insns migrated from original seccomp filters out and converts them back to perform disasm - DISASSEMBLE. This function does not require CONFIG_CHECKPOINT_RESTORE kernel config, and is functional even if ceccomp itself is under seccomp. This function is named "capture pid" below. Linux 6.2 is the lowest kernel version to run this function, as bpf_task_from_pid was introduced then.

Currently, compat task detection is only supported on x86_64 and aarch64. With this feature, ceccomp can identify whether a task is native (64-bit task on 64-bit kernel) or "compatible" (32-bit task on 64-bit kernel), so that ceccomp can pass the correct architecture token to libseccomp to query syscall name in captured seccomp filters.

Note that eBPF utilizes asynchronous ring buffer to send back data to user-mode process, so if lots of seccomp filters are loaded at the same time, the buffer may run out and you need to see detailed errors via bpftool prog trace. Since we can’t send the errors back through full ring buffer, those overflowed filters are actually invisible to users without reading kernel messages.

-c, --color WHEN

Argument description can be found in asm - ASSEMBLE section.

-p, --pid PID

Which process (thread) to extract seccomp filter insns from.

Comment and Label

ceccomp disasm displays a lot of things, but some of them are optional for asm.

#Label  CODE  JT   JF      K
#---------------------------------
 L0001: 0x06 0x00 0x00 0x7fff0000 return ALLOW
#---------------------------------

Any text after # will be discarded by asm like some script languages.

Empty lines are accepted.

Label declaration is an identifier at the beginning of line and suffixed by : like L0001. An identifier is a string starts with alpha and contains with only alphanumeric characters and underscore _. Label is only necessary if it’s the destination of goto, these redundant labels added by disasm are for readability. E.g. in if ($A == 0) goto somewhere, somewhere is a label and must be declared after the statement. Label declaration can take a line separately, or be put in front of statement.

The CODE, JT, JF and K value generated by disasm will be discarded by asm, asm only parse the effective statement after K.

line  CODE  JT   JF      K
=================================
0000: 0x06 0x00 0x00 0x7fff0000  return ALLOW

Assignment

A can be set to seccomp attributes directly. But X can not be assigned with seccomp attributes directly due to kernel limit.

$A = $arch
$A = $syscall_nr

To assign A with those 64-bit long fields, low_ or high_ prefix is needed.

$A = $low_pc
$A = $high_pc
$A = $low_args[0]
$A = $high_args[0]
...
$A = $low_args[5]
$A = $high_args[5]

A special attribute is sizeof(struct seccomp_data), that can be assigned to A or X directly.

$A = $scmp_data_len
$X = $scmp_data_len

Temporary memory is 32-bit, to access them, you could use hex or dec as index. Both A and X is assignable. Assigning immediate values to A or X accepts any format of number if you imply the correct base by "0x" or "0b".

$X = $mem[0]
$A = $mem[0xf]
$A = $mem[15] # both hex and dec index are OK
$A = 0
$X = 0x3b
$A = 0b1111
$A = 0333

You could also assign X to A or in the reverse order. Assign X or A to temporary memory is definitely okay.

$A = $X
$X = $A
$mem[3] = $X
$mem[0x4] = $A

Arithmetic Operations

Various operations can be applied to A.

$A += 30
$A -= 4
$A *= 9
$A /= 1
$A &= 7
$A >>= 6

The right value can be X.

$A &= $X
$A |= $X
$A ^= $X
$A <<= $X

And there is a way to negativate A.

$A = -$A

Jump Downwards If ...

Unconditional jump:

goto L3

Jump if:

if ($A == execve) goto L3
if ($A != 1234) goto L4
if ($A & $X) goto L5
if !($A & 7) goto L6
if ($A <= $X) goto L7

If true jump to ... if false jump to...:

if ($A > $X) goto L3, else goto L4
if ($A >= 4567) goto L5, else goto L6

ONLY in conditions, you CAN replace number with syscall name or arch name. In example above, 0x3b is replaced by execve. All the syscall name will be resolved to syscall number under your selected arch. If you want to resolve a syscall name in foreign arch (not equal to your selected arch), please prepend a arch and dot. For example, your arch is x86_64, and you are writing aarch64 rules, then please write like:

if ($A == aarch64.read) goto 5

Note that if you manually set arch to aarch64 with -a aarch64, you can omit aarch64. in statement.

Return Code

Return value of register A:

return $A

Or return a immediate value, with extra field in (). Actions including TRACE, TRAP and ERRNO accept an extra field, without (), they are treated as action(0).

return 0x13371337
return KILL
return KILL_PROCESS
return TRAP(123)
return ERRNO(0)
return TRACE
return TRACE(3)
return LOG
return NOTIFY

Short Example

The following TEXT is valid for asm, which blocks execve and execveat for amd64 syscalls:

$A = $syscall_nr
if ($A == execve) goto forbid
if ($A == execveat) goto forbid
return ALLOW
forbid: return KILL