### Resolve Syscall Names and Numbers Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Convert between syscall names and numbers for a specific architecture using resolve_syscall. Pass a syscall name to get its number, or a number to get its name. ```python import pyseccomp # Get syscall number from name write_nr = pyseccomp.resolve_syscall(pyseccomp.Arch.NATIVE, "write") print(f"write syscall number: {write_nr}") # e.g., 1 on x86_64 ``` -------------------------------- ### resolve_syscall - Resolve Syscall Names and Numbers Source: https://context7.com/cptpcrd/pyseccomp/llms.txt The `resolve_syscall()` function converts between syscall names and numbers for a specific architecture. Pass a syscall name to get its number, or pass a number to get its name. ```APIDOC ## resolve_syscall - Resolve Syscall Names and Numbers ### Description The `resolve_syscall()` function converts between syscall names and numbers for a specific architecture. Pass a syscall name to get its number, or pass a number to get its name. ### Method `resolve_syscall(arch, name_or_number)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```python import pyseccomp # Get syscall number from name write_nr = pyseccomp.resolve_syscall(pyseccomp.Arch.NATIVE, "write") print(f"write syscall number: {write_nr}") # e.g., 1 on x86_64 ``` ### Response #### Success Response (200) - **syscall_number** (int) - The syscall number corresponding to the name, or -1 if not found. #### Response Example ```json { "syscall_number": 1 } ``` ``` -------------------------------- ### Get and Set Filter Attributes Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Use `get_attr()` and `set_attr()` to read and modify filter configuration. The `Attr` class provides constants for attributes like default action, NNP, and logging. ```python import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.KILL) # Get the default action default_action = filt.get_attr(pyseccomp.Attr.ACT_DEFAULT) print(f"Default action: {hex(default_action)}") # Disable No New Privileges (NNP) requirement filt.set_attr(pyseccomp.Attr.CTL_NNP, 0) assert filt.get_attr(pyseccomp.Attr.CTL_NNP) == 0 # Enable NNP requirement filt.set_attr(pyseccomp.Attr.CTL_NNP, 1) assert filt.get_attr(pyseccomp.Attr.CTL_NNP) == 1 # Available attributes: # pyseccomp.Attr.ACT_DEFAULT - Default filter action # pyseccomp.Attr.ACT_BADARCH - Action for bad architecture # pyseccomp.Attr.CTL_NNP - No New Privileges control # pyseccomp.Attr.CTL_TSYNC - Thread synchronization control # pyseccomp.Attr.API_TSKIP - API level for TSKIP # pyseccomp.Attr.CTL_LOG - Logging control # pyseccomp.Attr.CTL_SSB - Speculative Store Bypass control # pyseccomp.Attr.CTL_OPTIMIZE - Optimization level # pyseccomp.Attr.API_SYSRAWRC - Raw syscall return codes ``` -------------------------------- ### Resolve Syscall Name and Number Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Use `resolve_syscall` to get a syscall's name from its number or vice versa. Returns -1 if the syscall is not found for the specified architecture. Supports native and specific architectures. ```python import pyseccomp # Get syscall name from number write_nr = 1 syscall_name = pyseccomp.resolve_syscall(pyseccomp.Arch.NATIVE, write_nr) print(f"syscall name: {syscall_name}") # b'write' # Check if syscall exists (returns -1 if not found) syscall_nr = pyseccomp.resolve_syscall(pyseccomp.Arch.NATIVE, "nonexistent") if syscall_nr == -1: print("Syscall does not exist on this architecture") # Resolve for specific architectures x86_write = pyseccomp.resolve_syscall(pyseccomp.Arch.X86, "write") arm_write = pyseccomp.resolve_syscall(pyseccomp.Arch.ARM, "write") ``` -------------------------------- ### Import pyseccomp or seccomp Source: https://github.com/cptpcrd/pyseccomp/blob/master/README.md This snippet demonstrates how to import the pyseccomp library, falling back to the standard seccomp if available. Use this pattern to ensure compatibility across different environments. ```python try: import seccomp except ImportError: import pyseccomp as seccomp ``` -------------------------------- ### Initialize SyscallFilter with Default Actions Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Initialize SyscallFilter with a default action. The default action applies to any syscall not explicitly matched by a rule. Supported actions include ALLOW, KILL_PROCESS, and ERRNO(errno.EPERM). ```python import pyseccomp # Create a filter that allows all syscalls by default filt = pyseccomp.SyscallFilter(pyseccomp.ALLOW) # Create a filter that kills the process for any syscall by default restrictive_filt = pyseccomp.SyscallFilter(pyseccomp.KILL_PROCESS) # Create a filter that returns EPERM for disallowed syscalls import errno permissive_filt = pyseccomp.SyscallFilter(pyseccomp.ERRNO(errno.EPERM)) ``` ```python # Reset a filter to a new default action filt.reset(pyseccomp.KILL) ``` -------------------------------- ### Pyseccomp Action Constants Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Demonstrates various action constants provided by Pyseccomp for defining seccomp filter rules, including ALLOW, KILL, TRAP, LOG, NOTIFY, ERRNO, and TRACE. ```python import errno import pyseccomp # Allow the syscall to proceed normally action_allow = pyseccomp.ALLOW # Kill the thread that made the syscall action_kill_thread = pyseccomp.KILL_THREAD action_kill = pyseccomp.KILL # Alias for KILL_THREAD # Kill the entire process action_kill_process = pyseccomp.KILL_PROCESS # Send SIGSYS signal to the process action_trap = pyseccomp.TRAP # Log the syscall and allow it action_log = pyseccomp.LOG # Notify user-space supervisor (requires libseccomp 2.5.0+) action_notify = pyseccomp.NOTIFY # Return a specific errno value action_eperm = pyseccomp.ERRNO(errno.EPERM) action_eacces = pyseccomp.ERRNO(errno.EACCES) action_enoent = pyseccomp.ERRNO(errno.ENOENT) # Trace with custom data (for use with ptrace) action_trace = pyseccomp.TRACE(0x1234) # Example: Build a restrictive filter filt = pyseccomp.SyscallFilter(pyseccomp.KILL_PROCESS) filt.add_rule(pyseccomp.ALLOW, "read") filt.add_rule(pyseccomp.ALLOW, "write") filt.add_rule(pyseccomp.ALLOW, "exit") filt.add_rule(pyseccomp.ALLOW, "exit_group") filt.add_rule(pyseccomp.ERRNO(errno.EPERM), "ptrace") # Deny ptrace ``` -------------------------------- ### SyscallFilter - Create and Configure Seccomp Filters Source: https://context7.com/cptpcrd/pyseccomp/llms.txt The SyscallFilter class is the primary interface for creating seccomp filters. Initialize it with a default action and then load the filter to apply it to the current process. ```APIDOC ## SyscallFilter - Create and Configure Seccomp Filters ### Description The `SyscallFilter` class is the primary interface for creating seccomp filters. Initialize it with a default action that applies to any syscall not explicitly matched by a rule. After configuring rules, call `load()` to apply the filter to the current process. ### Method `__init__(self, default_action)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```python import pyseccomp # Create a filter that allows all syscalls by default filt = pyseccomp.SyscallFilter(pyseccomp.ALLOW) # Create a filter that kills the process for any syscall by default restrictive_filt = pyseccomp.SyscallFilter(pyseccomp.KILL_PROCESS) # Create a filter that returns EPERM for disallowed syscalls import errno permissive_filt = pyseccomp.SyscallFilter(pyseccomp.ERRNO(errno.EPERM)) # Reset a filter to a new default action filt.reset(pyseccomp.KILL) ``` ### Response #### Success Response (200) None #### Response Example None ``` -------------------------------- ### Create Restrictive Sandbox Source: https://context7.com/cptpcrd/pyseccomp/llms.txt This function creates a seccomp filter that denies all syscalls by default and then explicitly allows basic I/O operations. Network operations are denied with EPERM instead of killing the process. Syscalls that do not exist on the current architecture are ignored. ```python import errno import os import pyseccomp def create_restrictive_sandbox(): """Create a restrictive seccomp sandbox allowing only basic I/O.""" # Start with KILL as default - deny everything not explicitly allowed filt = pyseccomp.SyscallFilter(pyseccomp.KILL_PROCESS) # Allow basic I/O operations allowed_syscalls = [ "read", "write", "close", "fstat", "lseek", "mmap", "mprotect", "munmap", "brk", "exit", "exit_group", "rt_sigreturn", "rt_sigprocmask", ] for syscall in allowed_syscalls: try: filt.add_rule(pyseccomp.ALLOW, syscall) except OSError: pass # Syscall might not exist on this architecture # Deny network operations with EPERM instead of killing network_syscalls = ["socket", "connect", "bind", "listen", "accept"] for syscall in network_syscalls: try: filt.add_rule(pyseccomp.ERRNO(errno.EPERM), syscall) except OSError: pass return filt # Apply sandbox in a child process pid = os.fork() if pid == 0: try: filt = create_restrictive_sandbox() filt.load() # Now the process is sandboxed # Only allowed syscalls will work os.write(1, b"Sandboxed process running\n") finally: os._exit(0) else: _, status = os.waitpid(pid, 0) if os.WIFEXITED(status): print(f"Child exited with code: {os.WEXITSTATUS(status)}") ``` -------------------------------- ### Manage Filter Architectures Source: https://context7.com/cptpcrd/pyseccomp/llms.txt The `Arch` class provides constants for architectures. Use `add_arch()`, `remove_arch()`, and `exist_arch()` to manage supported architectures for a filter. `system_arch()` returns the current system's architecture. ```python import pyseccomp # Get native system architecture native_arch = pyseccomp.system_arch() print(f"Native architecture: {hex(native_arch)}") filt = pyseccomp.SyscallFilter(pyseccomp.KILL) # Check if architecture is supported by filter assert filt.exist_arch(pyseccomp.Arch.NATIVE) assert filt.exist_arch(pyseccomp.system_arch()) # Add support for another architecture if not filt.exist_arch(pyseccomp.Arch.X86): filt.add_arch(pyseccomp.Arch.X86) # Remove native architecture (be careful!) filt.remove_arch(pyseccomp.Arch.NATIVE) # Available architectures: # pyseccomp.Arch.NATIVE - Current architecture # pyseccomp.Arch.X86, pyseccomp.Arch.X86_64, pyseccomp.Arch.X32 # pyseccomp.Arch.ARM, pyseccomp.Arch.AARCH64 # pyseccomp.Arch.MIPS, pyseccomp.Arch.MIPS64, pyseccomp.Arch.MIPSEL # pyseccomp.Arch.PPC, pyseccomp.Arch.PPC64, pyseccomp.Arch.PPC64LE # pyseccomp.Arch.S390, pyseccomp.Arch.S390X # pyseccomp.Arch.RISCV64 ``` -------------------------------- ### Export Seccomp Filters to BPF and PFC Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Export compiled seccomp filters to BPF (binary kernel format) or PFC (human-readable pseudo-code) files. Also demonstrates exporting to a pipe for inspection. ```python import os import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.KILL) filt.add_rule(pyseccomp.ALLOW, "read") filt.add_rule(pyseccomp.ALLOW, "write") filt.add_rule(pyseccomp.ALLOW, "exit") filt.add_rule(pyseccomp.ALLOW, "exit_group") # Export BPF to a file with open("filter.bpf", "wb") as f: filt.export_bpf(f) # Export PFC (human-readable) to a file with open("filter.pfc", "w") as f: filt.export_pfc(f) # Export to pipe for inspection r_fd, w_fd = os.pipe() with open(r_fd, "rb") as rfile: with open(w_fd, "wb") as wfile: filt.export_bpf(wfile) bpf_data = rfile.read() print(f"BPF filter size: {len(bpf_data)} bytes") ``` -------------------------------- ### Configure Syscall Argument Matching with Arg Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Use the Arg class to filter syscalls based on argument values. Specify argument index, comparison operator, and value(s). Available operators include NE, LT, LE, EQ, GE, GT, and MASKED_EQ. ```python import errno import os import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.ALLOW) # Block getpriority() only when second argument (who) equals 1 # Arg(arg_index, comparison_op, value) filt.add_rule( pyseccomp.ERRNO(errno.EPERM), "getpriority", pyseccomp.Arg(1, pyseccomp.EQ, 1) # Block only for PID 1 ) # Block prctl() with multiple argument conditions filt.add_rule( pyseccomp.KILL_PROCESS, "prctl", pyseccomp.Arg(0, pyseccomp.EQ, 0), pyseccomp.Arg(1, pyseccomp.NE, 0) ) # Available comparison operators: # pyseccomp.NE - Not equal # pyseccomp.LT - Less than # pyseccomp.LE - Less than or equal # pyseccomp.EQ - Equal # pyseccomp.GE - Greater than or equal # pyseccomp.GT - Greater than # pyseccomp.MASKED_EQ - Masked equality (datum_a & arg == datum_b) filt.load() # After loading: getpriority for PID 0 works, but PID 1 returns EPERM os.getpriority(os.PRIO_PROCESS, 0) # Works # os.getpriority(os.PRIO_PROCESS, 1) # Raises PermissionError ``` -------------------------------- ### Arg - Syscall Argument Matching Source: https://context7.com/cptpcrd/pyseccomp/llms.txt The `Arg` class allows filtering based on syscall argument values. Specify the argument index (0-5), comparison operator, and value(s) to match. This enables fine-grained control over which specific syscall invocations are filtered. ```APIDOC ## Arg - Syscall Argument Matching ### Description The `Arg` class allows filtering based on syscall argument values. Specify the argument index (0-5), comparison operator, and value(s) to match. This enables fine-grained control over which specific syscall invocations are filtered. ### Method `Arg(arg_index, comparison_op, value)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```python import errno import os import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.ALLOW) # Block getpriority() only when second argument (who) equals 1 # Arg(arg_index, comparison_op, value) filt.add_rule( pyseccomp.ERRNO(errno.EPERM), "getpriority", pyseccomp.Arg(1, pyseccomp.EQ, 1) # Block only for PID 1 ) # Block prctl() with multiple argument conditions filt.add_rule( pyseccomp.KILL_PROCESS, "prctl", pyseccomp.Arg(0, pyseccomp.EQ, 0), pyseccomp.Arg(1, pyseccomp.NE, 0) ) # Available comparison operators: # pyseccomp.NE - Not equal # pyseccomp.LT - Less than # pyseccomp.LE - Less than or equal # pyseccomp.EQ - Equal # pyseccomp.GE - Greater than or equal # pyseccomp.GT - Greater than # pyseccomp.MASKED_EQ - Masked equality (datum_a & arg == datum_b) filt.load() # After loading: getpriority for PID 0 works, but PID 1 returns EPERM os.getpriority(os.PRIO_PROCESS, 0) # Works # os.getpriority(os.PRIO_PROCESS, 1) # Raises PermissionError ``` ### Response #### Success Response (200) None #### Response Example None ``` -------------------------------- ### Handle Syscalls with User-Space Notifications Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Intercept syscalls and handle them in user-space using the notification API. This requires libseccomp 2.5.0+ and enables advanced sandboxing features. ```python import os import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.ALLOW) # Mark setpriority syscall for notification filt.add_rule(pyseccomp.NOTIFY, "setpriority") # In production, this would be in a parent/supervisor process filt.load() pid = os.fork() if pid == 0: # Child process - syscall will be intercepted try: os.setpriority(os.PRIO_PROCESS, 0, os.getpriority(os.PRIO_PROCESS, 0)) finally: os._exit(0) else: # Parent process - handle the notification notif = filt.receive_notify() # Inspect the notification print(f"Notification ID: {notif.id}") print(f"PID: {notif.pid}") print(f"Syscall number: {notif.syscall}") print(f"Syscall architecture: {hex(notif.syscall_arch)}") print(f"Arguments: {notif.syscall_args}") # Respond - allow the syscall with return value 0 response = pyseccomp.NotificationResponse( error=0, # No error flags=0, # No special flags id=notif.id, # Match the notification ID val=0 # Return value ) filt.respond_notify(response) os.waitpid(pid, 0) ``` -------------------------------- ### Merge Multiple Seccomp Filters Source: https://context7.com/cptpcrd/pyseccomp/llms.txt The `merge()` method combines two filters. Both filters must have the same default action. This is useful for building filters from multiple components. ```python import pyseccomp sys_arch = pyseccomp.system_arch() nonsys_arch = pyseccomp.Arch.X86 if sys_arch != pyseccomp.Arch.X86 else pyseccomp.Arch.ARM # Create filter A for native architecture filt_a = pyseccomp.SyscallFilter(pyseccomp.KILL) filt_a.add_rule(pyseccomp.ALLOW, "read") filt_a.add_rule(pyseccomp.ALLOW, "write") # Create filter B for another architecture filt_b = pyseccomp.SyscallFilter(pyseccomp.KILL) filt_b.add_arch(nonsys_arch) filt_b.remove_arch(sys_arch) filt_b.add_rule(pyseccomp.ALLOW, "exit") # Merge B into A - A now has rules for both architectures filt_a.merge(filt_b) # Filter A has both architectures assert filt_a.exist_arch(sys_arch) assert filt_a.exist_arch(nonsys_arch) ``` -------------------------------- ### add_rule - Add Syscall Filtering Rules Source: https://context7.com/cptpcrd/pyseccomp/llms.txt The `add_rule()` method adds a rule to match a specific syscall and optionally its arguments. When matched, the specified action is taken instead of the filter's default action. Syscalls can be specified by name (string) or number. ```APIDOC ## add_rule - Add Syscall Filtering Rules ### Description The `add_rule()` method adds a rule to match a specific syscall and optionally its arguments. When matched, the specified action is taken instead of the filter's default action. Syscalls can be specified by name (string) or number. ### Method `add_rule(self, action, syscall_name_or_number, *args)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```python import errno import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.ALLOW) # Block the nice() syscall with EPERM error filt.add_rule(pyseccomp.ERRNO(errno.EPERM), "nice") # Block setpriority() syscall - kills the thread filt.add_rule(pyseccomp.KILL, "setpriority") # Block ptrace() syscall - kills the entire process filt.add_rule(pyseccomp.KILL_PROCESS, "ptrace") # Log the syscall but allow it filt.add_rule(pyseccomp.LOG, "write") # Trap the syscall (sends SIGSYS) filt.add_rule(pyseccomp.TRAP, "execve") # Apply the filter filt.load() ``` ### Response #### Success Response (200) None #### Response Example None ``` -------------------------------- ### Add Syscall Filtering Rules Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Add rules to match specific syscalls and actions. Syscalls can be specified by name or number. Actions include ERRNO, KILL, KILL_PROCESS, LOG, and TRAP. ```python import errno import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.ALLOW) # Block the nice() syscall with EPERM error filt.add_rule(pyseccomp.ERRNO(errno.EPERM), "nice") # Block setpriority() syscall - kills the thread filt.add_rule(pyseccomp.KILL, "setpriority") # Block ptrace() syscall - kills the entire process filt.add_rule(pyseccomp.KILL_PROCESS, "ptrace") # Log the syscall but allow it filt.add_rule(pyseccomp.LOG, "write") # Trap the syscall (sends SIGSYS) filt.add_rule(pyseccomp.TRAP, "execve") # Apply the filter filt.load() ``` -------------------------------- ### Add Architecture-Specific Rules with add_rule_exactly Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Add rules that apply only to the exact architecture specified, without translation. Use this for precise control over rule application across architectures. ```python import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.ALLOW) # Add rule only for the native architecture (no translation) for name in ["nice", "setpriority"]: sys_nr = pyseccomp.resolve_syscall(pyseccomp.Arch.NATIVE, name) if sys_nr >= 0: # Syscall exists on this architecture filt.add_rule_exactly(pyseccomp.KILL, sys_nr) # Can also use syscall name directly filt.add_rule_exactly(pyseccomp.KILL, "ptrace") filt.load() ``` -------------------------------- ### add_rule_exactly - Architecture-Specific Rules Source: https://context7.com/cptpcrd/pyseccomp/llms.txt The `add_rule_exactly()` method adds rules that apply only to the exact architecture specified, without translation. Use this when you need precise control over which architectures a rule applies to. ```APIDOC ## add_rule_exactly - Architecture-Specific Rules ### Description The `add_rule_exactly()` method adds rules that apply only to the exact architecture specified, without translation. Use this when you need precise control over which architectures a rule applies to. ### Method `add_rule_exactly(self, action, syscall_number)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```python import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.ALLOW) # Add rule only for the native architecture (no translation) for name in ["nice", "setpriority"]: sys_nr = pyseccomp.resolve_syscall(pyseccomp.Arch.NATIVE, name) if sys_nr >= 0: # Syscall exists on this architecture filt.add_rule_exactly(pyseccomp.KILL, sys_nr) # Can also use syscall name directly filt.add_rule_exactly(pyseccomp.KILL, "ptrace") filt.load() ``` ### Response #### Success Response (200) None #### Response Example None ``` -------------------------------- ### Control Pyseccomp API Version Source: https://context7.com/cptpcrd/pyseccomp/llms.txt Query and set the libseccomp API level using `get_api()` and `set_api()`. This is useful for ensuring compatibility with specific libseccomp versions and requires libseccomp 2.4.0+. ```python import pyseccomp try: # Get current API level api_level = pyseccomp.get_api() print(f"Current libseccomp API level: {api_level}") # Set API level (useful for compatibility testing) pyseccomp.set_api(3) assert pyseccomp.get_api() == 3 # Restore original level pyseccomp.set_api(api_level) except NotImplementedError: print("API get/set not available (libseccomp < 2.4)") ``` -------------------------------- ### Set Syscall Rule Evaluation Priority Source: https://context7.com/cptpcrd/pyseccomp/llms.txt The `syscall_priority()` method sets the priority for a syscall's rules. Higher priority rules are evaluated first, improving performance for frequently-used syscalls. Can use syscall name or number. ```python import pyseccomp filt = pyseccomp.SyscallFilter(pyseccomp.KILL) # Set high priority for frequently-used syscalls filt.syscall_priority("write", 255) filt.syscall_priority("read", 255) # Can also use syscall number write_nr = pyseccomp.resolve_syscall(pyseccomp.Arch.NATIVE, "write") filt.syscall_priority(write_nr, 100) # Add rules after setting priority filt.add_rule(pyseccomp.ALLOW, "write") filt.add_rule(pyseccomp.ALLOW, "read") ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.