Registry / auth-security / pyseccomp

pyseccomp

JSON →
library0.1.2pypypi✓ verified 25d ago

Pyseccomp is a pure Python interface to the libseccomp library, leveraging ctypes to provide syscall filtering capabilities via Linux's seccomp mechanism. It aims for API compatibility with libseccomp's official Python bindings. The library is actively maintained, with its latest release (version 0.1.2) published in January 2021.

pip install pyseccomp
INSTALL
IMPORT
SIG · PYSECCOMP
P
pyseccomp
auth-securitypythonv0.1.2
Install
1.6s avg
Import
54ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.054s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SyscallFilter, ALLOW, LOG, ERRNO
from pyseccomp import SyscallFilter, ALLOW, LOG, ERRNO
import seccomp # without a fallback
The pyseccomp library recommends using a `try...except ImportError` block to import `seccomp` first, and then falling back to `pyseccomp as seccomp`. This ensures compatibility if the official `libseccomp` Python bindings are installed.

This quickstart demonstrates how to initialize a `SyscallFilter` with a default `ALLOW` action. It then adds rules to deny specific syscalls such as `execve`, `execveat`, `vfork`, and `fork`. The example shows how to configure an action (e.g., `LOG` or `ERRNO`) for denied syscalls before loading the filter into the kernel. An attempt to `os.fork()` is included to illustrate how the applied seccomp filter prevents this operation, resulting in an `OSError`.

import errno try: import seccomp except ImportError: import pyseccomp as seccomp def setup_seccomp_filter(log_only: bool = False): """ Sets up a basic seccomp filter to restrict process execution. """ f = seccomp.SyscallFilter(seccomp.ALLOW) # Always log, even when returning an error f.set_attr(seccomp.Attr.CTL_LOG, 1) # Define action: LOG for logging or ERRNO(EACCES) for denying and returning EACCES action = seccomp.LOG if log_only else seccomp.ERRNO(errno.EACCES) # Deny execution of new processes f.add_rule(action, "execve") f.add_rule(action, "execveat") f.add_rule(action, "vfork") f.add_rule(action, "fork") f.load() print(f'Seccomp filter enabled with action: {"LOG" if log_only else "ERRNO(EACCES)"}') if __name__ == "__main__": print("Applying seccomp filter to prevent fork/execve...") setup_seccomp_filter(log_only=False) # Attempt to fork (this should be blocked by seccomp) try: import os pid = os.fork() if pid == 0: print("Child process created (THIS SHOULD NOT HAPPEN IF SECCOMP WORKS!)") os._exit(0) else: print(f"Parent process: Child PID {pid}") os.waitpid(pid, 0) except OSError as e: print(f"Fork failed as expected due to seccomp: {e}") except Exception as e: print(f"An unexpected error occurred: {e}") print("Filter applied. Program will now exit.")
Debug
Known issues
breakingOlder versions of pyseccomp may have compatibility issues with `libseccomp` versions prior to 2.4, potentially leading to incorrect behavior or crashes.
fix
Upgrade `pyseccomp` to version 0.1.2 or later, which includes a fix for `libseccomp < 2.4` compatibility. It is also recommended to keep your system's `libseccomp` library updated.
affects: < 0.1.2
gotchaMissing C function prototypes in pyseccomp versions prior to 0.1.1 could lead to segmentation faults when certain library functionalities were invoked.
fix
Update `pyseccomp` to version 0.1.1 or newer to ensure all necessary function prototypes are included, resolving potential segfaults.
affects: < 0.1.1
gotchaPyseccomp is a wrapper for the `libseccomp` C library. If `libseccomp` is not installed on the system, pyseccomp will raise a `RuntimeError` during initialization, stating 'Unable to find libseccomp'.
fix
Ensure that the `libseccomp` development package (e.g., `libseccomp-dev` on Debian/Ubuntu, `libseccomp-devel` on Fedora/CentOS) is installed on your operating system.
affects: All versions
gotchaApplying seccomp filters too broadly or without a complete understanding of required syscalls can easily break an application, leading to unexpected crashes, hangs, or incorrect behavior. Common omissions include syscalls for file I/O (`openat`, `read`, `write`), process management (`exit_group`), and system information (`stat`).
fix
Start with a permissive policy (`ALLOW`) and progressively add `DENY` rules, or start with a restrictive policy (`KILL`, `TRAP`) and incrementally `ALLOW` only necessary syscalls. Utilize the `CTL_LOG` attribute (`f.set_attr(seccomp.Attr.CTL_LOG, 1)`) to log blocked syscalls during development, aiding in debugging. Thoroughly test the application under the seccomp filter.
affects: All versions
Errors
Common errors & fixes
OSError: libseccomp.so.2: cannot open shared object file: No such file or directory
The underlying C library `libseccomp`, which `pyseccomp` is a wrapper for, is not installed on the system or is not discoverable in the linker's search paths.
fix
Install the `libseccomp` development package using your system's package manager (e.g., `sudo apt-get install libseccomp-dev` on Debian/Ubuntu or `sudo dnf install libseccomp-devel` on Fedora/RHEL).
ModuleNotFoundError: No module named 'seccomp'
The `pyseccomp` Python package, which provides the `seccomp` module for import, has not been installed in the current Python environment.
fix
Install the package using pip: `pip install pyseccomp`.
OSError: [Errno 1] Operation not permitted
The current process lacks the necessary privileges or kernel capabilities (e.g., `CAP_SYS_ADMIN`, `CAP_SYS_PTRACE`) to load a seccomp filter into the kernel, or the kernel configuration prevents it.
fix
Run the application with elevated privileges (e.g., as root, or with appropriate capabilities if using a container runtime like Docker/Podman) and ensure the kernel supports seccomp in the execution environment.
Upgrade
Version history
0.1.2latest on PyPI · released Jan 2, 2021
Audit
Dependencies
libseccomprequiredPyseccomp is a Python interface to the C library `libseccomp`, which must be installed on the operating system for pyseccomp to function. It uses `ctypes.util.find_library('seccomp')` to locate it.
Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources
pyseccomp — pip install pyseccomp · libregistry