seccomp-tools 1.6.2 → 1.7.1

data/lib/seccomp-tools/cli/dump.rb

@@ -1,39 +1,37 @@
 # frozen_string_literal: true
 
-require 'shellwords'
-
 require 'seccomp-tools/cli/base'
+require 'seccomp-tools/cli/filter_input'
 require 'seccomp-tools/disasm/disasm'
 require 'seccomp-tools/dumper'
-require 'seccomp-tools/logger'
 
 module SeccompTools
   module CLI
     # Handle 'dump' command.
     class Dump < Base
+      include FilterInput
+
       # Summary of this command.
-      SUMMARY = 'Automatically dump seccomp bpf from execution file(s).'
+      SUMMARY = 'Automatically dump seccomp bpf from executable(s).'
       # Usage of this command.
-      USAGE = "dump - #{SUMMARY}\nNOTE : This function is only available on Linux." \
-              "\n\nUsage: seccomp-tools dump [exec] [options]".freeze
+      USAGE = "dump - #{SUMMARY}\nNOTE: This command is only available on Linux." \
+              "\n\nUsage: seccomp-tools dump [EXEC] [options]".freeze
 
+      # Instantiate a {Dump} object, dumping the first filter as disassembly by default.
+      #
+      # Takes the same arguments as {Base#initialize}.
       def initialize(*)
         super
         option[:format] = :disasm
-        option[:limit] = 1
-        option[:pid] = nil
       end
 
       # Define option parser.
       # @return [OptionParser]
+      #   The parser of this command's options.
       def parser
         @parser ||= OptionParser.new do |opt|
           opt.banner = usage
-          opt.on('-c', '--sh-exec <command>', 'Executes the given command (via sh).',
-                 'Use this option if want to pass arguments or do pipe things to the execution file.',
-                 'e.g. use `-c "./bin > /dev/null"` to dump seccomp without being mixed with stdout.') do |command|
-            option[:command] = command
-          end
+          option_filter_source(opt, 'dump')
 
           opt.on('-f', '--format FORMAT', %i[disasm raw inspect],
                  'Output format. FORMAT can only be one of <disasm|raw|inspect>.',
@@ -41,55 +39,42 @@ module SeccompTools
                    option[:format] = f
                  end
 
-          opt.on('-l', '--limit LIMIT', 'Limit the number of calling "prctl(PR_SET_SECCOMP)".',
-                 'The target process will be killed whenever its calling times reaches LIMIT.',
-                 'Default: 1', Integer) do |l|
-                   option[:limit] = l
-                 end
-
-          opt.on('-o', '--output FILE', 'Output result into FILE instead of stdout.',
+          opt.on('-o', '--output FILE', 'Write output to FILE instead of stdout.',
                  'If multiple seccomp syscalls have been invoked (see --limit),',
-                 'results will be written to FILE, FILE_1, FILE_2.. etc.',
-                 'For example, "--output out.bpf" and the output files are out.bpf, out_1.bpf, ...') do |o|
+                 'results are written to FILE, FILE_1, FILE_2, etc.',
+                 'For example, with "--output out.bpf" the output files are out.bpf, out_1.bpf, ...') do |o|
                    option[:ofile] = o
                  end
-
-          opt.on('-p', '--pid PID', 'Dump installed seccomp filters of the existing process.',
-                 'You must have CAP_SYS_ADMIN (e.g. be root) in order to use this option.',
-                 Integer) do |p|
-            option[:pid] = p
-          end
         end
       end
 
-      # Handle options.
+      # Traces the target process and writes out the seccomp filters it installs.
+      #
+      # Only available on Linux, logs an error and returns otherwise.
       # @return [void]
       def handle
-        return Logger.error('Dump is only available on Linux.') unless Dumper::SUPPORTED
+        return unless dumping_supported?
         return unless super
 
-        block = lambda do |bpf, arch|
-          case option[:format]
-          when :inspect then output { "\"#{bpf.bytes.map { |b| format('\\x%02X', b) }.join}\"\n" }
-          when :raw then output { bpf }
-          when :disasm then output { SeccompTools::Disasm.disasm(bpf, arch:) }
-          end
-        end
-        if option[:pid].nil?
-          option[:command] = argv.shift unless argv.empty?
-          SeccompTools::Dumper.dump('/bin/sh', '-c', option[:command], limit: option[:limit], &block)
-        else
-          begin
-            SeccompTools::Dumper.dump_by_pid(option[:pid], option[:limit], &block)
-          rescue Errno::EPERM, Errno::EACCES => e
-            Logger.error(<<~EOS)
-            #{e}
-            PTRACE_SECCOMP_GET_FILTER requires CAP_SYS_ADMIN
-            Try:
-                sudo env "PATH=$PATH" #{(%w[seccomp-tools] + ARGV).shelljoin}
-            EOS
-            exit(1)
-          end
+        collect_filters.each { |bpf, arch| emit(bpf, arch) }
+      end
+
+      private
+
+      # A positional argument is always an executable to trace, never a raw BPF blob to read: that is
+      # +disasm+'s job, and a non-ELF executable (a shell script wrapping the target) must still run.
+      # @return [Boolean]
+      def accepts_raw_bpf?
+        false
+      end
+
+      # Writes one dumped filter in the requested format.
+      # @return [void]
+      def emit(bpf, arch)
+        case option[:format]
+        when :inspect then output { "\"#{bpf.bytes.map { |b| format('\\x%02X', b) }.join}\"\n" }
+        when :raw then output { bpf }
+        when :disasm then output { SeccompTools::Disasm.disasm(bpf, arch:) }
         end
       end
     end

data/lib/seccomp-tools/cli/dumpable.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+require 'seccomp-tools/dumper'
+require 'seccomp-tools/logger'
+
+module SeccompTools
+  module CLI
+    # Shared helpers for the commands that dump seccomp filters via ptrace ({Dump} and {Explain}).
+    module Dumpable
+      # Dumps the seccomp filters from a command run via +sh+, or from an existing process, yielding
+      # each installed filter.
+      #
+      # When +pid+ is given the process is traced (requiring +CAP_SYS_ADMIN+); otherwise +command+
+      # is executed. On a permission error while tracing a pid, {#dump_permission_error} exits.
+      # Warns when nothing was installed, so a caller that produces no output still tells the user why.
+      # @param [String?] command
+      #   The command to run, when +pid+ is +nil+.
+      # @param [Integer?] pid
+      #   The process to trace, or +nil+ to run +command+.
+      # @param [Integer] limit
+      #   Stop after this many installed filters.
+      # @param [Float?] timeout
+      #   Seconds to wait for +command+, ignored when tracing a pid.
+      # @yieldparam [String] bpf
+      #   One installed filter, as raw bytes.
+      # @yieldparam [Symbol?] arch
+      #   The architecture of the traced process, if known.
+      # @return [Array]
+      #   One entry per filter: the block's return values. Empty when nothing was installed.
+      def dump_seccomp(command:, pid:, limit:, timeout:, &)
+        filters = if pid
+                    dump_seccomp_by_pid(pid, limit, &)
+                  else
+                    SeccompTools::Dumper.dump('/bin/sh', '-c', command, limit:, timeout:, &)
+                  end
+        Logger.warn('No seccomp filter was installed.') if filters.empty?
+        filters
+      end
+
+      # Whether tracer-based dumping is available on this platform (Linux only). Logs an error when
+      # it is not, so callers can guard with +return unless dumping_supported?+.
+      # @return [Boolean]
+      def dumping_supported?
+        return true if SeccompTools::Dumper::SUPPORTED
+
+        Logger.error('Dumping a filter from an executable or process is only available on Linux.')
+        false
+      end
+
+      private
+
+      # Traces +pid+, translating a permission error into the standard hint.
+      def dump_seccomp_by_pid(pid, limit, &)
+        SeccompTools::Dumper.dump_by_pid(pid, limit, &)
+      rescue Errno::EPERM, Errno::EACCES => e
+        dump_permission_error(e)
+      end
+
+      # Reports a permission error from tracing a process and exits.
+      #
+      # Dumping a filter by pid needs +CAP_SYS_ADMIN+ for +PTRACE_SECCOMP_GET_FILTER+.
+      # @param [SystemCallError] err
+      #   The +Errno::EPERM+ or +Errno::EACCES+ that was raised.
+      # @raise [SystemExit]
+      #   Always; the process is terminated with exit status 1.
+      def dump_permission_error(err)
+        Logger.error(<<~EOS)
+          #{err}
+          PTRACE_SECCOMP_GET_FILTER requires CAP_SYS_ADMIN
+          Try:
+              sudo env "PATH=$PATH" #{(%w[seccomp-tools] + ARGV).shelljoin}
+        EOS
+        exit(1)
+      end
+    end
+  end
+end

data/lib/seccomp-tools/cli/emu.rb

@@ -17,6 +17,9 @@ module SeccompTools
       # Usage of this command.
       USAGE = "emu - #{SUMMARY}\n\nUsage: seccomp-tools emu [options] BPF_FILE [sys_nr [arg0 [arg1 ... arg5]]]".freeze
 
+      # Instantiate an {Emu} object, defaulting to verbose output.
+      #
+      # Takes the same arguments as {Base#initialize}.
       def initialize(*)
         super
         option[:verbose] = 1
@@ -24,6 +27,7 @@ module SeccompTools
 
       # Define option parser.
       # @return [OptionParser]
+      #   The parser of this command's options.
       def parser
         @parser ||= OptionParser.new do |opt|
           opt.banner = usage
@@ -40,7 +44,7 @@ module SeccompTools
         end
       end
 
-      # Handle options.
+      # Emulates the filter against the given syscall and shows the resulting action.
       # @return [void]
       def handle
         return unless super
@@ -75,17 +79,28 @@ module SeccompTools
 
       private
 
+      # Resolves a syscall given on the command line, by name or by number.
+      #
       # @param [String] str
+      #   A syscall name valid for +option[:arch]+, or an integer literal.
       # @return [Integer]
+      #   The syscall number.
+      # @raise [ArgumentError]
+      #   If +str+ is neither a known syscall name nor a valid integer.
       def evaluate_sys_nr(str)
         consts = SeccompTools::Const::Syscall.const_get(option[:arch].to_s.upcase)
         consts[str.to_sym] || Integer(str)
       end
 
-      # output the path during emulation
+      # Outputs the disassembly, highlighting the lines that were executed during emulation.
+      #
       # @param [Array<String>] disasm
-      # @param [Set] trace
-      # @param [{Symbol => Object}] result
+      #   Lines of the disassembly, including the two header lines.
+      # @param [Set<Integer>] trace
+      #   Line numbers that were reached.
+      # @param [{Symbol => Integer}] result
+      #   The emulation result, as returned by {SeccompTools::Emulator#run}.
+      # @return [void]
       def output_emulate_path(disasm, trace, result)
         output { disasm.shift }
         output { disasm.shift }
@@ -95,7 +110,7 @@ module SeccompTools
 
             Util.colorize(line, t: :gray)
           end
-          # Too much remain, omit them.
+          # Too many lines remain; omit them.
           rem = disasm.size - idx - 1
           break output { Util.colorize("... (omitting #{rem} lines)\n", t: :gray) } if rem > 3 && idx > result[:pc] + 4
         end

data/lib/seccomp-tools/cli/explain.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/cli/base'
+require 'seccomp-tools/cli/filter_input'
+require 'seccomp-tools/disasm/disasm'
+require 'seccomp-tools/explain'
+require 'seccomp-tools/logger'
+
+module SeccompTools
+  module CLI
+    # Handle 'explain' command.
+    class Explain < Base
+      include FilterInput
+
+      # Summary of this command.
+      SUMMARY = 'Summarize a seccomp filter as a per-action policy.'
+      # Usage of this command.
+      USAGE = "explain - #{SUMMARY}\n\nUsage: seccomp-tools explain [options] [BPF_FILE|EXEC]".freeze
+
+      # Define option parser.
+      # @return [OptionParser]
+      #   The parser of this command's options.
+      def parser
+        @parser ||= OptionParser.new do |opt|
+          opt.banner = usage
+
+          option_filter_source(opt, 'explain')
+          option_arch(opt, 'With an executable or --pid the architecture is auto-detected instead.')
+        end
+      end
+
+      # Reads the filter(s) from a BPF file, an executable, or an existing process, then prints the
+      # policy of each.
+      # @return [void]
+      def handle
+        return unless super
+
+        filters = collect_filters
+        if filters.size > 1
+          Logger.warn("#{filters.size} filters are installed; they stack, so a syscall must pass every one " \
+                      '(most restrictive wins). Each is explained separately below.')
+        end
+        filters.each_with_index do |(raw, arch, source), idx|
+          label = filters.size > 1 ? "#{source} (filter ##{idx})" : source
+          insts = SeccompTools::Disasm.to_bpf(raw, arch).map(&:inst)
+          output { SeccompTools::Explain.new(insts, arch:, source: label).summarize.to_s }
+        end
+      end
+    end
+  end
+end

data/lib/seccomp-tools/cli/filter_input.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/cli/dumpable'
+require 'seccomp-tools/logger'
+require 'seccomp-tools/util'
+
+module SeccompTools
+  module CLI
+    # Shared input handling for the commands that take a seccomp filter from a BPF file, stdin, an
+    # executable, or a running process ({Explain} and {Audit}): it resolves the positional argument
+    # and options into +[raw_bpf, arch, source]+ tuples, dumping via ptrace ({Dumpable}) when the
+    # input is a command or +--pid+. The including command must provide +option+, +argv+, +parser+,
+    # +input+ and +warn_ignored_arguments+ (all from {Base}).
+    module FilterInput
+      include Dumpable
+
+      private
+
+      # Registers the options every command taking its filter from a process shares - +-c/--sh-exec+,
+      # +-l/--limit+, +-p/--pid+ and +-t/--timeout+ - and their defaults, so the four stay described
+      # and parsed the same way wherever they appear. The counterpart of {Base#option_arch}.
+      #
+      # The descriptions hold for every including command, because the behaviour they describe lives
+      # in the shared code: {#collect_filters} gives +-c+ precedence, and {Dumpable#dump_seccomp}
+      # passes +--timeout+ only when running an executable, never when attaching to a +--pid+.
+      # @param [OptionParser] opt
+      # @param [String] action
+      #   What the command does with each filter, woven into the descriptions.
+      # @return [void]
+      # @example
+      #   option_filter_source(opt, 'explain')
+      def option_filter_source(opt, action)
+        option[:limit] = 1
+        opt.on('-c', '--sh-exec <command>', "Executes the given command (via sh) and #{action}s its seccomp.",
+               'Use this to pass arguments or pipe things to the executable.',
+               'e.g. use `-c "./bin > /dev/null"` to keep the program output out of the result.',
+               'Takes precedence over the positional argument.') { |command| option[:command] = command }
+
+        opt.on('-l', '--limit LIMIT', Integer, "#{action.capitalize} only the first LIMIT installed filters.",
+               'Only meaningful when the input is an executable or --pid. Default: 1',
+               'An executable is killed once it reaches LIMIT.') { |l| option[:limit] = l }
+
+        opt.on('-p', '--pid PID', Integer, "#{action.capitalize} the seccomp filters installed on an existing process.",
+               'You must have CAP_SYS_ADMIN (e.g. be root) to use this option.') { |p| option[:pid] = p }
+
+        opt.on('-t', '--timeout SEC', Float, 'Timeout (seconds) for the execution. Default: no timeout',
+               'This option is ignored when --pid is given.') { |t| option[:timeout] = t }
+      end
+
+      # Resolves the input into an array of +[raw_bpf, arch, source]+ tuples, empty when there is
+      # nothing to process (help shown, or an error was logged).
+      #
+      # The input is one of three kinds:
+      # * a running process, when +--pid+ is given;
+      # * a raw BPF file (or stdin), when the positional argument is not an executable;
+      # * a command to run and trace - either +-c+, or a positional executable.
+      # @return [Array<Array(String, Symbol, String?)>]
+      def collect_filters
+        # -c/--sh-exec and --pid take precedence over a positional BPF file or executable.
+        option[:ifile] = argv.shift unless option[:command] || option[:pid]
+        warn_ignored_arguments
+
+        return dump_filters(command: nil, pid: option[:pid], source: "pid #{option[:pid]}") if option[:pid]
+
+        command = option[:command] || option[:ifile]
+        if command.nil? # nothing to process
+          CLI.show(parser.help)
+          return []
+        end
+        return read_raw_bpf if raw_bpf_file?
+
+        dump_filters(command:, pid: nil, source: command)
+      end
+
+      # Reads the positional file (or stdin) as a raw BPF blob, logging an error instead of
+      # crashing when it cannot be read.
+      # @return [Array<Array(String, Symbol, String?)>]
+      def read_raw_bpf
+        [[input, option[:arch], source_name(option[:ifile])]]
+      rescue SystemCallError => e
+        Logger.error(e.message)
+        []
+      end
+
+      # Should the input be read directly as a raw BPF blob, rather than run as a command? True when
+      # the command accepts blobs at all, no +-c+ was given, and the positional argument is not an
+      # executable (a plain file or stdin).
+      # @return [Boolean]
+      def raw_bpf_file?
+        accepts_raw_bpf? && !option[:command] && !executable?(option[:ifile])
+      end
+
+      # Does a positional argument that is not an ELF mean "read this filter"? True for the commands
+      # that analyze a filter ({Explain}, {Audit}); {Dump} overrides it to +false+, because its
+      # positional is always something to execute - a shell script is not an ELF but must still be
+      # run, not parsed as BPF.
+      # @return [Boolean]
+      def accepts_raw_bpf?
+        true
+      end
+
+      # Dumps filters from a command or pid and labels each with +source+.
+      # @return [Array<Array(String, Symbol, String?)>]
+      #   The filter tuples, empty when dumping is unsupported or nothing was installed.
+      def dump_filters(command:, pid:, source:)
+        return [] unless dumping_supported?
+
+        dump_seccomp(command:, pid:, limit: option[:limit], timeout: option[:timeout]) do |bpf, arch|
+          [bpf, arch || option[:arch], source]
+        end
+      end
+
+      # Is +file+ an ELF executable to run, rather than a raw BPF blob or stdin to read?
+      # @param [String?] file
+      #   The path to check. +nil+ (no argument) and +-+ (stdin) are not executables.
+      # @return [Boolean]
+      def executable?(file)
+        file && file != '-' && Util.elf?(file)
+      end
+
+      # The label shown in the header for +file+; +<STDIN>+ when reading from stdin.
+      # @param [String] file
+      #   The input path, or +-+ for stdin.
+      # @return [String]
+      def source_name(file)
+        file == '-' ? '<STDIN>' : file
+      end
+    end
+  end
+end

data/lib/seccomp-tools/const.rb

@@ -5,15 +5,48 @@ module SeccompTools
   module Const
     # For BPF / seccomp.
     module BPF
+      # Byte offsets of the fields of the filter's input buffer:
+      #   struct seccomp_data {
+      #     int nr;                     // SYS_NUMBER
+      #     __u32 arch;                 // ARCH
+      #     __u64 instruction_pointer;  // INSTRUCTION_POINTER
+      #     __u64 args[6];              // ARGS
+      #   };
+      # The 64-bit fields are each two 32-bit words a filter loads separately (see {QWORD_BASES}).
+      module SeccompData
+        # Byte offset of the syscall number.
+        SYS_NUMBER = 0
+        # Byte offset of the architecture.
+        ARCH = 4
+        # Byte offset of the instruction pointer.
+        INSTRUCTION_POINTER = 8
+        # Byte offset of the first 64-bit argument.
+        ARGS = 16
+        # Total size in bytes; the +len+ load returns this.
+        SIZE = 64
+        # Byte offsets of the 64-bit fields (+instruction_pointer+ and the six arguments), each a
+        # pair of 32-bit words.
+        QWORD_BASES = [INSTRUCTION_POINTER, *(ARGS...SIZE).step(8)].freeze
+        # Display names of the fixed (non-argument) fields, keyed by byte offset. For the 64-bit
+        # +instruction_pointer+ this is the field's base name; a high-word load appends +>> 32+.
+        NAMES = { SYS_NUMBER => 'sys_number', ARCH => 'arch', INSTRUCTION_POINTER => 'instruction_pointer' }.freeze
+      end
+
       # sizeof(struct seccomp_data)
-      SIZEOF_SECCOMP_DATA = 64
+      SIZEOF_SECCOMP_DATA = SeccompData::SIZE
 
       # option set seccomp
       PR_SET_SECCOMP = 22
 
+      # strict mode
+      SECCOMP_MODE_STRICT = 1
+
       # filter mode
       SECCOMP_MODE_FILTER = 2
 
+      # For syscall +seccomp+
+      SECCOMP_SET_MODE_STRICT = 0
+
       # For syscall +seccomp+
       SECCOMP_SET_MODE_FILTER = 1
 
@@ -86,7 +119,8 @@ module SeccompTools
         lsh: 0x60,
         rsh: 0x70,
         neg: 0x80,
-        # mod: 0x90, # not support
+        # mod (0x90) is intentionally omitted: the kernel's seccomp_check_filter() allowlist rejects
+        # BPF_MOD (EINVAL), so it can never appear in a loadable seccomp filter.
         xor: 0xa0
       }.freeze
 
@@ -95,6 +129,24 @@ module SeccompTools
         tax: 0x00,
         txa: 0x80
       }.freeze
+
+      # The action a seccomp return +value+ names, e.g. +"ALLOW"+ or +"ERRNO(5)"+, or +nil+ when
+      # the action bits are not a value the kernel defines. The data part is shown for the actions
+      # that consume it: +ERRNO+ always, and +TRACE+/+TRAP+ when non-zero (0 is their idle default).
+      # The result is both human-readable and re-assemblable.
+      # @param [Integer] value
+      # @return [String?]
+      def self.action_label(value)
+        action = ACTION.invert[value & SECCOMP_RET_ACTION_FULL]
+        return if action.nil?
+
+        data = value & SECCOMP_RET_DATA
+        case action
+        when :ERRNO then "ERRNO(#{data})"
+        when :TRACE, :TRAP then data.zero? ? action.to_s : "#{action}(#{data})"
+        else action.to_s
+        end
+      end
     end
 
     # Define syscall numbers for all architectures.
@@ -104,17 +156,21 @@ module SeccompTools
 
       # To dynamically fetch constants from files.
       # @param [Symbol] cons
-      #   Name of const.
-      # @return [Object]
-      #   Value of that +cons+.
+      #   Name of const, an upcased architecture name such as +:AMD64+.
+      # @return [{Symbol => Integer}]
+      #   The syscall table of that architecture, mapping name to number.
+      # @raise [NameError]
+      #   If no syscall table exists for +cons+.
       def const_missing(cons)
         load_const(cons) || super
       end
 
       # Load from file and define const value.
       # @param [Symbol] cons
-      #   Name of const.
-      # @return [Object]
+      #   Name of const, an upcased architecture name such as +:AMD64+.
+      # @return [{Symbol => Integer}?]
+      #   The syscall table of that architecture, or +nil+ if it has no file under
+      #   +consts/sys_nr/+.
       def load_const(cons)
         arch = cons.to_s.downcase
         filename = File.join(__dir__, 'consts', 'sys_nr', "#{arch}.rb")
@@ -124,6 +180,10 @@ module SeccompTools
       end
 
       # Helper for loading syscall prototypes from generated sys_arg.rb.
+      #
+      # @return [{Symbol => Array<String>}]
+      #   Syscall name to its argument names. Lookups of an +x32_+-prefixed name fall back to the
+      #   unprefixed one, and unknown names give +nil+.
       def load_args
         hash = instance_eval(File.read(File.join(__dir__, 'consts', 'sys_arg.rb')))
         Hash.new do |_h, k|
@@ -145,6 +205,7 @@ module SeccompTools
         amd64: 'ARCH_X86_64',
         i386: 'ARCH_I386',
         aarch64: 'ARCH_AARCH64',
+        riscv64: 'ARCH_RISCV64',
         s390x: 'ARCH_S390X'
       }.freeze
 
@@ -153,19 +214,41 @@ module SeccompTools
         'ARCH_X86_64' => 0xc000003e,
         'ARCH_I386' => 0x40000003,
         'ARCH_AARCH64' => 0xc00000b7,
+        'ARCH_RISCV64' => 0xc00000f3,
         'ARCH_S390X' => 0x80000016
       }.freeze
+
+      # The architecture symbol (e.g. +:amd64+) for an +AUDIT_ARCH_*+ value, or +nil+ when it is
+      # not one seccomp-tools knows.
+      # @param [Integer] audit_val
+      # @return [Symbol?]
+      def self.arch_symbol(audit_val)
+        name = ARCH.invert[audit_val]
+        name && ARCH_NAME.invert[name]
+      end
     end
 
-    # Endianess constants.
+    # Endianness constants.
     module Endian
-      # Defining default endianess of architectures.
-      ENDIAN = {
-        i386: '<',
-        amd64: '<',
-        aarch64: '<',
-        s390x: '>'
-      }.freeze
+      # +__AUDIT_ARCH_LE+ from +uapi/linux/audit.h+: the bit an +AUDIT_ARCH_*+ value carries iff
+      # the architecture is little-endian. The kernel encodes endianness in the arch token itself,
+      # so it never needs to be guessed from an architecture's name.
+      AUDIT_ARCH_LE = 0x40000000
+
+      # Endianness of each architecture as a pack/unpack format modifier, derived from the
+      # {Audit::ARCH} values instead of being maintained by hand.
+      ENDIAN = Audit::ARCH_NAME.transform_values do |name|
+        Audit::ARCH[name].anybits?(AUDIT_ARCH_LE) ? '<' : '>'
+      end.freeze
+
+      # Whether +arch+ is big-endian, i.e. stores the high 32-bit word of a 64-bit +seccomp_data+
+      # field (+instruction_pointer+ or an argument) first. See +arch_arg_offset_lo/hi+ in
+      # libseccomp and the +syscall_arg+ macro of the kernel's seccomp selftests.
+      # @param [Symbol] arch
+      # @return [Boolean]
+      def self.big?(arch)
+        ENDIAN[arch] == '>'
+      end
     end
   end
 end