1 package Linux
::Seccomp
;
11 our @ISA = qw(Exporter);
18 syscall_resolve_name_arch
19 syscall_resolve_name_rewrite
20 syscall_resolve_num_arch
53 SCMP_FLTATR_ACT_BADARCH
54 SCMP_FLTATR_ACT_DEFAULT
76 __NR_arm_sync_file_range
165 __NR_pciconfig_iobase
183 __NR_s390_pci_mmio_read
184 __NR_s390_pci_mmio_write
185 __NR_s390_runtime_instr
239 __NR_sync_file_range2
240 __NR_sys_debug_setcontext
273 __PNR_arm_fadvise64_64
274 __PNR_arm_sync_file_range
304 __PNR_get_kernel_syms
306 __PNR_get_thread_area
328 __PNR_kexec_file_load
363 __PNR_pciconfig_iobase
365 __PNR_pciconfig_write
381 __PNR_s390_pci_mmio_read
382 __PNR_s390_pci_mmio_write
383 __PNR_s390_runtime_instr
396 __PNR_set_thread_area
436 __PNR_sync_file_range
437 __PNR_sync_file_range2
438 __PNR_sys_debug_setcontext
464 $EXPORT_TAGS{all
} = [@
{$EXPORT_TAGS{functions
}}, @
{$EXPORT_TAGS{macros
}}];
465 our @EXPORT_OK = @
{$EXPORT_TAGS{all
}};
466 our @EXPORT = @
{$EXPORT_TAGS{macros
}};
476 ($constname = $AUTOLOAD) =~ s/.*:://;
477 croak
"&Linux::Seccomp::constant not defined" if $constname eq 'constant';
478 my ($error, $val) = constant
($constname);
479 if ($error) { croak
$error; }
482 *$AUTOLOAD = sub { $val };
489 XSLoader
::load
('Linux::Seccomp', $VERSION);
493 my ($ign, $def_action) = @_;
501 my %COMPARE_OP_TBL = (
502 '!=' => SCMP_CMP_NE
(),
504 '<' => SCMP_CMP_LT
(),
506 '<=' => SCMP_CMP_LE
(),
508 '==' => SCMP_CMP_EQ
(),
510 '>=' => SCMP_CMP_GE
(),
512 '>' => SCMP_CMP_GT
(),
514 '=~' => SCMP_CMP_MASKED_EQ
(),
515 me
=> SCMP_CMP_MASKED_EQ
(),
517 SCMP_CMP_NE
() => SCMP_CMP_NE
(),
518 SCMP_CMP_LT
() => SCMP_CMP_LT
(),
519 SCMP_CMP_LE
() => SCMP_CMP_LE
(),
520 SCMP_CMP_EQ
() => SCMP_CMP_EQ
(),
521 SCMP_CMP_GE
() => SCMP_CMP_GE
(),
522 SCMP_CMP_GT
() => SCMP_CMP_GT
(),
523 SCMP_CMP_MASKED_EQ
() => SCMP_CMP_MASKED_EQ
(),
526 sub _mangle_rule_add_args
{
529 $_->[1] = $COMPARE_OP_TBL{$op} or croak
"No mapping for compare operator '$op'";
536 rule_add_array
(shift, shift, shift, _mangle_rule_add_args
(@_));
540 rule_add_exact_array
(shift, shift, shift, _mangle_rule_add_args
(@_));
550 Linux::Seccomp - Interface to libseccomp Linux syscall filtering library
554 use Linux::Seccomp ':all';
555 my $ctx = Linux::Seccomp->new(SCMP_ACT_ALLOW);
556 # Block writes to STDERR
557 $ctx->rule_add(SCMP_ACT_KILL, syscall_resolve_name('write'), [0, '==', 2]);
560 print STDOUT "Hello world!\n"; # works
561 print STDERR "Goodbye world!\n"; # Killed
562 print STDOUT "Hello again world!\n"; # never reached
566 Secure Computing (seccomp) is Linux's system call filtering mechanism.
567 This system can operate in two modes: I<strict>, where only a very
568 small number of system calls are allowed and the more modern I<filter>
569 (or seccomp mode 2) which permits advanced filtering of system calls.
570 This module is only concerned with the latter.
572 Linux::Seccomp is a Perl interface to the
573 L<libseccomp|https://github.com/seccomp/libseccomp> library which
574 provides a simple way to use seccomp mode 2.
576 It should be mentioned that this module is not production-ready at the
577 moment -- work needs to be done to port the libseccomp testsuite and
578 the documentation needs to be improved.
580 Basic usage of this module is straightforward: Create a filter using
581 the B<new> method, add rules to it using the B<rule_add> method
582 several times, and finally load the filter into the kernel using the
583 B<load> method. An example of this can be seen in the SYNOPSIS.
587 Most methods die on error.
591 =item I<$ctx> = Linux::Seccomp->B<new>(I<$def_action>>)
593 Creates a new C<Linux::Seccomp> filter, with the default action for
594 unhandled syscalls being I<$def_action>. Possible values for
601 The thread will be terminated by the kernel with SIGSYS when it calls
602 a syscall that does not match any of the configured seccomp filter
603 rules. The thread will not be able to catch the signal.
607 The thread will be sent a SIGSYS signal when it calls a syscall that
608 does not match any of the configured seccomp filter rules. It may
609 catch this and change its behavior accordingly. When using SA_SIGINFO
610 with L<sigaction(2)>, si_code will be set to SYS_SECCOMP, si_syscall
611 will be set to the syscall that failed the rules, and si_arch will be
612 set to the AUDIT_ARCH for the active ABI.
614 =item SCMP_ACT_ERRNO(I<$errno>)
616 The thread will receive a return value of I<$errno> when it calls a
617 syscall that does not match any of the configured seccomp filter
620 =item SCMP_ACT_TRACE(I<$msg_num>)
622 If the thread is being traced and the tracing process specified the
623 PTRACE_O_TRACESECCOMP option in the call to L<ptrace(2)>, the tracing
624 process will be notified, via PTRACE_EVENT_SECCOMP, and the value
625 provided in msg_num can be retrieved using the PTRACE_GETEVENTMSG
630 The seccomp filter will have no effect on the thread calling the
631 syscall if it does not match any of the configured seccomp filter
636 See L<seccomp_init(3)>.
638 =item I<$ctx>->B<rule_add>(I<$action>, I<$syscall>, I<@args>)
640 Adds a rule to the filter. If a system call with number I<$syscall>
641 whose arguments match I<@args> is called, I<$action> will be taken.
643 I<$action> can be any of the C<SCMP_ACT_*> macros listed above.
645 I<@args> is a list of 0 or more constraints on the arguments to the
646 syscall. Each constraint is an arrayref with 3 or 4 elements: C<[$arg,
647 $op, $datum_a, $datum_b]> where I<$arg> is the index of the argument
648 we are comparing. I<$op> is as follows:
656 Matches when the argument value is not equal to I<$datum_a>.
662 Matches when the argument value is less than I<$datum_a>.
668 Matches when the argument value is less than or equal to I<$datum_a>.
674 Matches when the argument value is equal to I<$datum_a>.
680 Matches when the argument value is greater than or equal to I<$datum_a>.
686 Matches when the argument value is greater than I<$datum_a>.
688 =item SCMP_CMP_MASKED_EQ
692 Matches when the argument value masked with I<$datum_a> is equal to I<$datum_b> masked with I<$datum_a>.
696 See L<seccomp_rule_add(3)>.
698 =item I<$ctx>->B<arch_add>(I<$arch_token>)
700 Add an architecture to the filter. The native architecture is added by
702 See L<seccomp_arch_add(3)>.
704 =item I<$ctx>->B<arch_exists>(I<$arch_token>)
706 Returns true if the given architecture is in the filter, false
708 See L<seccomp_arch_add(3).
710 =item I<$ctx>->B<arch_remove>(I<$arch_token>)
712 Removes an architecture from the filter.
713 See L<seccomp_arch_add(3).
715 =item I<$ctx>->B<attr_get>(I<$attr>)
717 Returns the value of an attribute. The attributes are:
721 =item SCMP_FLTATR_ACT_DEFAULT
723 The default filter action as specified in the call to B<new>. Read-only.
725 =item SCMP_FLTATR_ACT_BADARCH
727 The filter action taken when the loaded filter does not match the
728 architecture of the executing application. Defaults to SCMP_ACT_KILL.
730 =item SCMP_FLTATR_CTL_NNP
732 Specifies whether to turn on NO_NEW_PRIVS functionality when B<load>
733 is called. Defaults to 1 (on). If this flag is turned off then the
734 calling process must have CAP_SYS_ADMIN (or else the call to B<load>
737 =item SCMP_FLTATR_CTL_TSYNC
739 Specifies whether the kernel should synchronize the filters accross
740 all threads when B<load> is called. Defaults to 0 (off).
744 See L<seccomp_attr_get(3)>.
746 =item I<$ctx>->B<attr_set>(I<$attr>, I<$value>)
748 Sets an attribute to the given value. The attributes are the ones from
749 the list above except for SCMP_FLTATR_ACT_DEFAULT which is read-only.
750 See L<seccomp_attr_get(3)>.
752 =item I<$ctx>->B<export_bpf>(I<$fh>)
754 Writes the BPF (Berkeley Packet Filter) representation of the filter
755 to the given file handle.
756 See L<seccomp_export_bpf(3)>.
758 =item I<$ctx>->B<export_pfc>(I<$fh>)
760 Writes the PFC (Pseudo Filter Code) representation of the filter to
761 the given file handle.
762 See L<seccomp_export_bpf(3)>.
764 =item I<$ctx>->B<load>
766 Loads the filter into the kernel.
767 See L<seccomp_load(3)>.
773 None exported by default. These functions die on error.
779 Returns the arch token for the native architecture.
780 See L<seccomp_arch_add(3)>.
782 =item B<arch_resolve_name>(I<$arch_name>)
784 Returns the arch token for a named architecture.
785 See L<seccomp_arch_add(3)>.
787 =item B<syscall_resolve_name>(I<$name>)
789 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.
790 See L<seccomp_syscall_resolve_name(3)>.
792 =item B<syscall_resolve_name_arch>(I<$arch_token>, I<$name>)
794 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.
795 See L<seccomp_syscall_resolve_name(3)>.
797 =item B<syscall_resolve_name_rewrite>(I<$arch_token>, I<$name>)
799 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.
800 See L<seccomp_syscall_resolve_name(3)>.
802 =item B<syscall_resolve_num_arch>(I<$arch_token>, I<$num>)
804 Returns the name of the system call with the given number on the given architecture.
805 See L<seccomp_syscall_resolve_name(3)>.
809 Returns the version of libseccomp as a three-element arrayref:
810 [$major_version, $minor_version, $micro_version].
816 All exported by default. Most of the SCMP_ constants were seen above.
817 Here is a list of all of them:
829 SCMP_ARCH_MIPSEL64N32
846 SCMP_FLTATR_ACT_BADARCH
847 SCMP_FLTATR_ACT_DEFAULT
849 SCMP_FLTATR_CTL_TSYNC
854 Besides the SCMP_ constants, the module also provides a long list of
855 __NR_syscall and __PNR_syscall constants that represent real and
856 pseudo syscall numbers for many common system calls. A full list can
857 be found in the source code of this module. See also the
858 B<syscall_resolve_name> family of functions above which is more
859 flexible than this set of constants.
863 L<https://github.com/seccomp/libseccomp>
867 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
869 =head1 COPYRIGHT AND LICENSE
871 Copyright (C) 2016 by Marius Gavrilescu
873 This library is free software; you can redistribute it and/or modify
874 it under the same terms as Perl itself, either Perl version 5.24.0 or,
875 at your option, any later version of Perl 5 you may have available.