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
77 __NR_arm_sync_file_range
166 __NR_pciconfig_iobase
184 __NR_s390_pci_mmio_read
185 __NR_s390_pci_mmio_write
186 __NR_s390_runtime_instr
240 __NR_sync_file_range2
241 __NR_sys_debug_setcontext
274 __PNR_arm_fadvise64_64
275 __PNR_arm_sync_file_range
305 __PNR_get_kernel_syms
307 __PNR_get_thread_area
329 __PNR_kexec_file_load
364 __PNR_pciconfig_iobase
366 __PNR_pciconfig_write
382 __PNR_s390_pci_mmio_read
383 __PNR_s390_pci_mmio_write
384 __PNR_s390_runtime_instr
397 __PNR_set_thread_area
437 __PNR_sync_file_range
438 __PNR_sync_file_range2
439 __PNR_sys_debug_setcontext
464 __PNR_pkey_mprotect __NR_pkey_mprotect __PNR_pkey_alloc
465 __NR_pkey_alloc __PNR_pkey_free __NR_pkey_free
467 __PNR_get_tls __NR_get_tls __PNR_s390_guarded_storage
468 __NR_s390_guarded_storage __PNR_s390_sthyi __NR_s390_sthyi
/]
471 $EXPORT_TAGS{all
} = [@
{$EXPORT_TAGS{functions
}}, @
{$EXPORT_TAGS{macros
}}];
472 our @EXPORT_OK = @
{$EXPORT_TAGS{all
}};
473 our @EXPORT = @
{$EXPORT_TAGS{macros
}};
483 ($constname = $AUTOLOAD) =~ s/.*:://;
484 croak
"&Linux::Seccomp::constant not defined" if $constname eq 'constant';
485 my ($error, $val) = constant
($constname);
486 if ($error) { croak
$error; }
489 *$AUTOLOAD = sub { $val };
496 XSLoader
::load
('Linux::Seccomp', $VERSION);
500 my ($ign, $def_action) = @_;
508 my %COMPARE_OP_TBL = (
509 '!=' => SCMP_CMP_NE
(),
511 '<' => SCMP_CMP_LT
(),
513 '<=' => SCMP_CMP_LE
(),
515 '==' => SCMP_CMP_EQ
(),
517 '>=' => SCMP_CMP_GE
(),
519 '>' => SCMP_CMP_GT
(),
521 '=~' => SCMP_CMP_MASKED_EQ
(),
522 me
=> SCMP_CMP_MASKED_EQ
(),
524 SCMP_CMP_NE
() => SCMP_CMP_NE
(),
525 SCMP_CMP_LT
() => SCMP_CMP_LT
(),
526 SCMP_CMP_LE
() => SCMP_CMP_LE
(),
527 SCMP_CMP_EQ
() => SCMP_CMP_EQ
(),
528 SCMP_CMP_GE
() => SCMP_CMP_GE
(),
529 SCMP_CMP_GT
() => SCMP_CMP_GT
(),
530 SCMP_CMP_MASKED_EQ
() => SCMP_CMP_MASKED_EQ
(),
533 sub _mangle_rule_add_args
{
536 $_->[1] = $COMPARE_OP_TBL{$op} or croak
"No mapping for compare operator '$op'";
543 rule_add_array
(shift, shift, shift, _mangle_rule_add_args
(@_));
547 rule_add_exact_array
(shift, shift, shift, _mangle_rule_add_args
(@_));
557 Linux::Seccomp - Interface to libseccomp Linux syscall filtering library
561 use Linux::Seccomp ':all';
562 my $ctx = Linux::Seccomp->new(SCMP_ACT_ALLOW);
563 # Block writes to STDERR
564 $ctx->rule_add(SCMP_ACT_KILL, syscall_resolve_name('write'), [0, '==', 2]);
567 print STDOUT "Hello world!\n"; # works
568 print STDERR "Goodbye world!\n"; # Killed
569 print STDOUT "Hello again world!\n"; # never reached
573 Secure Computing (seccomp) is Linux's system call filtering mechanism.
574 This system can operate in two modes: I<strict>, where only a very
575 small number of system calls are allowed and the more modern I<filter>
576 (or seccomp mode 2) which permits advanced filtering of system calls.
577 This module is only concerned with the latter.
579 Linux::Seccomp is a Perl interface to the
580 L<libseccomp|https://github.com/seccomp/libseccomp> library which
581 provides a simple way to use seccomp mode 2.
583 It should be mentioned that this module is not production-ready at the
584 moment -- work needs to be done to port the libseccomp testsuite and
585 the documentation needs to be improved.
587 Basic usage of this module is straightforward: Create a filter using
588 the B<new> method, add rules to it using the B<rule_add> method
589 several times, and finally load the filter into the kernel using the
590 B<load> method. An example of this can be seen in the SYNOPSIS.
594 Most methods die on error.
598 =item I<$ctx> = Linux::Seccomp->B<new>(I<$def_action>)
600 Creates a new C<Linux::Seccomp> filter, with the default action for
601 unhandled syscalls being I<$def_action>. Possible values for
608 The thread will be terminated by the kernel with SIGSYS when it calls
609 a syscall that does not match any of the configured seccomp filter
610 rules. The thread will not be able to catch the signal.
614 The thread will be sent a SIGSYS signal when it calls a syscall that
615 does not match any of the configured seccomp filter rules. It may
616 catch this and change its behavior accordingly. When using SA_SIGINFO
617 with L<sigaction(2)>, si_code will be set to SYS_SECCOMP, si_syscall
618 will be set to the syscall that failed the rules, and si_arch will be
619 set to the AUDIT_ARCH for the active ABI.
621 =item SCMP_ACT_ERRNO(I<$errno>)
623 The thread will receive a return value of I<$errno> when it calls a
624 syscall that does not match any of the configured seccomp filter
627 =item SCMP_ACT_TRACE(I<$msg_num>)
629 If the thread is being traced and the tracing process specified the
630 PTRACE_O_TRACESECCOMP option in the call to L<ptrace(2)>, the tracing
631 process will be notified, via PTRACE_EVENT_SECCOMP, and the value
632 provided in msg_num can be retrieved using the PTRACE_GETEVENTMSG
637 The seccomp filter will have no effect on the thread calling the
638 syscall if it does not match any of the configured seccomp filter
643 See L<seccomp_init(3)>.
645 =item I<$ctx>->B<rule_add>(I<$action>, I<$syscall>, I<@args>)
647 Adds a rule to the filter. If a system call with number I<$syscall>
648 whose arguments match I<@args> is called, I<$action> will be taken.
650 I<$action> can be any of the C<SCMP_ACT_*> macros listed above.
652 I<@args> is a list of 0 or more constraints on the arguments to the
653 syscall. Each constraint is an arrayref with 3 or 4 elements: C<[$arg,
654 $op, $datum_a, $datum_b]> where I<$arg> is the index of the argument
655 we are comparing. I<$op> is as follows:
665 Matches when the argument value is not equal to I<$datum_a>.
673 Matches when the argument value is less than I<$datum_a>.
681 Matches when the argument value is less than or equal to I<$datum_a>.
689 Matches when the argument value is equal to I<$datum_a>.
697 Matches when the argument value is greater than or equal to I<$datum_a>.
705 Matches when the argument value is greater than I<$datum_a>.
707 =item SCMP_CMP_MASKED_EQ
713 Matches when the argument value masked with I<$datum_a> is equal to I<$datum_b> masked with I<$datum_a>.
717 See L<seccomp_rule_add(3)>.
719 =item I<$ctx>->B<arch_add>(I<$arch_token>)
721 Add an architecture to the filter. The native architecture is added by
723 See L<seccomp_arch_add(3)>.
725 =item I<$ctx>->B<arch_exists>(I<$arch_token>)
727 Returns true if the given architecture is in the filter, false
729 See L<seccomp_arch_add(3)>.
731 =item I<$ctx>->B<arch_remove>(I<$arch_token>)
733 Removes an architecture from the filter.
734 See L<seccomp_arch_add(3)>.
736 =item I<$ctx>->B<attr_get>(I<$attr>)
738 Returns the value of an attribute. The attributes are:
742 =item SCMP_FLTATR_ACT_DEFAULT
744 The default filter action as specified in the call to B<new>. Read-only.
746 =item SCMP_FLTATR_ACT_BADARCH
748 The filter action taken when the loaded filter does not match the
749 architecture of the executing application. Defaults to SCMP_ACT_KILL.
751 =item SCMP_FLTATR_CTL_NNP
753 Specifies whether to turn on NO_NEW_PRIVS functionality when B<load>
754 is called. Defaults to 1 (on). If this flag is turned off then the
755 calling process must have CAP_SYS_ADMIN (or else the call to B<load>
758 =item SCMP_FLTATR_CTL_TSYNC
760 Specifies whether the kernel should synchronize the filters accross
761 all threads when B<load> is called. Defaults to 0 (off).
763 =item SCMP_FLTATR_API_TSKIP
765 Specifies whether rules for the system call -1 should be allowed. This
766 value can be used by tracer programs to skip specific system call
767 invocations, see L<seccomp(2)> for more information. Defaults to 0
772 See L<seccomp_attr_get(3)>.
774 =item I<$ctx>->B<attr_set>(I<$attr>, I<$value>)
776 Sets an attribute to the given value. The attributes are the ones from
777 the list above except for SCMP_FLTATR_ACT_DEFAULT which is read-only.
778 See L<seccomp_attr_get(3)>.
780 =item I<$ctx>->B<export_bpf>(I<$fh>)
782 Writes the BPF (Berkeley Packet Filter) representation of the filter
783 to the given file handle.
784 See L<seccomp_export_bpf(3)>.
786 =item I<$ctx>->B<export_pfc>(I<$fh>)
788 Writes the PFC (Pseudo Filter Code) representation of the filter to
789 the given file handle.
790 See L<seccomp_export_bpf(3)>.
792 =item I<$ctx>->B<load>
794 Loads the filter into the kernel.
795 See L<seccomp_load(3)>.
801 None exported by default. These functions die on error.
807 Returns the arch token for the native architecture.
808 See L<seccomp_arch_add(3)>.
810 =item B<arch_resolve_name>(I<$arch_name>)
812 Returns the arch token for a named architecture.
813 See L<seccomp_arch_add(3)>.
815 =item B<syscall_resolve_name>(I<$name>)
817 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.
818 See L<seccomp_syscall_resolve_name(3)>.
820 =item B<syscall_resolve_name_arch>(I<$arch_token>, I<$name>)
822 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.
823 See L<seccomp_syscall_resolve_name(3)>.
825 =item B<syscall_resolve_name_rewrite>(I<$arch_token>, I<$name>)
827 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.
828 See L<seccomp_syscall_resolve_name(3)>.
830 =item B<syscall_resolve_num_arch>(I<$arch_token>, I<$num>)
832 Returns the name of the system call with the given number on the given architecture.
833 See L<seccomp_syscall_resolve_name(3)>.
837 Returns the version of libseccomp as a three-element arrayref:
838 [$major_version, $minor_version, $micro_version].
844 All exported by default. Most of the SCMP_ constants were seen above.
845 Here is a list of all of them:
857 SCMP_ARCH_MIPSEL64N32
874 SCMP_FLTATR_ACT_BADARCH
875 SCMP_FLTATR_ACT_DEFAULT
877 SCMP_FLTATR_CTL_TSYNC
878 SCMP_FLTATR_API_TSKIP
883 Besides the SCMP_ constants, the module also provides a long list of
884 __NR_syscall and __PNR_syscall constants that represent real and
885 pseudo syscall numbers for many common system calls. A full list can
886 be found in the source code of this module. See also the
887 B<syscall_resolve_name> family of functions above which is more
888 flexible than this set of constants.
892 L<https://github.com/seccomp/libseccomp>
896 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
898 =head1 COPYRIGHT AND LICENSE
900 Copyright (C) 2016 by Marius Gavrilescu
902 This library is free software; you can redistribute it and/or modify
903 it under the same terms as Perl itself, either Perl version 5.24.0 or,
904 at your option, any later version of Perl 5 you may have available.