Reference Guide

Python bindings for the libseccomp library

The libseccomp library provides and easy to use, platform independent, interface to the Linux Kernel’s syscall filtering mechanism: seccomp. The libseccomp API is designed to abstract away the underlying BPF based syscall filter language and present a more conventional function-call based filtering interface that should be familiar to, and easily adopted by application developers.

Filter action values:

KILL_PROCESS - kill the process KILL - kill the thread LOG - allow the syscall to be executed after the action has been logged ALLOW - allow the syscall to execute TRAP - a SIGSYS signal will be thrown NOTIFY - a notification event will be sent via the notification API ERRNO(x) - syscall will return (x) TRACE(x) - if the process is being traced, (x) will be returned to the

tracing process via PTRACE_EVENT_SECCOMP and the PTRACE_GETEVENTMSG option

Argument comparison values (see the Arg class):

NE - arg != datum_a LT - arg < datum_a LE - arg <= datum_a EQ - arg == datum_a GT - arg > datum_a GE - arg >= datum_a MASKED_EQ - (arg & datum_a) == datum_b

Example:

import sys from seccomp import *

# create a filter object with a default KILL action f = SyscallFilter(defaction=KILL)

# add some basic syscalls which python typically wants f.add_rule(ALLOW, “rt_sigaction”) f.add_rule(ALLOW, “rt_sigreturn”) f.add_rule(ALLOW, “exit_group”) f.add_rule(ALLOW, “brk”)

# add syscall filter rules to allow certain syscalls f.add_rule(ALLOW, “open”) f.add_rule(ALLOW, “close”) f.add_rule(ALLOW, “read”, Arg(0, EQ, sys.stdin.fileno())) f.add_rule(ALLOW, “write”, Arg(0, EQ, sys.stdout.fileno())) f.add_rule(ALLOW, “write”, Arg(0, EQ, sys.stderr.fileno()))

# load the filter into the kernel f.load()

class seccomp.Arch

Python object representing the SyscallFilter architecture values.

Data values: NATIVE - the native architecture X86 - 32-bit x86 X86_64 - 64-bit x86 X32 - 64-bit x86 using the x32 ABI ARM - ARM AARCH64 - 64-bit ARM MIPS - MIPS O32 ABI MIPS64 - MIPS 64-bit ABI MIPS64N32 - MIPS N32 ABI MIPSEL - MIPS little endian O32 ABI MIPSEL64 - MIPS little endian 64-bit ABI MIPSEL64N32 - MIPS little endian N32 ABI PARISC - 32-bit PA-RISC PARISC64 - 64-bit PA-RISC PPC64 - 64-bit PowerPC PPC - 32-bit PowerPC

class seccomp.Arg

Python object representing a SyscallFilter syscall argument.

class seccomp.Attr

Python object representing the SyscallFilter attributes.

Data values: ACT_DEFAULT - the filter’s default action ACT_BADARCH - the filter’s bad architecture action CTL_NNP - the filter’s “no new privileges” flag CTL_NNP - the filter’s thread sync flag CTL_TSYNC - sync threads on filter load CTL_TSKIP - allow rules with a -1 syscall number CTL_LOG - log not-allowed actions CTL_SSB - disable SSB mitigations

seccomp.ERRNO()

The action ERRNO(x) means that the syscall will return (x). To conform to Linux syscall calling conventions, the syscall return value should almost always be a negative number.

class seccomp.Notification

Python object representing a seccomp notification.

flags

Get the seccomp notification flags.

Description: Get the seccomp notification flags.

id

Get the seccomp notification ID.

Description: Get the seccomp notification ID.

pid

Get the seccomp notification process ID.

Description: Get the seccomp notification process ID.

syscall

Get the seccomp notification syscall.

Description: Get the seccomp notification syscall.

syscall_arch

Get the seccomp notification syscall architecture.

Description: Get the seccomp notification syscall architecture.

syscall_args

Get the seccomp notification syscall arguments.

Description: Get the seccomp notification syscall arguments in a six element list.

syscall_ip

Get the seccomp notification syscall instruction pointer.

Description: Get the seccomp notification syscall instruction pointer.

class seccomp.NotificationResponse

Python object representing a seccomp notification response.

error

Get the seccomp notification response error.

Description: Get the seccomp notification response error.

flags

Get the seccomp notification response flags.

Description: Get the seccomp notification response flags.

id

Get the seccomp notification response ID.

Description: Get the seccomp notification response ID.

val

Get the seccomp notification response value.

Description: Get the seccomp notification response value.

class seccomp.SyscallFilter

Python object representing a seccomp syscall filter.

add_arch()

Add an architecture to the filter.

Arguments: arch - the architecture value, e.g. Arch.*

Description: Add the given architecture to the filter. Any new rules added after this method returns successfully will be added to this new architecture, but any existing rules will not be added to the new architecture.

add_rule()

Add a new rule to filter.

Arguments: action - the rule action: KILL_PROCESS, KILL, TRAP, ERRNO(), TRACE(),

LOG, or ALLOW

syscall - the syscall name or number args - variable number of Arg objects

Description: Add a new rule to the filter, matching on the given syscall and an optional list of argument comparisons. If the rule is triggered the given action will be taken by the kernel. In order for the rule to trigger, the syscall as well as each argument comparison must be true.

In the case where the specific rule is not valid on a specific architecture, e.g. socket() on 32-bit x86, this method rewrites the rule to the best possible match. If you don’t want this fule rewriting to take place use add_rule_exactly().

add_rule_exactly()

Add a new rule to filter.

Arguments: action - the rule action: KILL_PROCESS, KILL, TRAP, ERRNO(), TRACE(),

LOG, or ALLOW

syscall - the syscall name or number args - variable number of Arg objects

Description: Add a new rule to the filter, matching on the given syscall and an optional list of argument comparisons. If the rule is triggered the given action will be taken by the kernel. In order for the rule to trigger, the syscall as well as each argument comparison must be true.

This method attempts to add the filter rule exactly as specified which can cause problems on certain architectures, e.g. socket() on 32-bit x86. For a architecture independent version of this method use add_rule().

exist_arch()

Check if the seccomp filter contains a given architecture.

Arguments: arch - the architecture value, e.g. Arch.*

Description: Test to see if a given architecture is included in the filter. Return True is the architecture exists, False if it does not exist.

export_bpf()

Export the filter in BPF format.

Arguments: file - the output file

Description: Output the filter in Berkley Packet Filter (BPF) to the given file. The output is identical to what is loaded into the Linux Kernel.

export_pfc()

Export the filter in PFC format.

Arguments: file - the output file

Description: Output the filter in Pseudo Filter Code (PFC) to the given file. The output is functionally equivalent to the BPF based filter which is loaded into the Linux Kernel.

get_attr()

Get an attribute value from the filter.

Arguments: attr - the attribute, e.g. Attr.*

Description: Lookup the given attribute in the filter and return the attribute’s value to the caller.

load()

Load the filter into the Linux Kernel.

Description: Load the current filter into the Linux Kernel. As soon as the method returns the filter will be active and enforcing.

merge()

Merge two existing SyscallFilter objects.

Arguments: filter - a valid SyscallFilter object

Description: Merges a valid SyscallFilter object with the current SyscallFilter object; the passed filter object will be reset on success. In order to successfully merge two seccomp filters they must have the same attribute values and not share any of the same architectures.

receive_notify()

Receive seccomp notifications.

Description: Receive a seccomp notification from the system, requires the use of the NOTIFY action.

remove_arch()

Remove an architecture from the filter.

Arguments: arch - the architecture value, e.g. Arch.*

Description: Remove the given architecture from the filter. The filter must always contain at least one architecture, so if only one architecture exists in the filter this method will fail.

reset()

Reset the filter state.

Arguments: defaction - the default filter action

Description: Resets the seccomp filter state to an initial default state, if a default filter action is not specified in the reset call the original action will be reused. This function does not affect any seccomp filters alread loaded into the kernel.

respond_notify()

Send a seccomp notification response.

Arguments: response - the response to send to the system

Description: Respond to a seccomp notification.

set_attr()

Set a filter attribute.

Arguments: attr - the attribute, e.g. Attr.* value - the attribute value

Description: Lookup the given attribute in the filter and assign it the given value.

syscall_priority()

Set the filter priority of a syscall.

Arguments: syscall - the syscall name or number priority - the priority of the syscall

Description: Set the filter priority of the given syscall. A syscall with a higher priority will have less overhead in the generated filter code which is loaded into the system. Priority values can range from 0 to 255 inclusive.

seccomp.TRACE()

The action TRACE(x) means that, if the process is being traced, (x) will be returned to the tracing process via PTRACE_EVENT_SECCOMP and the PTRACE_GETEVENTMSG option.

seccomp.c_str()

Convert a Python string to a C string.

Arguments: string - the Python string

Description: Convert the Python string into a form usable by C taking into consideration the Python major version, e.g. Python 2.x or Python 3.x. See http://docs.cython.org/en/latest/src/tutorial/strings.html for more information.

seccomp.get_api()

Query the level of API support

Description: Returns the API level value indicating the current supported functionality.

seccomp.resolve_syscall()

Resolve the syscall.

Arguments: arch - the architecture value, e.g. Arch.* syscall - the syscall name or number

Description: Resolve an architecture’s syscall name to the correct number or the syscall number to the correct name.

seccomp.set_api()

Set the level of API support

Arguments: level - the API level

Description: This function forcibly sets the API level at runtime. General use of this function is strongly discouraged.

seccomp.system_arch()

Return the system architecture value.

Description: Returns the native system architecture value.