seccomp-tools 1.6.2 → 1.7.0

data/completions/seccomp-tools.bash

@@ -0,0 +1,59 @@
+# bash completion for seccomp-tools
+#
+# Load it with either:
+#   eval "$(seccomp-tools completion bash)"    # in ~/.bashrc
+# or drop this file into a bash-completion directory named `seccomp-tools`, e.g.
+#   ~/.local/share/bash-completion/completions/seccomp-tools
+
+_seccomp_tools() {
+  local cur prev cmd
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+  local commands="asm audit completion disasm dump emu explain"
+  local arches="aarch64 amd64 i386 riscv64 s390x"
+
+  # Position 1: the subcommand.
+  if [[ $COMP_CWORD -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "$commands --help --version" -- "$cur") )
+    return
+  fi
+
+  cmd="${COMP_WORDS[1]}"
+
+  # The previous word expects a value: complete just that value.
+  case "$prev" in
+    -a|--arch) COMPREPLY=( $(compgen -W "$arches" -- "$cur") ); return ;;
+    -o|--output) COMPREPLY=( $(compgen -f -- "$cur") ); return ;;
+    -f|--format)
+      case "$cmd" in
+        asm)   COMPREPLY=( $(compgen -W "inspect raw c_array c_source assembly" -- "$cur") ) ;;
+        audit) COMPREPLY=( $(compgen -W "human json" -- "$cur") ) ;;
+        dump)  COMPREPLY=( $(compgen -W "disasm raw inspect" -- "$cur") ) ;;
+      esac
+      return ;;
+  esac
+
+  if [[ $cmd == completion ]]; then
+    COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
+    return
+  fi
+
+  # Otherwise: this subcommand's flags (when typing a -flag) or a file.
+  local opts="-h --help"
+  case "$cmd" in
+    asm)     opts+=" -o --output -f --format -a --arch" ;;
+    disasm)  opts+=" -o --output -a --arch --bpf --no-bpf --arg-infer --no-arg-infer --asm-able" ;;
+    dump)    opts+=" -c --sh-exec -l --limit -p --pid -t --timeout -f --format -o --output" ;;
+    emu)     opts+=" -a --arch -q --no-quiet -i --ip" ;;
+    explain) opts+=" -c --sh-exec -l --limit -p --pid -t --timeout -a --arch" ;;
+    audit)   opts+=" -c --sh-exec -l --limit -p --pid -t --timeout -a --arch -f --format" ;;
+  esac
+
+  if [[ $cur == -* ]]; then
+    COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+  else
+    COMPREPLY=( $(compgen -f -- "$cur") )
+  fi
+}
+complete -F _seccomp_tools seccomp-tools

data/completions/seccomp-tools.fish

@@ -0,0 +1,52 @@
+# fish completion for seccomp-tools
+#
+# Load it with either:
+#   seccomp-tools completion fish | source    # in ~/.config/fish/config.fish
+# or drop this file into ~/.config/fish/completions/seccomp-tools.fish
+
+# Disable file completion by default; re-enabled per option/positional below.
+complete -c seccomp-tools -f
+
+# Subcommands (offered only when none has been given yet).
+complete -c seccomp-tools -n __fish_use_subcommand -a asm        -d 'Seccomp bpf assembler'
+complete -c seccomp-tools -n __fish_use_subcommand -a audit      -d 'Assess a filter for weaknesses and escape routes'
+complete -c seccomp-tools -n __fish_use_subcommand -a completion -d 'Print a shell completion script'
+complete -c seccomp-tools -n __fish_use_subcommand -a disasm     -d 'Disassemble seccomp bpf'
+complete -c seccomp-tools -n __fish_use_subcommand -a dump       -d 'Automatically dump seccomp bpf from executable(s)'
+complete -c seccomp-tools -n __fish_use_subcommand -a emu        -d 'Emulate seccomp rules'
+complete -c seccomp-tools -n __fish_use_subcommand -a explain    -d 'Summarize a filter as a per-action policy'
+complete -c seccomp-tools -n __fish_use_subcommand -l version    -d 'Show version'
+complete -c seccomp-tools -s h -l help -d 'Show help'
+
+# --arch, shared by the analysis commands.
+complete -c seccomp-tools -n '__fish_seen_subcommand_from asm disasm emu explain audit' \
+  -s a -l arch -x -a 'aarch64 amd64 i386 riscv64 s390x' -d Architecture
+
+# --format, whose valid values differ per command.
+complete -c seccomp-tools -n '__fish_seen_subcommand_from asm'   -s f -l format -x -a 'inspect raw c_array c_source assembly' -d 'Output format'
+complete -c seccomp-tools -n '__fish_seen_subcommand_from dump'  -s f -l format -x -a 'disasm raw inspect' -d 'Output format'
+complete -c seccomp-tools -n '__fish_seen_subcommand_from audit' -s f -l format -x -a 'human json' -d 'Output format'
+
+# --output takes a file.
+complete -c seccomp-tools -n '__fish_seen_subcommand_from asm disasm dump' -s o -l output -r -d 'Write output to FILE'
+
+# Options shared by the commands that read from a process.
+complete -c seccomp-tools -n '__fish_seen_subcommand_from dump explain audit' -s c -l sh-exec -x -d 'Run command via sh and analyze its seccomp'
+complete -c seccomp-tools -n '__fish_seen_subcommand_from dump explain audit' -s p -l pid     -x -d 'Analyze a running process'
+complete -c seccomp-tools -n '__fish_seen_subcommand_from dump explain audit' -s l -l limit   -x -d 'Analyze only the first N filters'
+complete -c seccomp-tools -n '__fish_seen_subcommand_from dump explain audit' -s t -l timeout -x -d 'Timeout in seconds'
+
+# disasm-only flags.
+complete -c seccomp-tools -n '__fish_seen_subcommand_from disasm' -l asm-able     -d 'Emit output that is valid input for asm'
+complete -c seccomp-tools -n '__fish_seen_subcommand_from disasm' -l no-bpf       -d 'Hide the raw BPF bytes'
+complete -c seccomp-tools -n '__fish_seen_subcommand_from disasm' -l no-arg-infer -d 'Do not infer argument names'
+
+# emu-only flags.
+complete -c seccomp-tools -n '__fish_seen_subcommand_from emu' -s i -l ip    -x -d 'Set the instruction pointer'
+complete -c seccomp-tools -n '__fish_seen_subcommand_from emu' -s q -l quiet -d 'Only show the emulation result'
+
+# completion takes a shell name.
+complete -c seccomp-tools -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish' -d Shell
+
+# The commands whose positional argument is a file/executable get file completion.
+complete -c seccomp-tools -n '__fish_seen_subcommand_from asm disasm dump emu explain audit' -F

data/ext/ptrace/ptrace.c

@@ -48,9 +48,9 @@ ptrace_peekuser(VALUE _mod, VALUE pid, VALUE off, VALUE _data, VALUE bits) {
     uint32_t val32;
     uint64_t val64;
   } val;
-  // Dynamically allocate a buffer to store registers-well, at least enough
+  // Dynamically allocate a buffer to store registers - well, at least enough
   // registers to reach the offset we want. Normally we'd want to use
-  // user_pt_regs or similar, but it's difficult to find it available in the
+  // user_pt_regs or similar, but it's difficult to find it available in
   // the same header across different versions of Linux or libcs, or even with
   // the same *name*, so this is the compromise.
   size_t size = offset + width;

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

@@ -8,19 +8,24 @@ module SeccompTools
   module Asm
     module_function
 
-    # Assembler of seccomp bpf.
+    # Compiles seccomp assembly into raw BPF bytes.
     # @param [String] str
+    #   The assembly source to be compiled.
     # @param [String] filename
     #   Only used for error messages.
     # @param [Symbol?] arch
+    #   Target architecture, must be one of {SeccompTools::Util.supported_archs}.
+    #   Defaults to {SeccompTools::Util.system_arch} when +nil+.
     # @return [String]
     #   Raw BPF bytes.
+    # @raise [SeccompTools::Error]
+    #   If +str+ is not valid seccomp assembly.
     # @example
     #   SeccompTools::Asm.asm(<<-EOS)
-    #     # lines start with '#' are comments
+    #     # lines starting with '#' are comments
     #     A = sys_number                # here's a comment, too
-    #     A >= 0x40000000 ? dead : next # 'next' is a keyword, denote the next instruction
-    #     A == read ? ok : next         # custom defined label 'dead' and 'ok'
+    #     A >= 0x40000000 ? dead : next # 'next' is a keyword, denoting the next instruction
+    #     A == read ? ok : next         # custom-defined labels 'dead' and 'ok'
     #     A == 1 ? ok : next            # SYS_write = 1 on amd64
     #     return ERRNO(1)
     #     dead:

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

@@ -31,10 +31,21 @@ module SeccompTools
 
       # Compiles the processed instructions.
       #
+      # Scans and parses the source, resolves the labels into relative jump distances, then emits
+      # one {BPF} per statement.
+      #
       # @return [Array<SeccompTools::BPF>]
       #   Returns the compiled {BPF} array.
-      # @raise [SeccompTools::Error]
-      #   Raises the error found during compilation.
+      # @raise [SeccompTools::UnrecognizedTokenError]
+      #   If the source contains text that is not valid assembly.
+      # @raise [SeccompTools::ParseError]
+      #   If the tokens do not form valid statements.
+      # @raise [SeccompTools::DuplicateLabelError]
+      #   If a label is defined more than once.
+      # @raise [SeccompTools::UndefinedLabelError]
+      #   If a jump refers to a label that is never defined.
+      # @raise [SeccompTools::BackwardJumpError]
+      #   If a jump goes backward, which BPF cannot express.
       def compile!
         @scanner.validate!
         statements = SeccompAsmParser.new(@scanner).parse
@@ -79,8 +90,18 @@ module SeccompTools
         end
       end
 
+      # Resolves a jump target into a relative distance from +index+.
+      #
       # @param [Integer] index
+      #   Index of the statement the jump is written in.
       # @param [SeccompTools::Asm::Token, :next] sym
+      #   The jump target, either a label token or +:next+ for the following instruction.
+      # @return [Integer]
+      #   Number of instructions to skip, +0+ meaning the next instruction.
+      # @raise [SeccompTools::UndefinedLabelError]
+      #   If +sym+ names a label that is never defined.
+      # @raise [SeccompTools::BackwardJumpError]
+      #   If the target lies before +index+.
       def resolve_symbol(index, sym)
         return 0 if sym.is_a?(Symbol) && sym == :next
 
@@ -105,6 +126,15 @@ module SeccompTools
 
       # Emits a raw BPF object.
       #
+      # @param [Array<Symbol>] args
+      #   Names of the flags to be OR-ed together into the instruction's +code+ field, looked up in
+      #   the {Const::BPF} tables. Unknown names contribute nothing.
+      # @param [Integer] k
+      #   The +k+ field, an immediate operand or a jump target.
+      # @param [Integer] jt
+      #   The +jt+ field, instructions to skip when a comparison is true.
+      # @param [Integer] jf
+      #   The +jf+ field, instructions to skip when a comparison is false.
       # @return [BPF]
       #   Returns the emitted {BPF} object.
       def emit(*args, k: 0, jt: 0, jf: 0)

data/lib/seccomp-tools/asm/sasm.tab.rb

@@ -9,17 +9,24 @@ require 'racc/parser.rb'
 require 'seccomp-tools/asm/scalar'
 require 'seccomp-tools/asm/scanner'
 require 'seccomp-tools/asm/statement'
+require 'seccomp-tools/const'
 
 module SeccompTools
   module Asm
     class SeccompAsmParser < Racc::Parser
 
-module_eval(<<'...end sasm.y/module_eval...', 'sasm.y', 136)
+module_eval(<<'...end sasm.y/module_eval...', 'sasm.y', 138)
   def initialize(scanner)
     @scanner = scanner
     super()
   end
 
+  # The byte offset of the low (+hi: false+) or high 32-bit word of the 8-byte seccomp_data field
+  # at +base+; on a big-endian target the high word comes first.
+  def word_offset(base, hi:)
+    base + (hi == SeccompTools::Const::Endian.big?(@scanner.arch) ? 0 : 4)
+  end
+
   # @return [Array<Statement>]
   def parse
     @tokens = @scanner.scan.dup
@@ -632,47 +639,48 @@ module_eval(<<'.,.,', 'sasm.y', 70)
                 off = val[1] == '>>' ? 0 : -1
                 raise_error("operator after an argument can only be '>> 32'", off)
               end
-              val[0] + 4
+              val[0] ^ 4 # the other 32-bit word of the same 64-bit field
 
   end
 .,.,
 
 module_eval(<<'.,.,', 'sasm.y', 76)
   def _reduce_46(val, _values)
-     0
+     SeccompTools::Const::BPF::SeccompData::SYS_NUMBER
   end
 .,.,
 
 module_eval(<<'.,.,', 'sasm.y', 77)
   def _reduce_47(val, _values)
-     4
+     SeccompTools::Const::BPF::SeccompData::ARCH
   end
 .,.,
 
 module_eval(<<'.,.,', 'sasm.y', 79)
   def _reduce_48(val, _values)
                   idx = val[2].to_i
-              if idx % 4 != 0 || idx >= 64
-                raise_error(format('index of data[] must be a multiple of 4 and less than 64, got %d', idx), -1)
+              size = SeccompTools::Const::BPF::SeccompData::SIZE
+              if idx % 4 != 0 || idx >= size
+                raise_error(format('index of data[] must be a multiple of 4 and less than %d, got %d', size, idx), -1)
               end
               idx
 
   end
 .,.,
 
-module_eval(<<'.,.,', 'sasm.y', 87)
+module_eval(<<'.,.,', 'sasm.y', 88)
   def _reduce_49(val, _values)
                        idx = val[2].to_i
                    s = val[0]
                    raise_error(format('index of %s[] must between 0 and 5, got %d', s, idx), -1) unless idx.between?(0, 5)
-                   16 + idx * 8 + (s.downcase.end_with?('h') ? 4 : 0)
+                   word_offset(SeccompTools::Const::BPF::SeccompData::ARGS + idx * 8, hi: s.downcase.end_with?('h'))
 
   end
 .,.,
 
-module_eval(<<'.,.,', 'sasm.y', 92)
+module_eval(<<'.,.,', 'sasm.y', 93)
   def _reduce_50(val, _values)
-     8
+     word_offset(SeccompTools::Const::BPF::SeccompData::INSTRUCTION_POINTER, hi: false)
   end
 .,.,
 
@@ -680,7 +688,7 @@ module_eval(<<'.,.,', 'sasm.y', 92)
 
 # reduce 52 omitted
 
-module_eval(<<'.,.,', 'sasm.y', 95)
+module_eval(<<'.,.,', 'sasm.y', 96)
   def _reduce_53(val, _values)
      val[0] + val[1]
   end
@@ -690,13 +698,13 @@ module_eval(<<'.,.,', 'sasm.y', 95)
 
 # reduce 55 omitted
 
-module_eval(<<'.,.,', 'sasm.y', 98)
+module_eval(<<'.,.,', 'sasm.y', 99)
   def _reduce_56(val, _values)
      Scalar::ConstVal.new(val[0] & 0xffffffff)
   end
 .,.,
 
-module_eval(<<'.,.,', 'sasm.y', 99)
+module_eval(<<'.,.,', 'sasm.y', 100)
   def _reduce_57(val, _values)
      val[1]
   end
@@ -706,37 +714,37 @@ module_eval(<<'.,.,', 'sasm.y', 99)
 
 # reduce 59 omitted
 
-module_eval(<<'.,.,', 'sasm.y', 102)
+module_eval(<<'.,.,', 'sasm.y', 103)
   def _reduce_60(val, _values)
      Scalar::A.instance
   end
 .,.,
 
-module_eval(<<'.,.,', 'sasm.y', 103)
+module_eval(<<'.,.,', 'sasm.y', 104)
   def _reduce_61(val, _values)
      Scalar::X.instance
   end
 .,.,
 
-module_eval(<<'.,.,', 'sasm.y', 104)
+module_eval(<<'.,.,', 'sasm.y', 105)
   def _reduce_62(val, _values)
      val[0].to_i
   end
 .,.,
 
-module_eval(<<'.,.,', 'sasm.y', 105)
+module_eval(<<'.,.,', 'sasm.y', 106)
   def _reduce_63(val, _values)
      val[0].to_i(16)
   end
 .,.,
 
-module_eval(<<'.,.,', 'sasm.y', 106)
+module_eval(<<'.,.,', 'sasm.y', 107)
   def _reduce_64(val, _values)
      Const::Audit::ARCH[val[0]]
   end
 .,.,
 
-module_eval(<<'.,.,', 'sasm.y', 108)
+module_eval(<<'.,.,', 'sasm.y', 109)
   def _reduce_65(val, _values)
                 s = val[0]
             return @scanner.syscalls[s.to_sym] unless s.include?('.')

data/lib/seccomp-tools/asm/sasm.y

@@ -72,14 +72,15 @@ rule
                 off = val[1] == '>>' ? 0 : -1
                 raise_error("operator after an argument can only be '>> 32'", off)
               end
-              val[0] + 4
+              val[0] ^ 4 # the other 32-bit word of the same 64-bit field
             }
-          | SYS_NUMBER { 0 }
-          | ARCH { 4 }
+          | SYS_NUMBER { SeccompTools::Const::BPF::SeccompData::SYS_NUMBER }
+          | ARCH { SeccompTools::Const::BPF::SeccompData::ARCH }
           | DATA LBRACK constexpr RBRACK {
               idx = val[2].to_i
-              if idx % 4 != 0 || idx >= 64
-                raise_error(format('index of data[] must be a multiple of 4 and less than 64, got %d', idx), -1)
+              size = SeccompTools::Const::BPF::SeccompData::SIZE
+              if idx % 4 != 0 || idx >= size
+                raise_error(format('index of data[] must be a multiple of 4 and less than %d, got %d', size, idx), -1)
               end
               idx
             }
@@ -88,9 +89,9 @@ rule
                    idx = val[2].to_i
                    s = val[0]
                    raise_error(format('index of %s[] must between 0 and 5, got %d', s, idx), -1) unless idx.between?(0, 5)
-                   16 + idx * 8 + (s.downcase.end_with?('h') ? 4 : 0)
+                   word_offset(SeccompTools::Const::BPF::SeccompData::ARGS + idx * 8, hi: s.downcase.end_with?('h'))
                  }
-               | INSTRUCTION_POINTER { 8 }
+               | INSTRUCTION_POINTER { word_offset(SeccompTools::Const::BPF::SeccompData::INSTRUCTION_POINTER, hi: false) }
   args: ARGS
       | ARGS_H
   alu_op_eq: alu_op ASSIGN { val[0] + val[1] }
@@ -131,6 +132,7 @@ end
 require 'seccomp-tools/asm/scalar'
 require 'seccomp-tools/asm/scanner'
 require 'seccomp-tools/asm/statement'
+require 'seccomp-tools/const'
 
 ---- inner
   def initialize(scanner)
@@ -138,6 +140,12 @@ require 'seccomp-tools/asm/statement'
     super()
   end
 
+  # The byte offset of the low (+hi: false+) or high 32-bit word of the 8-byte seccomp_data field
+  # at +base+; on a big-endian target the high word comes first.
+  def word_offset(base, hi:)
+    base + (hi == SeccompTools::Const::Endian.big?(@scanner.arch) ? 0 : 4)
+  end
+
   # @return [Array<Statement>]
   def parse
     @tokens = @scanner.scan.dup

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

@@ -10,116 +10,159 @@ module SeccompTools
     # @private
     module Scalar
       # To be used to denote a register (A / X), an argument (data[]), or a memory data (mem[]).
+      #
+      # Every predicate returns +false+ here, each subclass overrides exactly the one that
+      # identifies it. The registers and +len+ carry no payload and are singletons, the remaining
+      # subclasses keep theirs in {#val}.
       class Base
+        # @return [Integer?]
+        #   The payload of this scalar, whose meaning depends on the subclass: the immediate value
+        #   for {ConstVal}, the index for {Data} and {Mem}. +nil+ for the singletons.
         attr_reader :val
 
+        # Is this the A register?
+        # @return [Boolean]
         def a?
           false
         end
 
+        # Is this the X register?
+        # @return [Boolean]
         def x?
           false
         end
 
+        # Is this +len+?
+        # @return [Boolean]
         def len?
           false
         end
 
+        # Is this a +data[]+ access?
+        # @return [Boolean]
         def data?
           false
         end
 
+        # Is this a +mem[]+ access?
+        # @return [Boolean]
         def mem?
           false
         end
 
+        # Is this a constant value?
+        # @return [Boolean]
         def const?
           false
         end
       end
 
-      # Register A.
+      # Register A, the accumulator. A singleton, use +A.instance+.
       class A < Base
         include Singleton
 
+        # @return [Boolean] Always +true+.
         def a?
           true
         end
       end
 
-      # Register X.
+      # Register X, the index register. A singleton, use +X.instance+.
       class X < Base
         include Singleton
 
+        # @return [Boolean] Always +true+.
         def x?
           true
         end
       end
 
-      # Len.
+      # The +len+ keyword, the size of +struct seccomp_data+. A singleton, use +Len.instance+.
       class Len < Base
         include Singleton
 
+        # @return [Boolean] Always +true+.
         def len?
           true
         end
       end
 
-      # A constant value.
+      # A constant value, i.e. an immediate operand.
       class ConstVal < Base
+        # Instantiates a {ConstVal} object.
+        #
         # @param [Integer] val
+        #   The constant value.
         def initialize(val)
           @val = val
           super()
         end
 
+        # Compares by value, so a {ConstVal} equals the bare Integer it wraps.
+        #
         # @param [ConstVal, Integer] other
+        #   The object to be compared with.
+        # @return [Boolean]
         def ==(other)
           to_i == other.to_i
         end
 
+        # @return [Boolean] Always +true+.
         def const?
           true
         end
 
+        # @!method to_i
+        #   The wrapped constant value.
+        #   @return [Integer]
         alias to_i val
       end
 
-      # data[]
+      # A +data[]+ access, one word of +struct seccomp_data+.
       class Data < Base
         # Instantiates a {Data} object.
         #
         # @param [Integer] index
+        #   Byte offset into +struct seccomp_data+.
         def initialize(index)
           @val = index
           super()
         end
 
         # @param [Data] other
+        #   The object to be compared with.
+        # @return [Boolean]
+        #   +true+ only if +other+ is a {Data} with the same index.
         def ==(other)
           other.is_a?(Data) && val == other.val
         end
 
+        # @return [Boolean] Always +true+.
         def data?
           true
         end
       end
 
-      # mem[]
+      # A +mem[]+ access, one slot of the scratch memory.
       class Mem < Base
         # Instantiates a {Mem} object.
         #
         # @param [Integer] index
+        #   Index of the scratch memory slot.
         def initialize(index)
           @val = index
           super()
         end
 
-        # @param [Data] other
+        # @param [Mem] other
+        #   The object to be compared with.
+        # @return [Boolean]
+        #   +true+ only if +other+ is a {Mem} with the same index.
         def ==(other)
           other.is_a?(Mem) && val == other.val
         end
 
+        # @return [Boolean] Always +true+.
         def mem?
           true
         end

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

@@ -11,9 +11,14 @@ module SeccompTools
     #
     # Maintains columns and rows to have informative error messages.
     #
-    # Internally used by {SeccompAsmParser}.
+    # Internally used by the seccomp asm parser.
     class Scanner
+      # @return [{Symbol => Integer}]
+      #   Syscall name to number, for the architecture this scanner was created with.
       attr_reader :syscalls
+      # @return [Symbol]
+      #   The architecture this scanner was created with.
+      attr_reader :arch
 
       # Keywords with special meanings in our assembly. Keywords are all case-insensitive.
       KEYWORDS = %w[a x if else return mem args args_h data len sys_number arch instruction_pointer].freeze
@@ -40,14 +45,20 @@ module SeccompTools
       # Supported architectures
       ARCHES = SeccompTools::Syscall::ABI.keys.map(&:to_s)
 
+      # Instantiates a {Scanner} object.
+      #
       # @param [String] str
+      #   The assembly source to be scanned.
       # @param [Symbol] arch
+      #   Target architecture, decides which syscall names are recognized.
       # @param [String?] filename
+      #   Only used for error messages, defaults to +<inline>+.
       # @example
       #   Scanner.new('return ALLOW', :amd64)
       def initialize(str, arch, filename: nil)
         @filename = filename || '<inline>'
         @str = str
+        @arch = arch
         @syscalls =
           begin; Const::Syscall.const_get(arch.to_s.upcase); rescue NameError; []; end
         @syscall_all = ARCHES.each_with_object({}) do |ar, memo|
@@ -57,7 +68,9 @@ module SeccompTools
 
       # Scans the whole string and raises errors when there are unrecognized tokens.
       # @return [self]
+      #   The scanner itself, so calls can be chained.
       # @raise [UnrecognizedTokenError]
+      #   If any token could not be recognized. The message points at every such token.
       def validate!
         errors = validate
         return self if errors.empty?
@@ -68,11 +81,17 @@ module SeccompTools
       # Same as {#validate!} but returns the array of errors instead of raising an exception.
       #
       # @return [Array<Token>]
+      #   The +:unknown+ tokens, empty when the source is valid.
       def validate
         scan.select { |t| t.sym == :unknown }
       end
 
+      # Scans the whole string into tokens.
+      #
+      # The result is memoized, so repeated calls are free.
       # @return [Array<Token>]
+      #   All tokens in source order. Unrecognized text becomes +:unknown+ tokens rather than
+      #   raising, see {#validate!}.
       def scan
         return @tokens if defined?(@tokens)
 
@@ -138,9 +157,22 @@ module SeccompTools
       # Let tab on terminal be 4 spaces wide.
       TAB_WIDTH = 4
 
+      # Formats an error message that points at a token in the source.
+      #
       # @param [Token] tok
+      #   The token the message refers to.
       # @param [String] msg
+      #   The message to be shown next to the source location.
       # @return [String]
+      #   The location and message, the offending source line, and a row of carets underlining
+      #   the token.
+      # @example
+      #   scanner.format_error(tok, 'unknown token "foo"')
+      #   #=> <<-EOS
+      #   #   <inline>:1:1 unknown token "foo"
+      #   #   foo
+      #   #   ^^^
+      #   # EOS
       def format_error(tok, msg)
         @lines = @str.lines unless defined?(@lines)
         line = @lines[tok.line]