seccomp-tools 1.6.2 → 1.7.1

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]

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

@@ -8,15 +8,21 @@ module SeccompTools
     # Internally used by sasm.y.
     # @private
     class Statement
-      attr_reader :type, :data, :symbols
+      # @return [Symbol] Kind of this statement, one of +:alu+, +:assign+, +:if+ and +:ret+.
+      attr_reader :type
+      # @return [Object] The operands of this statement, see {#initialize}.
+      attr_reader :data
+      # @return [Array<Token>] Labels that refer to this statement.
+      attr_reader :symbols
 
       # Instantiates a {Statement} object.
       #
       # @param [:alu, :assign, :if, :ret] type
-      # @param [Integer, Array<Integer, String>] data
-      #   The data for describing this statement. Type of +data+ is variant according to the value of +type+.
-      # @param [Array<String>] symbols
-      #   Symbols that refer to this statement.
+      #   Kind of this statement.
+      # @param [Object] data
+      #   The data for describing this statement. Type of +data+ varies according to the value of +type+.
+      # @param [Array<Token>] symbols
+      #   Label tokens that refer to this statement.
       def initialize(type, data, symbols)
         @type = type
         @data = data
@@ -24,6 +30,9 @@ module SeccompTools
       end
 
       # @param [Statement] other
+      #   The statement to be compared with.
+      # @return [Boolean]
+      #   +true+ only if the type, data and symbols are all equal.
       def ==(other)
         [type, data, symbols] == [other.type, other.data, other.symbols]
       end

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

@@ -3,14 +3,30 @@
 module SeccompTools
   module Asm
     # Records information of a token.
+    #
+    # Beyond the token itself, a {Token} remembers where it was found so that
+    # {Scanner#format_error} can point at it in the source.
     class Token
-      attr_reader :sym, :str, :line, :col
+      # @return [Symbol]
+      #   Type of this token, e.g. +:NEWLINE+, +:SYMBOL+, +:GOTO+, or +:unknown+ for text the
+      #   scanner failed to recognize.
+      attr_reader :sym
+      # @return [String] The matched text.
+      attr_reader :str
+      # @return [Integer] Zero-based line number where this token starts.
+      attr_reader :line
+      # @return [Integer] Zero-based column number where this token starts.
+      attr_reader :col
 
       # Instantiates a {Token} object.
       # @param [Symbol] sym
+      #   Type of this token.
       # @param [String] str
+      #   The matched text.
       # @param [Integer] line
+      #   Zero-based line number where this token starts.
       # @param [Integer] col
+      #   Zero-based column number where this token starts.
       def initialize(sym, str, line, col)
         @sym = sym
         @str = str
@@ -20,7 +36,9 @@ module SeccompTools
 
       # To compare with another {Token} object.
       # @param [Token] other
+      #   The token to be compared with.
       # @return [Boolean]
+      #   +true+ only if all four attributes are equal.
       def ==(other)
         [other.sym, other.str, other.line, other.col] == [sym, str, line, col]
       end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module SeccompTools
+  class Audit
+    # The seccomp-domain knowledge the checks classify against: which syscalls are dangerous, which
+    # are equivalents of each other, and which form a file read/write chain. Entries are by syscall
+    # *name*; each check resolves them against the target architecture's own syscall table (a name a
+    # given arch lacks is simply skipped), and the +*_BY_ARCH+ maps add arch-specific knowledge on a
+    # clean extension point - no arch is hardcoded in the checks themselves.
+    module Catalog
+      # Dangerous-if-reachable syscalls => +{severity:, why:}+. Applied on every architecture. Kept to
+      # a low-noise, high-signal set: syscalls a real sandbox almost never wants. Ubiquitous-but-risky
+      # ones (+mmap+/+mprotect+ RWX, decided by the +prot+ argument) are intentionally out of v1 -
+      # flagging them needs argument-flag analysis, else every normal allowlist trips them.
+      DANGEROUS = {
+        execve: { severity: :high, why: 'arbitrary program execution' },
+        execveat: { severity: :high, why: 'arbitrary program execution' },
+        ptrace: { severity: :high, why: 'inspect/inject into other processes' },
+        process_vm_readv: { severity: :high, why: "read another process's memory" },
+        process_vm_writev: { severity: :high, why: "write another process's memory" },
+        io_uring_setup: {
+          severity: :high, why: 'reads/writes/opens as ring operations, bypassing filters on those syscalls'
+        },
+        socket: { severity: :medium, why: 'network access (exfiltration)' },
+        connect: { severity: :medium, why: 'network access (exfiltration)' }
+      }.freeze
+
+      # Per-arch additions to {DANGEROUS} (e.g. i386 multiplexes the socket API through +socketcall+).
+      DANGEROUS_BY_ARCH = {
+        i386: { socketcall: { severity: :medium, why: 'multiplexed socket API (exfiltration)' } }
+      }.freeze
+
+      # Equivalent-syscall groups: denying one member while another is allowed is a bypass gap.
+      ALT_GROUPS = {
+        exec: %i[execve execveat],
+        open: %i[open openat openat2],
+        read: %i[read readv pread64 preadv preadv2],
+        write: %i[write writev pwrite64 pwritev sendfile],
+        fork: %i[fork vfork clone clone3]
+      }.freeze
+
+      # Per-arch additions to {ALT_GROUPS}.
+      ALT_GROUPS_BY_ARCH = {}.freeze
+
+      # The open/read/write families whose joint availability is a file read/exfil chain.
+      ORW = {
+        open: %i[open openat openat2],
+        read: %i[read readv pread64 preadv preadv2],
+        write: %i[write writev pwrite64 pwritev sendfile]
+      }.freeze
+
+      module_function
+
+      # {DANGEROUS} plus any per-arch additions for +arch_sym+.
+      # @param [Symbol?] arch_sym
+      # @return [Hash{Symbol=>Hash}]
+      def dangerous(arch_sym)
+        DANGEROUS.merge(DANGEROUS_BY_ARCH.fetch(arch_sym, {}))
+      end
+
+      # {ALT_GROUPS} plus any per-arch additions for +arch_sym+.
+      # @param [Symbol?] arch_sym
+      # @return [Hash{Symbol=>Array<Symbol>}]
+      def alt_groups(arch_sym)
+        ALT_GROUPS.merge(ALT_GROUPS_BY_ARCH.fetch(arch_sym, {}))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/finding'
+require 'seccomp-tools/explain/verdict'
+
+module SeccompTools
+  class Audit
+    module Checks
+      # The filter does not validate the architecture, or lets an unlisted one reach +ALLOW+. Syscall
+      # numbers are ABI-relative, so number-only rules are dodged by invoking under another ABI.
+      module ArchUnchecked
+        module_function
+
+        # @param [Explain::Analysis] analysis
+        # @return [Array<Audit::Finding>]
+        def call(analysis)
+          if analysis.arch_values.empty?
+            [finding('Architecture is never validated',
+                     'The filter checks syscall numbers without ever comparing data[4] (arch). ' \
+                     'Numbers mean different syscalls under another AUDIT_ARCH, so the checks can be ' \
+                     'dodged by invoking through a different ABI (e.g. i386 numbering on amd64).')]
+          elsif analysis.other_leaves.any? { |l| Explain::Verdict.label(l.ret) == 'ALLOW' }
+            [finding('Unlisted architectures reach ALLOW',
+                     'Some paths reach ALLOW on an architecture the filter does not explicitly ' \
+                     'check, so a different-ABI call can slip past the syscall-number rules.')]
+          else
+            []
+          end
+        end
+
+        # @!visibility private
+        def finding(title, detail)
+          Finding.new(id: 'arch-unchecked', severity: :high, arch: nil, title:, detail:,
+                      syscalls: [], condition: nil,
+                      remediation: 'Compare data[4] against your AUDIT_ARCH_* and KILL every ' \
+                                   'architecture you do not explicitly handle.')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/catalog'
+require 'seccomp-tools/audit/finding'
+
+module SeccompTools
+  class Audit
+    module Checks
+      # A syscall a sandbox almost never wants ({Catalog#dangerous}) is reachable as +ALLOW+. One
+      # finding per syscall, carrying the argument condition (if any) under which it is allowed.
+      module DangerousAllow
+        module_function
+
+        # @param [Audit::Policy] policy
+        # @return [Array<Audit::Finding>]
+        def call(policy)
+          Catalog.dangerous(policy.arch_sym).filter_map do |name, meta|
+            nr = policy.number(name)
+            next unless nr && policy.reachable_as_allow?(nr)
+
+            cond = policy.condition_for(nr)
+            Finding.new(
+              id: 'dangerous-allow', severity: meta[:severity], arch: policy.arch_name,
+              title: "#{name} is allowed",
+              detail: "#{name} reaches ALLOW - #{meta[:why]}.",
+              syscalls: [name.to_s], condition: cond,
+              remediation: "Block #{name} unless the program genuinely needs it."
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/catalog'
+require 'seccomp-tools/audit/finding'
+
+module SeccompTools
+  class Audit
+    module Checks
+      # An open-family, a read-family and a write/send-family syscall are all reachable as +ALLOW+ -
+      # the classic "open the flag, read it, write it out" chain.
+      module OrwChain
+        module_function
+
+        # @param [Audit::Policy] policy
+        # @return [Array<Audit::Finding>]
+        def call(policy)
+          o = first_allowed(policy, Catalog::ORW[:open])
+          r = first_allowed(policy, Catalog::ORW[:read])
+          w = first_allowed(policy, Catalog::ORW[:write])
+          return [] unless o && r && w
+
+          [Finding.new(
+            id: 'orw-chain', severity: :high, arch: policy.arch_name,
+            title: 'A file can be opened and its contents copied out',
+            # The syscall names are painted wherever they appear, so keep them out of prose that
+            # merely describes the actions - only name one where the syscall itself is meant.
+            detail: "#{o}, #{r} and #{w} all reach ALLOW, so the contents of an arbitrary file " \
+                    '(e.g. the flag) can be copied straight back out.',
+            syscalls: [o, r, w].map(&:to_s), condition: nil,
+            remediation: 'Deny the open-family syscalls unless the program genuinely needs arbitrary files.'
+          )]
+        end
+
+        # @!visibility private
+        def first_allowed(policy, names)
+          names.find { |n| (nr = policy.number(n)) && policy.reachable_as_allow?(nr) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/finding'
+
+module SeccompTools
+  class Audit
+    module Checks
+      # The catch-all action is +ALLOW+: a denylist, bypassable by anything the author forgot.
+      module PermissiveDefault
+        module_function
+
+        # @param [Audit::Policy] policy
+        # @return [Array<Audit::Finding>]
+        def call(policy)
+          return [] unless policy.default_label == 'ALLOW'
+
+          [Finding.new(
+            id: 'permissive-default', severity: :high, arch: policy.arch_name,
+            title: 'Default action is ALLOW (denylist)',
+            detail: 'Any syscall the filter does not explicitly block is allowed; a denylist is ' \
+                    'bypassable by any syscall the author overlooked.',
+            syscalls: [], condition: nil,
+            remediation: 'Use an allowlist: default to KILL/ERRNO and permit only the needed syscalls.'
+          )]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/catalog'
+require 'seccomp-tools/audit/finding'
+
+module SeccompTools
+  class Audit
+    module Checks
+      # An equivalent-syscall gap: a group member is singled out for denial while a sibling with the
+      # same capability still reaches +ALLOW+ (blocked +execve+ but not +execveat+, +open+ but not
+      # +openat+, +fork+ but not +clone+).
+      module SyscallAltGap
+        module_function
+
+        # @param [Audit::Policy] policy
+        # @return [Array<Audit::Finding>]
+        def call(policy)
+          Catalog.alt_groups(policy.arch_sym).filter_map do |group, names|
+            present = names.filter_map { |n| [n, policy.number(n)] if policy.number(n) }
+            denied = present.select { |_n, nr| policy.explicitly_denied?(nr) }.map(&:first)
+            allowed = present.select { |_n, nr| policy.reachable_as_allow?(nr) }.map(&:first)
+            next if denied.empty? || allowed.empty?
+
+            finding(policy, group, denied, allowed)
+          end
+        end
+
+        # @!visibility private
+        def finding(policy, group, denied, allowed)
+          Finding.new(
+            id: 'syscall-alt-gap', severity: %i[exec open].include?(group) ? :high : :medium,
+            arch: policy.arch_name,
+            title: "#{denied.join('/')} blocked but #{allowed.join('/')} allowed",
+            detail: "#{denied.join(', ')} denied, but the equivalent #{allowed.join(', ')} reaches " \
+                    'ALLOW - same capability, different syscall number.',
+            # Both sides: the finding is about the pair, and the detail says which is which.
+            syscalls: (denied + allowed).map(&:to_s), condition: nil,
+            remediation: "Deny every equivalent in the group: also block #{allowed.join(', ')}."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/finding'
+
+module SeccompTools
+  class Audit
+    module Checks
+      # amd64's x32 ABI quirk: x32 syscalls share +AUDIT_ARCH_X86_64+ but number as +nr | 0x40000000+.
+      # Without a +sys_number >= 0x40000000+ (or +jset 0x40000000+) guard, a syscall blocked by its
+      # native number is still reachable through its x32 number. Registered only for amd64, so no
+      # other architecture is ever mis-flagged.
+      module X32Guard
+        module_function
+
+        # @param [Audit::Policy] policy
+        # @return [Array<Audit::Finding>]
+        def call(policy)
+          sharp = policy.table.filter_map do |name, nr|
+            next if name.to_s.start_with?('x32_')
+
+            x = policy.number(:"x32_#{name}")
+            name if x && policy.reachable_as_allow?(x) && !policy.reachable_as_allow?(nr)
+          end
+          return [] if sharp.empty?
+
+          [finding(policy, sharp)]
+        end
+
+        # @!visibility private
+        def finding(policy, sharp)
+          shown = sharp.first(8).map(&:to_s)
+          more = sharp.size > shown.size ? ", ... (+#{sharp.size - shown.size} more)" : ''
+          Finding.new(
+            id: 'x32-guard', severity: :high, arch: policy.arch_name,
+            title: 'x32 ABI is not guarded',
+            detail: 'Syscalls blocked by their native number are reachable via their x32 number ' \
+                    "(nr | 0x40000000): #{shown.join(', ')}#{more}.",
+            syscalls: shown, condition: nil,
+            remediation: 'After the arch check, KILL when sys_number >= 0x40000000 ' \
+                         '(or jset 0x40000000).'
+          )
+        end
+      end
+    end
+  end
+end

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