NAME

Linux::Seccomp - Interface to libseccomp Linux syscall filtering library

SYNOPSIS

use Linux::Seccomp ':all';
my $ctx = Linux::Seccomp->new(SCMP_ACT_ALLOW);
# Block writes to STDERR
$ctx->rule_add(SCMP_ACT_KILL, syscall_resolve_name('write'), [0, '==', 2]);
$ctx->load;
$| = 1;
print STDOUT "Hello world!\n";       # works
print STDERR "Goodbye world!\n";     # Killed
print STDOUT "Hello again world!\n"; # never reached

DESCRIPTION

Secure Computing (seccomp) is Linux's system call filtering mechanism. This system can operate in two modes: strict, where only a very small number of system calls are allowed and the more modern filter (or seccomp mode 2) which permits advanced filtering of system calls. This module is only concerned with the latter.

Linux::Seccomp is a Perl interface to the libseccomp library which provides a simple way to use seccomp mode 2.

It should be mentioned that this module is not production-ready at the moment -- work needs to be done to port the libseccomp testsuite and the documentation needs to be improved.

Basic usage of this module is straightforward: Create a filter using the new method, add rules to it using the rule_add method several times, and finally load the filter into the kernel using the load method. An example of this can be seen in the SYNOPSIS.

METHODS

Most methods die on error.

$ctx = Linux::Seccomp->new($def_action)

Creates a new Linux::Seccomp filter, with the default action for unhandled syscalls being $def_action. Possible values for $def_action are:

SCMP_ACT_KILL: The thread will be terminated by the kernel with SIGSYS when it calls a syscall that does not match any of the configured seccomp filter rules. The thread will not be able to catch the signal.
SCMP_ACT_TRAP: The thread will be sent a SIGSYS signal when it calls a syscall that does not match any of the configured seccomp filter rules. It may catch this and change its behavior accordingly. When using SA_SIGINFO with sigaction(2), si_code will be set to SYS_SECCOMP, si_syscall will be set to the syscall that failed the rules, and si_arch will be set to the AUDIT_ARCH for the active ABI.
SCMP_ACT_ERRNO($errno): The thread will receive a return value of $errno when it calls a syscall that does not match any of the configured seccomp filter rules.
SCMP_ACT_TRACE($msg_num): If the thread is being traced and the tracing process specified the PTRACE_O_TRACESECCOMP option in the call to ptrace(2), the tracing process will be notified, via PTRACE_EVENT_SECCOMP, and the value provided in msg_num can be retrieved using the PTRACE_GETEVENTMSG option.
SCMP_ACT_ALLOW: The seccomp filter will have no effect on the thread calling the syscall if it does not match any of the configured seccomp filter rules.

See seccomp_init(3).

$ctx->rule_add($action, $syscall, @args)

Adds a rule to the filter. If a system call with number $syscall whose arguments match @args is called, $action will be taken.

$action can be any of the SCMP_ACT_* macros listed above.

@args is a list of 0 or more constraints on the arguments to the syscall. Each constraint is an arrayref with 3 or 4 elements: [$arg, $op, $datum_a, $datum_b] where $arg is the index of the argument we are comparing. $op is as follows:

SCMP_CMP_NE
'!='
'ne': Matches when the argument value is not equal to $datum_a.
SCMP_CMP_LT
'<'
'lt': Matches when the argument value is less than $datum_a.
SCMP_CMP_LE
'<='
'le': Matches when the argument value is less than or equal to $datum_a.
SCMP_CMP_EQ
'=='
'eq': Matches when the argument value is equal to $datum_a.
SCMP_CMP_GE
'>='
'ge': Matches when the argument value is greater than or equal to $datum_a.
SCMP_CMP_GT
'>'
'gt': Matches when the argument value is greater than $datum_a.
SCMP_CMP_MASKED_EQ
'=~'
'me': Matches when the argument value masked with $datum_a is equal to $datum_b masked with $datum_a.

See seccomp_rule_add(3).

$ctx->arch_add($arch_token)

Add an architecture to the filter. The native architecture is added by default. See seccomp_arch_add(3).

$ctx->arch_exists($arch_token)

Returns true if the given architecture is in the filter, false otherwise. See seccomp_arch_add(3).

$ctx->arch_remove($arch_token)

Removes an architecture from the filter. See seccomp_arch_add(3).

$ctx->attr_get($attr)

Returns the value of an attribute. The attributes are:

SCMP_FLTATR_ACT_DEFAULT: The default filter action as specified in the call to new. Read-only.
SCMP_FLTATR_ACT_BADARCH: The filter action taken when the loaded filter does not match the architecture of the executing application. Defaults to SCMP_ACT_KILL.
SCMP_FLTATR_CTL_NNP: Specifies whether to turn on NO_NEW_PRIVS functionality when load is called. Defaults to 1 (on). If this flag is turned off then the calling process must have CAP_SYS_ADMIN (or else the call to load will fail).
SCMP_FLTATR_CTL_TSYNC: Specifies whether the kernel should synchronize the filters accross all threads when load is called. Defaults to 0 (off).
SCMP_FLTATR_API_TSKIP: Specifies whether rules for the system call -1 should be allowed. This value can be used by tracer programs to skip specific system call invocations, see seccomp(2) for more information. Defaults to 0 (off).

See seccomp_attr_get(3).

$ctx->attr_set($attr, $value)

Sets an attribute to the given value. The attributes are the ones from the list above except for SCMP_FLTATR_ACT_DEFAULT which is read-only. See seccomp_attr_get(3).

$ctx->export_bpf($fh)

Writes the BPF (Berkeley Packet Filter) representation of the filter to the given file handle. See seccomp_export_bpf(3).

$ctx->export_pfc($fh)

Writes the PFC (Pseudo Filter Code) representation of the filter to the given file handle. See seccomp_export_bpf(3).

$ctx->load

Loads the filter into the kernel. See seccomp_load(3).

FUNCTIONS

None exported by default. These functions die on error.

arch_native: Returns the arch token for the native architecture. See seccomp_arch_add(3).
arch_resolve_name($arch_name): Returns the arch token for a named architecture. See seccomp_arch_add(3).
syscall_resolve_name($name): Resolves a system call name to its number for the native architecture. A negative pseudo syscall number is returned if the architecture does not have the given syscall. See seccomp_syscall_resolve_name(3).
syscall_resolve_name_arch($arch_token, $name): Resolves a system call name to its number for a given architecture. A negative pseudo syscall number is returned if the architecture does not have the given syscall. See seccomp_syscall_resolve_name(3).
syscall_resolve_name_rewrite($arch_token, $name): Resolves a system call name to its number for a given architecture. A negative pseudo syscall number is returned if the architecture does not have the given syscall. In contrast to the previous function, this function tries to obtain the actual syscall number in cases where the previous function would return a pseudo syscall number. See seccomp_syscall_resolve_name(3).
syscall_resolve_num_arch($arch_token, $num): Returns the name of the system call with the given number on the given architecture. See seccomp_syscall_resolve_name(3).
version: Returns the version of libseccomp as a three-element arrayref: [$major_version, $minor_version, $micro_version].

CONSTANTS

All exported by default. Most of the SCMP_ constants were seen above. Here is a list of all of them:

SCMP_ACT_ALLOW
SCMP_ACT_KILL
SCMP_ACT_TRAP
SCMP_ARCH_AARCH64
SCMP_ARCH_ARM
SCMP_ARCH_MIPS
SCMP_ARCH_MIPS64
SCMP_ARCH_MIPS64N32
SCMP_ARCH_MIPSEL
SCMP_ARCH_MIPSEL64
SCMP_ARCH_MIPSEL64N32
SCMP_ARCH_NATIVE
SCMP_ARCH_PPC
SCMP_ARCH_PPC64
SCMP_ARCH_PPC64LE
SCMP_ARCH_S390
SCMP_ARCH_S390X
SCMP_ARCH_X32
SCMP_ARCH_X86
SCMP_ARCH_X86_64
SCMP_CMP_EQ
SCMP_CMP_GE
SCMP_CMP_GT
SCMP_CMP_LE
SCMP_CMP_LT
SCMP_CMP_MASKED_EQ
SCMP_CMP_NE
SCMP_FLTATR_ACT_BADARCH
SCMP_FLTATR_ACT_DEFAULT
SCMP_FLTATR_CTL_NNP
SCMP_FLTATR_CTL_TSYNC
SCMP_FLTATR_API_TSKIP
SCMP_VER_MAJOR
SCMP_VER_MICRO
SCMP_VER_MINOR

Besides the SCMP_ constants, the module also provides a long list of __NR_syscall and __PNR_syscall constants that represent real and pseudo syscall numbers for many common system calls. A full list can be found in the source code of this module. See also the syscall_resolve_name family of functions above which is more flexible than this set of constants.

AUTHOR

Marius Gavrilescu, <marius@ieval.ro>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.0 or, at your option, any later version of Perl 5 you may have available.

To install Linux::Seccomp, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Linux::Seccomp

CPAN shell

perl -MCPAN -e shell
install Linux::Seccomp

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)