seccomp-tools 1.6.1 → 1.7.0

data/lib/seccomp-tools/audit/checks.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/checks/arch_unchecked'
+require 'seccomp-tools/audit/checks/dangerous_allow'
+require 'seccomp-tools/audit/checks/orw_chain'
+require 'seccomp-tools/audit/checks/permissive_default'
+require 'seccomp-tools/audit/checks/syscall_alt_gap'
+require 'seccomp-tools/audit/checks/x32_guard'
+
+module SeccompTools
+  class Audit
+    # The registries the {Audit} engine runs. A check is anything answering +call+ and returning
+    # {Finding}s; which registry it is listed in decides both how often it runs and what it is
+    # handed, so adding one is a single entry here rather than a change to the engine.
+    #
+    # * {FILTER} - asked once about the whole filter, and handed the {Explain::Analysis}. For
+    #   questions no single architecture can answer, such as whether the filter checks the
+    #   architecture at all.
+    # * {SECTION} / {SECTION_BY_ARCH} - asked once per architecture, and handed that architecture's
+    #   {Policy}. {SECTION_BY_ARCH} keeps a quirk confined to the architecture that has it, so it is
+    #   a one-line entry rather than a branch inside a check.
+    module Checks
+      # Whole-filter checks; each takes the {Explain::Analysis}.
+      FILTER = [ArchUnchecked].freeze
+
+      # Per-architecture checks that apply everywhere; each takes a {Policy}.
+      SECTION = [PermissiveDefault, SyscallAltGap, OrwChain, DangerousAllow].freeze
+
+      # Per-architecture checks that apply only to the keyed architecture (amd64's x32 is the exemplar).
+      SECTION_BY_ARCH = { amd64: [X32Guard] }.freeze
+
+      module_function
+
+      # The per-architecture checks to run for +arch_sym+: the common ones plus any it alone has.
+      # @param [Symbol?] arch_sym
+      # @return [Array]
+      def section_checks(arch_sym)
+        SECTION + SECTION_BY_ARCH.fetch(arch_sym, [])
+      end
+    end
+  end
+end

data/lib/seccomp-tools/audit/finding.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SeccompTools
+  class Audit
+    # Severities, most to least severe. Drives ordering and (for +human+ output) coloring.
+    SEVERITIES = %i[high medium low].freeze
+
+    # One weakness reported by a {Check}: a stable +id+, a +severity+, a human +title+/+detail+, the
+    # architecture it applies to, the syscalls involved, an optional argument +condition+ under which
+    # it holds, and a one-line +remediation+.
+    Finding = Struct.new(:id, :severity, :title, :detail, :arch, :syscalls, :condition, :remediation,
+                         keyword_init: true) do
+      # Sort key: by severity, then id, then the affected syscalls.
+      # @return [Array]
+      def rank
+        [SEVERITIES.index(severity) || SEVERITIES.size, id, Array(syscalls).join(',')]
+      end
+
+      # @return [Hash] JSON-ready shape.
+      def to_h
+        { id:, severity:, title:, detail:, arch:, syscalls: Array(syscalls), condition:, remediation: }
+      end
+    end
+  end
+end

data/lib/seccomp-tools/audit/policy.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+require 'seccomp-tools/explain/qword'
+require 'seccomp-tools/explain/renderer'
+require 'seccomp-tools/explain/verdict'
+require 'seccomp-tools/symbolic/constraint'
+
+module SeccompTools
+  class Audit
+    # One architecture's view of a filter: given a syscall number, which actions can an attacker
+    # reach? Built from that arch's section leaves (already arch-filtered by {Explain::Analysis}).
+    #
+    # A leaf is reachable for syscall +nr+ when every plain +sys_number+ fact on its path is satisfied
+    # by +nr+ - this one predicate covers +==+, ranges, and +jset+ bit-tests (so it sees an x32 guard
+    # written either way). Argument and opaque facts are *not* consulted: arguments are
+    # attacker-controlled and the executor already dropped self-contradictory paths, so a surviving
+    # leaf is reachable under some argument choice. The stance is deliberately conservative - "could an
+    # attacker reach this action?".
+    class Policy
+      SYS = Const::BPF::SeccompData::SYS_NUMBER
+
+      # @return [Integer?] The +AUDIT_ARCH+ value (+nil+ when the filter never branches on +arch+).
+      attr_reader :arch_val
+      # @return [Symbol?] The architecture symbol whose syscall names apply (+nil+ when unknown).
+      attr_reader :arch_sym
+      # @return [Object] Display title for this section (arch symbol or +0x... (unknown)+).
+      attr_reader :title
+      # @return [Array<Symbolic::Executor::Leaf>] This section's leaves.
+      attr_reader :leaves
+
+      # @param [Explain::Analysis] analysis
+      # @param [Array] section One +[arch_val, arch_sym, title, leaves]+ entry from {Explain::Analysis#sections}.
+      def initialize(analysis, section)
+        @analysis = analysis
+        @arch_val, @arch_sym, @title, @leaves = section
+        @fusion = @arch_sym && Explain::QwordFusion.new(@arch_sym)
+        @renderer = @fusion && Explain::Renderer.new(@fusion)
+      end
+
+      # A display name for this section's architecture (+"amd64"+, or +"0x... (unknown)"+).
+      # @return [String]
+      def arch_name
+        (@arch_sym || @title).to_s
+      end
+
+      # This arch's +name => number+ table, or +nil+ when the section has no known architecture.
+      #
+      # +@arch_sym+ is always +nil+ or a supported architecture (the CLI rejects an undetectable host
+      # before we get here), so the table lookup never fails.
+      # @return [Hash{Symbol=>Integer}?]
+      def table
+        return @table if defined?(@table)
+
+        @table = @arch_sym && Const::Syscall.const_get(@arch_sym.upcase)
+      end
+
+      # The number of syscall +name+ on this arch, or +nil+ if the arch lacks it.
+      # @param [Symbol] name
+      # @return [Integer?]
+      def number(name)
+        table && table[name]
+      end
+
+      # The action of the catch-all (default) path, e.g. +"ALLOW"+ / +"ERRNO(5)"+.
+      # @return [String?]
+      def default_label
+        @analysis.default_label(@leaves)
+      end
+
+      # The distinct actions reachable for syscall number +nr+.
+      # @param [Integer] nr
+      # @return [Array<String>]
+      def reachable_actions(nr)
+        reachable_leaves(nr).map { |l| Explain::Verdict.label(l.ret) }.uniq
+      end
+
+      # Can syscall +nr+ reach +ALLOW+?
+      # @param [Integer] nr
+      # @return [Boolean]
+      def reachable_as_allow?(nr)
+        reachable_leaves(nr).any? { |l| Explain::Verdict.label(l.ret) == 'ALLOW' }
+      end
+
+      # Was syscall +nr+ singled out for denial (a rule pins +sys_number == nr+ to a non-+ALLOW+
+      # action), as opposed to merely being absent from an allowlist? Distinguishes a real
+      # "blocked one equivalent but not another" gap from allowlist omissions.
+      # @param [Integer] nr
+      # @return [Boolean]
+      def explicitly_denied?(nr)
+        !reachable_as_allow?(nr) &&
+          @leaves.any? { |l| @analysis.facts(l).sys_eq == nr && Explain::Verdict.label(l.ret) != 'ALLOW' }
+      end
+
+      # The argument condition under which +nr+ reaches +action+, rendered like +explain+
+      # (+"filename == 0x..."+), or +nil+ when it is unconditional or the arch is unknown.
+      # @param [Integer] nr
+      # @param [String] action
+      # @return [String?]
+      def condition_for(nr, action = 'ALLOW')
+        return nil unless @renderer
+
+        ls = reachable_leaves(nr).select { |l| Explain::Verdict.label(l.ret) == action }
+        conds = @fusion.merge_or(ls.map { |l| @analysis.facts(l).residual })
+                       .map { |list| @renderer.conjunction(@fusion.fold(list), name_of(nr)) }.uniq
+        conds.include?('') ? nil : conds.join(' or ')
+      end
+
+      private
+
+      def name_of(nr)
+        table && table.invert[nr]
+      end
+
+      def reachable_leaves(nr)
+        @leaves.select { |l| sys_satisfied?(l, nr) }
+      end
+
+      def sys_satisfied?(leaf, nr)
+        leaf.path.all? do |c|
+          !c.plain_data_fact?(SYS) || Symbolic::Constraint.evaluate(nr, c.op, c.rhs.val)
+        end
+      end
+    end
+  end
+end

data/lib/seccomp-tools/audit/report.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/finding'
+require 'seccomp-tools/util'
+
+module SeccompTools
+  class Audit
+    # The findings for one filter, rendered either as a human report or a JSON-ready hash.
+    class Report
+      # Severity => {Util.colorize} theme for the +[SEVERITY]+ tag.
+      SEVERITY_THEME = { high: :error, medium: :warn, low: :info }.freeze
+
+      # Widest a rendered line may get, so a finding reads without wrapping on a standard terminal.
+      WIDTH = 120
+
+      # @param [String?] source Label for the audited filter.
+      # @param [Array<String>] arches The architectures covered.
+      # @param [Array<Finding>] findings
+      # @param [Boolean] truncated Whether the symbolic walk was cut short.
+      def initialize(source:, arches:, findings:, truncated:)
+        @source = source
+        @arches = arches
+        @findings = findings.sort_by(&:rank)
+        @truncated = truncated
+      end
+
+      # @return [Array<Finding>]
+      attr_reader :findings
+      # @return [Array<String>] The architectures covered.
+      attr_reader :arches
+
+      # The human report.
+      # @return [String]
+      def to_s
+        out = +''
+        out << "Seccomp audit of #{@source}\n" if @source
+        out << "Architectures: #{@arches.join(', ')}\n" unless @arches.empty?
+        # A truncated walk can only hide weaknesses, so it qualifies the whole report rather than
+        # being a finding of its own.
+        out << "WARNING: analysis truncated (filter too large); results may be incomplete.\n" if @truncated
+        return out << "\nNo weaknesses found.\n" if @findings.empty?
+
+        @findings.each { |f| out << render(f) }
+        out
+      end
+
+      # @return [Hash] JSON-ready shape for one filter.
+      def to_h
+        { source: @source, arches: @arches, truncated: @truncated, findings: @findings.map(&:to_h) }
+      end
+
+      private
+
+      def render(finding)
+        tag = Util.colorize("[#{finding.severity.to_s.upcase}]", t: SEVERITY_THEME[finding.severity])
+        arch = finding.arch ? " (#{Util.colorize(finding.arch, t: :arch)})" : ''
+        names = finding.syscalls
+        out = "\n#{tag} #{highlight(finding.title, names)}#{arch}\n"
+        out << paragraph(finding.detail, names, '    ', '    ')
+        out << paragraph(finding.condition, names, '    when: ', '          ') if finding.condition
+        out << paragraph(finding.remediation, names, '    fix:  ', '          ') if finding.remediation
+        out
+      end
+
+      # +text+ wrapped to {WIDTH} columns, its first line prefixed with +first+ and the rest with
+      # +hang+ so they read as one block. Wrapping is measured before coloring, so the invisible
+      # escape codes never count towards the width.
+      # @return [String]
+      def paragraph(text, names, first, hang)
+        lines = []
+        indent = first
+        line = nil
+        text.to_s.split(/\s+/).each do |word|
+          if line.nil?
+            line = word
+          elsif indent.size + line.size + 1 + word.size <= WIDTH
+            line = "#{line} #{word}"
+          else
+            lines << (indent + line)
+            indent = hang
+            line = word
+          end
+        end
+        lines << (indent + line) if line
+        lines.map { |l| "#{highlight(l, names)}\n" }.join
+      end
+
+      # Paints the syscall names a finding is about wherever they appear in +text+, in the same color
+      # disasm gives them. Whole words only, so +read+ leaves +process_vm_readv+ alone.
+      # @return [String]
+      def highlight(text, names)
+        Array(names).uniq.reduce(text) do |painted, name|
+          painted.gsub(/\b#{Regexp.escape(name)}\b/) { Util.colorize(name, t: :syscall) }
+        end
+      end
+    end
+  end
+end

data/lib/seccomp-tools/audit.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/checks'
+require 'seccomp-tools/audit/policy'
+require 'seccomp-tools/audit/report'
+require 'seccomp-tools/explain/analysis'
+require 'seccomp-tools/symbolic/executor'
+
+module SeccompTools
+  # Assesses a seccomp filter for weaknesses / escape routes and reports them as a {Audit::Report}.
+  #
+  # It runs the generic {Symbolic::Executor} over the filter (the same walk {Explain} uses), splits
+  # the leaves per architecture with {Explain::Analysis}, and runs each {Checks} rule against the
+  # per-arch {Policy}. Every supported architecture is assessed; architecture-specific quirks (e.g.
+  # amd64's x32 ABI) are registered per arch in {Checks}, never special-cased inline.
+  #
+  # @example
+  #   insts = SeccompTools::Disasm.to_bpf(raw, :amd64).map(&:inst)
+  #   puts SeccompTools::Audit.new(insts, arch: :amd64, source: 'a.out').audit
+  class Audit
+    # @param [Array<Instruction::Base>] instructions
+    #   The filter, as +SeccompTools::Disasm.to_bpf(raw, arch).map(&:inst)+.
+    # @param [Symbol] arch
+    #   The architecture the filter is written for, used when it does not itself branch on +arch+.
+    # @param [String?] source
+    #   A label for the filter (e.g. a filename) shown in the report.
+    def initialize(instructions, arch:, source: nil)
+      @instructions = instructions
+      @arch = arch
+      @source = source
+    end
+
+    # Walks the filter, runs every check, and returns the {Report}.
+    # @return [Report]
+    def audit
+      leaves, truncated = Symbolic::Executor.new(@instructions).run
+      analysis = Explain::Analysis.new(leaves)
+      policies = analysis.sections(@arch).map { |section| Policy.new(analysis, section) }
+
+      findings = Checks::FILTER.flat_map { |check| check.call(analysis) }
+      policies.each do |policy|
+        Checks.section_checks(policy.arch_sym).each { |check| findings.concat(check.call(policy)) }
+      end
+
+      Report.new(source: @source, arches: policies.map(&:arch_name), findings:, truncated:)
+    end
+  end
+end

data/lib/seccomp-tools/bpf.rb

@@ -7,7 +7,10 @@ require 'seccomp-tools/const'
 require 'seccomp-tools/instruction/instruction'
 
 module SeccompTools
-  # Define the +struct sock_filter+, while more powerful.
+  # One BPF instruction, i.e. a +struct sock_filter+.
+  #
+  # Beyond the four fields of the C struct, a {BPF} also carries the architecture it belongs to and
+  # its line number, which together allow it to be disassembled into readable assembly.
   class BPF
     # @return [Integer] Line number.
     attr_reader :line
@@ -21,12 +24,13 @@ module SeccompTools
     attr_reader :k
     # @return [Symbol] Architecture.
     attr_reader :arch
-    # @return [Set<Context>] Possible contexts before this instruction.
-    attr_accessor :contexts
+    # @return [Set<SeccompTools::Symbolic::State>] Possible states before this instruction.
+    attr_accessor :states
 
     # Instantiate a {BPF} object.
-    # @param [String] raw
-    #   One +struct sock_filter+ in bytes, should be 8 bytes long.
+    # @param [String, {Symbol => Integer}] raw
+    #   One +struct sock_filter+, either as 8 raw bytes or as a hash of the +:code+, +:jt+, +:jf+
+    #   and +:k+ fields.
     # @param [Symbol] arch
     #   Architecture, for showing constant names in decompile.
     # @param [Integer] line
@@ -47,7 +51,7 @@ module SeccompTools
       end
       @arch = arch
       @line = line
-      @contexts = Set.new
+      @states = Set.new
       @disasm_setting = {
         code: true,
         arg_infer: true
@@ -56,8 +60,11 @@ module SeccompTools
 
     # Pretty display the disassemble result.
     # @param [{Symbol => Boolean}] options
-    #   Set display settings.
+    #   Display settings, merged into the current ones. Supports +:code+, whether to show the raw
+    #   +code+, +jt+, +jf+ and +k+ fields, and +:arg_infer+, whether to annotate the line with the
+    #   inferred syscall argument.
     # @return [String]
+    #   One line of disassembly, without a trailing newline.
     def disasm(**options)
       @disasm_setting.merge!(options)
       if show_code?
@@ -69,12 +76,14 @@ module SeccompTools
       end
     end
 
-    # Whether needs to dump code, jt, jf, k.
+    # Whether the raw +code+, +jt+, +jf+, +k+ fields need to be dumped.
+    # @return [Boolean]
     def show_code?
       @disasm_setting[:code]
     end
 
-    # Whether needs to infer the syscall argument names.
+    # Whether the syscall argument names need to be inferred.
+    # @return [Boolean]
     def show_arg_infer?
       @disasm_setting[:arg_infer]
     end
@@ -88,8 +97,8 @@ module SeccompTools
     end
 
     # Command according to +code+.
-    # @return [Symbol]
-    #   See {Const::BPF::COMMAND} for list of commands.
+    # @return [Symbol?]
+    #   See {Const::BPF::COMMAND} for the list of commands, +nil+ if +code+ is invalid.
     def command
       Const::BPF::COMMAND.invert[code & 7]
     end
@@ -101,15 +110,16 @@ module SeccompTools
       inst.decompile
     end
 
-    # @param [Context] context
-    #   Current context.
+    # Yields every branch that may be taken after executing this instruction.
+    # @param [SeccompTools::Symbolic::State] state
+    #   Current state.
     # @yieldparam [Integer] pc
     #   Program counter after this instruction.
-    # @yieldparam [Context] ctx
-    #   Context after this instruction.
+    # @yieldparam [SeccompTools::Symbolic::State] st
+    #   State after this instruction.
     # @return [void]
-    def branch(context, &block)
-      inst.branch(context).each(&block)
+    def branch(state, &)
+      inst.branch(state).each(&)
     end
 
     # Corresponding instruction object.

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

@@ -10,8 +10,11 @@ module SeccompTools
       # Summary of this command.
       SUMMARY = 'Seccomp bpf assembler.'
       # Usage of this command.
-      USAGE = "asm - #{SUMMARY}\n\nUsage: seccomp-tools asm IN_FILE [options]"
+      USAGE = "asm - #{SUMMARY}\n\nUsage: seccomp-tools asm IN_FILE [options]".freeze
 
+      # Instantiate an {Asm} object, defaulting the output format to +:inspect+.
+      #
+      # Takes the same arguments as {Base#initialize}.
       def initialize(*)
         super
         option[:format] = :inspect
@@ -19,10 +22,11 @@ module SeccompTools
 
       # Define option parser.
       # @return [OptionParser]
+      #   The parser of this command's options.
       def parser
         @parser ||= OptionParser.new do |opt|
           opt.banner = usage
-          opt.on('-o', '--output FILE', 'Output result into FILE instead of stdout.') do |o|
+          opt.on('-o', '--output FILE', 'Write output to FILE instead of stdout.') do |o|
             option[:ofile] = o
           end
 
@@ -36,7 +40,7 @@ module SeccompTools
         end
       end
 
-      # Handle options.
+      # Assembles the input file and writes the result in the requested format.
       # @return [void]
       def handle
         return unless super

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require 'seccomp-tools/audit'
+require 'seccomp-tools/cli/base'
+require 'seccomp-tools/cli/filter_input'
+require 'seccomp-tools/disasm/disasm'
+require 'seccomp-tools/logger'
+
+module SeccompTools
+  module CLI
+    # Handle 'audit' command.
+    class Audit < Base
+      include FilterInput
+
+      # Summary of this command.
+      SUMMARY = 'Assess a seccomp filter for weaknesses and escape routes.'
+      # Usage of this command.
+      USAGE = "audit - #{SUMMARY}\n\nUsage: seccomp-tools audit [options] [BPF_FILE|EXEC]".freeze
+
+      # Instantiate an {Audit} object.
+      #
+      # Takes the same arguments as {Base#initialize}.
+      def initialize(*)
+        super
+        option[:format] = :human
+      end
+
+      # 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, 'audit')
+          option_arch(opt, 'With an executable or --pid the architecture is auto-detected instead.')
+
+          opt.on('-f', '--format FORMAT', %i[human json], 'Output format, one of <human|json>.',
+                 'Default: human') do |f|
+            option[:format] = f
+          end
+        end
+      end
+
+      # Reads the filter(s) from a BPF file, an executable, or an existing process, then reports the
+      # weaknesses of each.
+      # @return [void]
+      def handle
+        return unless super
+
+        filters = collect_filters
+        return if filters.empty?
+
+        option[:format] == :json ? emit_json(filters) : emit_human(filters)
+      end
+
+      private
+
+      # Prints each filter's report, warning first when several filters stack.
+      def emit_human(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 audited separately below.')
+        end
+        each_report(filters) { |report| output { report.to_s } }
+      end
+
+      # Prints one JSON document describing every stacked filter.
+      def emit_json(filters)
+        reports = []
+        each_report(filters) { |report| reports << report.to_h }
+        output { "#{JSON.pretty_generate(stacked_filters: filters.size, reports:)}\n" }
+      end
+
+      # Yields the {Audit::Report} of each filter, labelling stacked filters like +explain+ does.
+      def each_report(filters)
+        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)
+          yield SeccompTools::Audit.new(insts, arch:, source: label).audit
+        end
+      end
+    end
+  end
+end

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

@@ -2,13 +2,19 @@
 
 require 'optparse'
 
+require 'seccomp-tools/logger'
 require 'seccomp-tools/util'
 
 module SeccompTools
   module CLI
     # Base class for handlers.
+    #
+    # Each subcommand is a subclass that defines a +USAGE+ constant and a +parser+, and overrides
+    # {#handle} to do its work.
     class Base
-      # @return [{Symbol => Object}] Options.
+      # @return [{Symbol => Object}]
+      #   Options parsed from the command line. Common keys are +:arch+, +:ifile+, +:ofile+,
+      #   +:format+, +:limit+, +:pid+ and +:verbose+, depending on the subcommand.
       attr_reader :option
       # @return [Array<String>] Arguments array.
       attr_reader :argv
@@ -23,14 +29,29 @@ module SeccompTools
 
       private
 
-      # Handle show help message.
+      # Parses the common options, and shows the help message when asked to.
       # @return [Boolean]
-      #   For decestors to check whether need to continue.
+      #   For descendants to check whether they need to continue. +false+ when the help message
+      #   was shown and there is nothing left to do.
       def handle
-        return CLI.show(parser.help) if argv.empty? || %w[-h --help].any? { |h| argv.include?(h) }
+        return CLI.show(parser.help) if argv.empty? || %w[-h --help].intersect?(argv)
 
         parser.parse!(argv)
-        option[:arch] ||= Util.system_arch
+
+        # Fill in the architecture from the host when --arch was not given. A command that offers
+        # --arch needs a concrete architecture to name syscalls; if the host CPU is one seccomp-tools
+        # does not recognize, auto-detection cannot supply one, so fail with a clear message instead
+        # of letting :unknown reach a syscall-table lookup and raise deep down.
+        return true unless option[:arch].nil?
+
+        arch = Util.system_arch
+        if arch == :unknown && @arch_option_offered
+          Logger.error('Could not detect the host architecture; specify one with ' \
+                       "--arch <#{Util.supported_archs.join('|')}>.")
+          return false
+        end
+
+        option[:arch] = arch
         true
       end
 
@@ -43,6 +64,9 @@ module SeccompTools
       end
 
       # Write data to stdout or file(s).
+      #
+      # When +option[:ofile]+ is set, each call writes to a new file named after it with an
+      # incrementing serial number, see {#file_of}. Colors are disabled while writing to a file.
       # @yieldreturn [String]
       #   The data to be written.
       # @return [void]
@@ -65,7 +89,7 @@ module SeccompTools
       # @param [String] file
       #   Filename.
       # @param [Integer] serial
-      #   serial number, starts from zero.
+      #   Serial number, starts from zero.
       # @return [String]
       #   Result filename.
       # @example
@@ -89,11 +113,30 @@ module SeccompTools
         self.class.const_get(:USAGE)
       end
 
-      def option_arch(opt)
+      # Warns about positional arguments left over in {#argv} after the command has taken what it
+      # needs, e.g. an exec given together with +-c+, or anything after +--pid+. The command still
+      # proceeds.
+      # @return [void]
+      def warn_ignored_arguments
+        return if argv.empty?
+
+        Logger.warn("ignoring unused argument#{'s' if argv.size > 1}: #{argv.join(' ')}")
+      end
+
+      # Registers the common +--arch+ option on +opt+.
+      #
+      # @param [OptionParser] opt
+      #   The parser to add the option to.
+      # @param [Array<String>] extra_desc
+      #   Extra description lines appended after the default ones, for command-specific guidance.
+      # @return [void]
+      def option_arch(opt, *extra_desc)
+        @arch_option_offered = true
         supported = Util.supported_archs
         opt.on('-a', '--arch ARCH', supported, 'Specify architecture.',
                "Supported architectures are <#{supported.join('|')}>.",
-               "Default: #{Util.system_arch}") do |a|
+               'Default: auto-detected from the host machine.',
+               'Set it when the filter targets an architecture other than the host.', *extra_desc) do |a|
           option[:arch] = a
         end
       end