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.

WHEN

ARCH

FMT

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] [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.

WHEN

ARCH

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.

WHEN

SYSCALL_NAME/SYSCALL_NR

ARGS[0-5] and PC

ARCH

TEXT

trace - TRACE FILTER IN RUNTIME¶

ceccomp trace [-c WHEN] [-o FILE] PROGRAM [program-args]


              [-c WHEN] -p PID

The first line captures filters PROGRAM loads in runtime by tracing it; the second line extract seccomp filters from PID; 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.

WHEN

FILE

PROGRAM

PID

probe - TEST COMMON SYSCALLS INSTANTLY¶

ceccomp probe [-c WHEN] [-o FILE] 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

Optional Wrapper¶

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

Line  CODE  JT   JF      K
---------------------------------
0001: 0x06 0x00 0x00 0x7fff0000 return ALLOW
---------------------------------

Only return ALLOW, the statement is needed.

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 = 0b111
$X = 0777

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 3

Jump if:

if ($A == execve) goto 3
if ($A != 1234) goto 4
if ($A & $X) goto 5
if !($A & 7) goto 6
if ($A <= $X) goto 7

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

if ($A > $X) goto 3, else goto 4
if ($A >= 4567) goto 5, else goto 6

ONLY in conditions, you CAN replace number with syscall 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 KILL
return KILL_PROCESS
return TRAP(123)
return ERRNO(0)
return TRACE
return TRACE(3)
return LOG
return NOTIFY