seccomp-tools 1.6.1 → 1.7.0

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

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+
+module SeccompTools
+  class Explain
+    # A 64-bit fact reassembled from 32-bit word checks (see {QwordFusion}); +base+ is the field's
+    # byte offset in +seccomp_data+.
+    Qword = Struct.new(:base, :op, :val) do
+      # Mirrors {Symbolic::Constraint#key} (a string) so fused condition lists can still be compared;
+      # the +q+ prefix keeps it distinct from any constraint key, which starts with an operand char.
+      def key
+        "q#{base},#{op},#{val}"
+      end
+
+      # A {Qword} is a whole-field fact, never a single plain-word one, so it matches neither
+      # predicate. Defining them lets the fusion code treat a mixed list uniformly, without an
+      # +is_a?+ guard on every access.
+      def plain_data_fact?(_offset = nil) = false
+      alias_method :plain_data_eq?, :plain_data_fact?
+    end
+
+    # A 64-bit field of +seccomp_data+ (+instruction_pointer+ or an argument) is two 32-bit words,
+    # and filters check them separately. This class fuses such word facts back into 64-bit ones
+    # ({Qword}), both within one path condition ({#fold}) and across the sibling or-branches
+    # libseccomp compiles a 64-bit range comparison into ({#merge_or}).
+    class QwordFusion
+      # Byte offsets of the 64-bit fields whose two 32-bit words this class fuses.
+      BASES = Const::BPF::SeccompData::QWORD_BASES
+      # How the extra facts of two sibling or-branches fuse into one 64-bit comparison: one branch
+      # holds a strict high-word fact +hi <hi_op> H+ (+hi_op+ is +>+, +<+ or +!=+, normalized by
+      # {#strict}) and the other +hi == H && lo <lo_op> L+; keyed by +[hi_op, lo_op]+, they are
+      # exactly +field <fused op> (H << 32 | L)+. This is the shape libseccomp compiles
+      # SCMP_CMP_GT/GE/LT/LE/NE argument comparisons into.
+      OR_MERGE = {
+        %i[> >] => :>, %i[> >=] => :>=, %i[< <] => :<, %i[< <=] => :<=, %i[!= !=] => :!=
+      }.freeze
+
+      # @param [Symbol] arch
+      #   Decides the word order: on a big-endian architecture the high 32-bit word of a 64-bit
+      #   field comes first.
+      def initialize(arch)
+        @hi_first = Const::Endian.big?(arch)
+      end
+
+      # The byte offset of the low 32-bit word of the 64-bit field at +base+.
+      def lo_off(base)
+        @hi_first ? base + 4 : base
+      end
+
+      # The byte offset of the high 32-bit word of the 64-bit field at +base+.
+      def hi_off(base)
+        @hi_first ? base : base + 4
+      end
+
+      # The byte offset of the 64-bit field that the word at +offset+ belongs to.
+      def base_of(offset)
+        offset - (offset % 8)
+      end
+
+      # Fuses the 32-bit word facts of one path condition into whole-field {Qword}s; facts that do
+      # not form a fusable pair pass through unchanged.
+      # @param [Array<Symbolic::Constraint, Qword>] constraints
+      # @return [Array<Symbolic::Constraint, Qword>]
+      # @example Both halves pinned by == (little-endian: args[0] lo word @16, hi @20)
+      #   fold([ data[20] == 0x1, data[16] == 0x2 ])
+      #   #=> [ Qword(base: 16, op: :==, val: 0x100000002) ]
+      # @example A zero high word with a low-word bound
+      #   fold([ data[20] == 0x0, data[16] < 0x1000 ])
+      #   #=> [ Qword(base: 16, op: :<, val: 0x1000) ]
+      def fold(constraints)
+        plan = qword_plan(constraints)
+        constraints.filter_map do |c|
+          action = plan[c]
+          next if action == :drop
+
+          action || c
+        end
+      end
+
+      # Fuses sibling or-branches that together express one 64-bit comparison, repeatedly until
+      # nothing fuses; branches that do not pair up are returned untouched. See {#fuse_pair} for
+      # the shape of a fusable pair.
+      # @param [Array<Array<Symbolic::Constraint, Qword>>] lists
+      #   The condition lists of one rule's or-branches.
+      # @return [Array<Array<Symbolic::Constraint, Qword>>]
+      # @example The two match branches of a 64-bit +args[0] > 0x200000500+ (little-endian: lo @16, hi @20)
+      #   merge_or([ [ data[20] > 2 ],
+      #              [ data[20] == 2, data[16] > 0x500 ] ])
+      #   #=> [ [ Qword(base: 16, op: :>, val: 0x200000500) ] ]
+      def merge_or(lists)
+        lists = lists.dup # own a mutable copy; the caller's array is left untouched
+        loop { break unless merge_one_pair!(lists) }
+        lists
+      end
+
+      private
+
+      # Maps each constraint to what {#fold} should do with it: a {Qword} to replace it with, or
+      # +:drop+ to remove it. A constraint absent from the plan is kept as-is.
+      def qword_plan(constraints)
+        eqs = constraints.select(&:plain_data_eq?).group_by { |c| c.lhs.offset }.transform_values(&:first)
+        plan = {}
+        BASES.each do |base|
+          hi = eqs[hi_off(base)]
+          next unless hi
+
+          if (lo = eqs[lo_off(base)])
+            plan[lo] = Qword.new(base, :==, (hi.rhs.val << 32) | lo.rhs.val)
+          elsif hi.rhs.val.zero? && (lo = lo_bound(constraints, base))
+            plan[lo] = Qword.new(base, lo.op, lo.rhs.val)
+          else
+            next
+          end
+          plan[hi] = :drop
+        end
+        plan
+      end
+
+      # The +lo < L+ / +lo <= L+ fact on the low word of the field at +base+, if any.
+      def lo_bound(constraints, base)
+        constraints.find { |c| c.plain_data_fact?(lo_off(base)) && %i[< <=].include?(c.op) }
+      end
+
+      # Fuses the first fusable pair of +lists+ in place - dropping the two branches and putting the
+      # fused one at the earlier slot - and returns it, or +nil+ when no pair fused.
+      def merge_one_pair!(lists)
+        lists.each_with_index do |a, i|
+          lists.each_with_index do |b, j|
+            next if i == j
+
+            fused = fuse_pair(a, b)
+            next unless fused
+
+            lo, hi = [i, j].minmax
+            lists[lo] = fused
+            lists.delete_at(hi)
+            return fused
+          end
+        end
+        nil
+      end
+
+      # Fuses two sibling or-branches into one 64-bit fact. It applies when +a+'s only extra fact
+      # (vs +b+) is a strict high-word fact +hi <op> H+, and +b+'s two extras are +hi == H+ plus a
+      # bound on the matching low word: that pair in +b+ is then replaced by the fused {Qword} (see
+      # {OR_MERGE}).
+      # @param [Array<Symbolic::Constraint, Qword>] a
+      #   One or-branch's condition list.
+      # @param [Array<Symbolic::Constraint, Qword>] b
+      #   The sibling branch's condition list.
+      # @return [Array<Symbolic::Constraint, Qword>, nil]
+      #   +b+ with its +hi == H+ / +lo <op> L+ pair collapsed into one {Qword}, or +nil+ when the
+      #   two lists do not have the fusable shape.
+      # @example Fusing the two match paths of a 64-bit +args[0] > 0x200000500+ (little-endian: lo word @16, hi @20)
+      #   a = [ data[20] >  2 ]                    # hi > H
+      #   b = [ data[20] == 2, data[16] > 0x500 ]  # hi == H && lo > L
+      #   fuse_pair(a, b) #=> [ Qword(base: 16, op: :>, val: 0x200000500) ]
+      def fuse_pair(a, b)
+        only_a = minus(a, b)
+        return unless only_a.size == 1
+
+        hi = only_a.first
+        base = hi_field_base(hi)
+        return unless base
+
+        hi_op, hi_val = strict(hi.op, hi.rhs.val)
+        only_b = minus(b, a)
+        eq = only_b.find { |c| c.plain_data_eq?(hi.lhs.offset) && c.rhs.val == hi_val }
+        lo = only_b.find { |c| c.plain_data_fact?(lo_off(base)) }
+        return unless only_b.size == 2 && eq && lo && (op = OR_MERGE[[hi_op, lo.op]])
+
+        b.map { |c| c.equal?(eq) ? Qword.new(base, op, (hi_val << 32) | lo.rhs.val) : c }.reject { |c| c.equal?(lo) }
+      end
+
+      # The field base when +hi+ is a constant comparison on the high word of a 64-bit field;
+      # +nil+ otherwise.
+      def hi_field_base(hi)
+        return unless hi.plain_data_fact?
+
+        base = base_of(hi.lhs.offset)
+        base if BASES.include?(base) && hi.lhs.offset == hi_off(base)
+      end
+
+      # +>= v+ and +> v-1+ are the same test; normalize the high-word comparison to the strict form
+      # so {OR_MERGE} needs only one spelling. At the 32-bit boundary +val+ can step out of range
+      # (+>= 0+ to +> -1+, +<= 0xffffffff+ to +< 0x100000000+), but that is safe: the result is only
+      # matched against a data-word +==+ constant, which is masked to +0..0xffffffff+ and so can
+      # never equal it, and those boundary comparisons are always-true anyway (nothing to fuse).
+      def strict(op, val)
+        case op
+        when :>= then [:>, val - 1]
+        when :<= then [:<, val + 1]
+        else [op, val]
+        end
+      end
+
+      # The constraints in +a+ whose fact does not also appear in +b+.
+      def minus(a, b)
+        a.reject { |c| b.any? { |d| d.key == c.key } }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+require 'seccomp-tools/explain/qword'
+require 'seccomp-tools/util'
+
+module SeccompTools
+  class Explain
+    # Renders path-condition facts ({Symbolic::Constraint}s and {Qword}s) as C-like conditions,
+    # naming the +seccomp_data+ fields and parenthesizing exactly where the expression would
+    # otherwise be misread.
+    class Renderer
+      # C-like operator precedence (higher binds tighter), used to parenthesize a rendered condition
+      # exactly where it would otherwise be misread - notably that +==+ binds tighter than the
+      # bitwise operators, so +a & b == c+ must be shown as +(a & b) == c+.
+      PREC = {
+        :* => 12, :/ => 12, :+ => 11, :- => 11, :<< => 10, :>> => 10,
+        :< => 9, :<= => 9, :> => 9, :>= => 9, :== => 8, :!= => 8,
+        :& => 7, :^ => 6, :| => 5
+      }.freeze
+      # Unary negation binds tighter than any binary operator.
+      UNARY_PREC = 13
+      # The comparison operators. When one is the parent, operands are parenthesized by precedence
+      # alone (so +a & b == c+ becomes +(a & b) == c+ but +a >> b == c+ stays put), never by the
+      # extra readability rule in {#clarity_wrap?}.
+      COMPARISON = %i[== != < <= > >=].freeze
+      # The +seccomp_data+ field layout the rendered names come from.
+      DATA = Const::BPF::SeccompData
+
+      # @param [QwordFusion] fusion
+      #   Supplies the endian-correct word offsets of the 64-bit fields, for naming their halves.
+      def initialize(fusion)
+        @fusion = fusion
+      end
+
+      # Renders a conjunction of facts, e.g. +"fd == 0x1 && (flags & 0xf) < 0x5"+.
+      # @param [Array<Symbolic::Constraint, Qword>] constraints
+      # @param [Symbol?] sys
+      #   The syscall the facts belong to, if pinned - names the arguments.
+      # @return [String]
+      def conjunction(constraints, sys)
+        constraints.map do |c|
+          if c.is_a?(Qword)
+            "#{data_name(@fusion.lo_off(c.base), sys)} #{c.op} 0x#{c.val.to_s(16)}"
+          else
+            constraint(c, sys)
+          end
+        end.join(' && ')
+      end
+
+      private
+
+      def constraint(c, sys)
+        return "(#{binop(:&, c.lhs, c.rhs, sys)}) != 0" if c.op == :set
+        return "(#{binop(:&, c.lhs, c.rhs, sys)}) == 0" if c.op == :unset
+
+        prec = PREC[c.op]
+        "#{operand(c.lhs, c.op, prec, sys)} #{c.op} #{operand(c.rhs, c.op, prec, sys)}"
+      end
+
+      # Renders an expression without any outer parentheses; each caller wraps it via {#operand}.
+      def expr(e, sys)
+        return '<opaque>' if e.opaque?
+        return "0x#{e.val.to_s(16)}" if e.imm?
+        return data_name(e.offset, sys) if e.plain_data?
+        return "-#{operand(e.lhs, :neg, UNARY_PREC, sys)}" if e.kind == :unop
+
+        binop(e.op, e.lhs, e.rhs, sys)
+      end
+
+      # Renders +lhs op rhs+. Operators are left-associative, so the left operand shares +op+'s
+      # precedence while the right needs one higher (an equal-precedence right subtree is wrapped).
+      def binop(op, lhs, rhs, sys)
+        prec = PREC[op]
+        left = operand(lhs, op, prec, sys)
+        right = rhs.imm? && %i[<< >>].include?(op) ? rhs.val.to_s : operand(rhs, op, prec + 1, sys)
+        "#{left} #{op} #{right}"
+      end
+
+      # Renders +child+ as an operand of +parent_op+, parenthesizing it when precedence requires it
+      # (+child+ binds looser than +min_prec+) or when {#clarity_wrap?} judges the grouping too easy
+      # to misread.
+      def operand(child, parent_op, min_prec, sys)
+        s = expr(child, sys)
+        return s unless child.kind == :binop
+
+        PREC[child.op] < min_prec || clarity_wrap?(parent_op, child.op) ? "(#{s})" : s
+      end
+
+      # Should a +child_op+ nested under +parent_op+ be parenthesized purely for readability (beyond
+      # what precedence requires)? Yes when they sit at *different* precedence levels - mixing
+      # families like +a & (b + c)+ or +(a + b) << c+ is easy to misjudge. The exceptions, where the
+      # grouping is universally understood, are: any comparison parent (+a & b == c+ is already made
+      # unambiguous by wrapping the looser +&+), a same-level pair (+a + b - c+, +a ^ b ^ c+), and
+      # multiplication/division directly inside addition/subtraction (+a + b * c+).
+      def clarity_wrap?(parent_op, child_op)
+        return false if COMPARISON.include?(parent_op)
+        return false if PREC[parent_op] == PREC[child_op]
+        return false if PREC[child_op] == PREC[:*] && PREC[parent_op] == PREC[:+]
+
+        true
+      end
+
+      def data_name(offset, sys)
+        case offset
+        when DATA::SYS_NUMBER, DATA::ARCH then DATA::NAMES[offset] # the scalar fields
+        else qword_word_name(offset, sys) # endian-split fields (instruction_pointer, args)
+        end
+      end
+
+      # Names one 32-bit word of a 64-bit field, appending +>> 32+ for the high word - which is the
+      # second word on little-endian architectures but the first on big-endian ones.
+      def qword_word_name(offset, sys)
+        base = @fusion.base_of(offset)
+        return "data[#{offset}]" unless DATA::QWORD_BASES.include?(base)
+
+        name = if base == DATA::INSTRUCTION_POINTER
+                 DATA::NAMES[base]
+               else
+                 idx = (base - DATA::ARGS) / 8
+                 names = sys && Const::SYS_ARG[sys]
+                 Util.colorize((names && names[idx]) || "args[#{idx}]", t: :args)
+               end
+        offset == @fusion.hi_off(base) ? "#{name} >> 32" : name
+      end
+    end
+  end
+end

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

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+require 'seccomp-tools/explain/analysis'
+require 'seccomp-tools/explain/qword'
+require 'seccomp-tools/explain/renderer'
+require 'seccomp-tools/explain/verdict'
+require 'seccomp-tools/util'
+
+module SeccompTools
+  class Explain
+    # Turns the raw {Symbolic::Executor::Leaf}s collected by the walk into a human-readable policy,
+    # grouped by architecture and then by action (+ALLOW+, +KILL+, +ERRNO(n)+, ...).
+    #
+    # This class owns the presentation: sections, buckets and the default rule. It reads each
+    # leaf's path through {PathFacts}, decodes the returned action with {Verdict}, reassembles
+    # 64-bit word checks with {QwordFusion}, and stringifies conditions with {Renderer}.
+    class Summary
+      # Display name of the syscall-number field, for the range subjects.
+      SYS_NAME = Const::BPF::SeccompData::NAMES.fetch(Const::BPF::SeccompData::SYS_NUMBER)
+      # The x32 ABI bit (+__X32_SYSCALL_BIT+); a lower-bound-only range at exactly this value is the
+      # conventional x32 guard, worth annotating.
+      X32_SYSCALL_BIT = 0x40000000
+      # Widest a wrapped bucket line may get, in columns.
+      WRAP_WIDTH = 72
+
+      # @param [Array<Symbolic::Executor::Leaf>] leaves
+      # @param [Symbol] arch
+      #   The filter's declared architecture, used when the filter itself does not branch on +arch+.
+      # @param [String?] source
+      #   Label shown in the header.
+      # @param [Boolean] truncated
+      #   Whether the walk hit {Symbolic::Executor::STEP_CAP}.
+      def initialize(leaves, arch:, source: nil, truncated: false)
+        @arch = arch
+        @source = source
+        @truncated = truncated
+        @fusion = QwordFusion.new(arch)
+        @renderer = Renderer.new(@fusion)
+        @analysis = Analysis.new(leaves)
+      end
+
+      # Renders the policy.
+      # @return [String]
+      def to_s
+        out = +''
+        out << "Seccomp policy for #{@source}\n" if @source
+        out << "WARNING: analysis truncated (filter too large); results may be incomplete.\n" if @truncated
+        @analysis.sections(@arch).each do |_arch_val, arch_sym, title, leaves|
+          out << "\n" << render_section(title, section_buckets(arch_sym, leaves))
+        end
+        out << render_other_arches
+        out
+      end
+
+      private
+
+      # The {PathFacts} of +leaf+, computed once (shared with {Analysis}).
+      def facts(leaf)
+        @analysis.facts(leaf)
+      end
+
+      # Renders what happens on the architectures the filter does not explicitly check for. Usually
+      # those paths just fall to one action and a one-liner suffices; when they carry rules of their
+      # own, a full section is rendered so the rules are not silently dropped.
+      def render_other_arches
+        return '' if @analysis.arch_values.empty?
+
+        leaves = @analysis.other_leaves
+        default = @analysis.default_label(leaves)
+        return '' unless default
+
+        buckets = rule_buckets(nil, leaves, default)
+        return "\nOther architectures: #{default}\n" if buckets.empty?
+
+        add_default(buckets, default)
+        "\n#{render_section('<any other>', buckets)}"
+      end
+
+      # The action buckets of one section: its non-default rules plus the default rule. +arch_sym+
+      # names syscalls/arguments; +nil+ (architecture unknown) leaves them numeric.
+      def section_buckets(arch_sym, leaves)
+        default = @analysis.default_label(leaves)
+        buckets = rule_buckets(arch_sym, leaves, default)
+        add_default(buckets, default)
+        buckets
+      end
+
+      # Renders one architecture section from its prebuilt +buckets+.
+      def render_section(title, buckets)
+        out = "Architecture: #{Util.colorize(title, t: :arch)}\n"
+        return out << "\n  (no return reached; filter runs off the end)\n" if buckets.empty?
+
+        sorted_buckets(buckets).each { |label, b| out << render_bucket(label, b) }
+        out
+      end
+
+      # Buckets the non-default rules of a section by action label. Every leaf falls into exactly
+      # one bucket source: it pins a syscall number, restricts a range of numbers, checks arguments
+      # only, or is the catch-all (rendered by {#add_default}).
+      def rule_buckets(arch_sym, leaves, default)
+        named, rest = leaves.partition { |l| facts(l).sys_eq }
+        ranged, rest = rest.partition { |l| facts(l).sys_range }
+        conditional, = rest.partition { |l| !facts(l).residual.empty? }
+
+        buckets = {}
+        add_named(buckets, arch_sym, named, default)
+        add_ranges(buckets, ranged)
+        add_conditional(buckets, conditional, default)
+        buckets
+      end
+
+      # Explicitly matched syscalls (+A == nr+), grouped by number then verdict.
+      def add_named(buckets, arch_sym, leaves, default)
+        leaves.group_by { |l| facts(l).sys_eq }.sort_by(&:first).each do |nr, group|
+          sys = syscall_name(arch_sym, nr)
+          name = Util.colorize(sys ? sys.to_s : "0x#{nr.to_s(16)}", t: :syscall)
+          group.group_by { |l| Verdict.label(l.ret) }.each do |label, ls|
+            next if label == default # falls through to the default action
+
+            conds = merged_conds(ls, sys)
+            plain = conds.include?('') # some path reaches this verdict with no extra condition
+            entry = plain ? name : "#{name} when #{conds.join(' or ')}"
+            add(buckets, label, entry, simple: plain)
+          end
+        end
+      end
+
+      # Fall-through rules that restrict a range of syscall numbers, e.g. the x32 ABI guard,
+      # together with whatever else those paths check. A range whose action is the default is still
+      # shown when unconditional (the explicit guard is worth surfacing), and its conditional
+      # variants are shown too so no check is silently dropped.
+      def add_ranges(buckets, leaves)
+        leaves.group_by { |l| facts(l).sys_range }.each do |(lo, hi), group|
+          range = "#{SYS_NAME} >= 0x#{lo.to_s(16)}"
+          range << " && #{SYS_NAME} <= 0x#{hi.to_s(16)}" if hi
+          group.group_by { |l| Verdict.label(l.ret) }.each do |label, ls|
+            conds = merged_conds(ls, nil)
+            entry = conds.include?('') ? range.dup : "#{range} when #{conds.join(' or ')}"
+            entry << '  (x32 ABI)' if x32?(lo, hi)
+            add(buckets, label, entry, simple: false)
+          end
+        end
+      end
+
+      # Fall-through rules that inspect arguments (or a transformed syscall number) without pinning a
+      # specific syscall. Kept so such checks are never silently dropped.
+      def add_conditional(buckets, leaves, default)
+        leaves.group_by { |l| Verdict.label(l.ret) }.each do |label, ls|
+          next if label == default
+
+          conds = merged_conds(ls, nil)
+          add(buckets, label, "any syscall when #{conds.join(' or ')}", simple: false)
+        end
+      end
+
+      # The rendered or-branch conditions of the leaves +ls+, deduplicated, with 64-bit word checks
+      # fused back into whole-field facts (see {QwordFusion}).
+      def merged_conds(ls, sys)
+        @fusion.merge_or(ls.map { |l| facts(l).residual })
+               .map { |list| @renderer.conjunction(@fusion.fold(list), sys) }.uniq
+      end
+
+      def add_default(buckets, default)
+        return unless default
+
+        # "other" only makes sense when some syscall was singled out; otherwise the default is the
+        # whole policy.
+        text = buckets.empty? ? '<default> (any syscall)' : '<default> (any other syscall)'
+        add(buckets, default, text, simple: false)
+      end
+
+      def add(buckets, label, text, simple:)
+        b = buckets[label] ||= { simple: [], complex: [] }
+        (simple ? b[:simple] : b[:complex]) << text
+      end
+
+      def sorted_buckets(buckets)
+        buckets.sort_by { |label, _b| Verdict.rank(label) }
+      end
+
+      def render_bucket(label, bucket)
+        out = "\n  #{label}:\n"
+        wrap(bucket[:simple]).each { |line| out << "    #{line}\n" }
+        bucket[:complex].each { |line| out << "    #{line}\n" }
+        out
+      end
+
+      # Wraps a list of short tokens into comma-separated lines no wider than 72 columns.
+      def wrap(tokens)
+        return [] if tokens.empty?
+
+        lines = []
+        line = +''
+        tokens.each do |tok|
+          piece = line.empty? ? tok : ", #{tok}"
+          if !line.empty? && line.size + piece.size > WRAP_WIDTH
+            lines << line
+            line = +tok
+          else
+            line << piece
+          end
+        end
+        lines << line
+      end
+
+      def x32?(lo, hi)
+        lo == X32_SYSCALL_BIT && hi.nil?
+      end
+
+      def syscall_name(arch_sym, nr)
+        arch_sym && Const::Syscall.const_get(arch_sym.upcase).invert[nr]
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+
+module SeccompTools
+  class Explain
+    # Decodes the value a filter path returns into the action it stands for: the label a policy
+    # shows (+ALLOW+, +ERRNO(5)+, ...) and where that action sorts among the buckets.
+    module Verdict
+      # Buckets are printed in this order; unlisted actions sort last.
+      ORDER = %i[ALLOW USER_NOTIF LOG TRACE TRAP ERRNO KILL KILL_PROCESS UNKNOWN].freeze
+
+      module_function
+
+      # The label for the value +ret+ a leaf returns, including the +SECCOMP_RET_DATA+ part when
+      # it is meaningful for the action.
+      # @param [Symbolic::Expr] ret
+      # @return [String]
+      def label(ret)
+        return 'UNKNOWN' unless ret.imm?
+
+        # An unrecognized action value loads fine; the kernel treats it as KILL_PROCESS
+        # (KILL_THREAD before Linux 4.14). See seccomp(2).
+        Const::BPF.action_label(ret.val) || format('KILL_PROCESS (unknown action 0x%x)', ret.val)
+      end
+
+      # Where the bucket labeled +label+ sorts: by its action's position in {ORDER}, then
+      # alphabetically. Works on any label {.label} produces, data and annotations included.
+      # @param [String] label
+      # @return [Array(Integer, String)]
+      def rank(label)
+        [ORDER.index(action_of(label)) || ORDER.size, label]
+      end
+
+      # The bare action symbol of a label, recovered by stripping any +(data)+ / + (annotation)+
+      # suffix {.label} appended. Safe because no action name itself contains +" ("+.
+      # @param [String] label
+      # @return [Symbol]
+      def action_of(label)
+        label.sub(/\s*\(.*/, '').to_sym
+      end
+    end
+  end
+end

data/lib/seccomp-tools/explain.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/explain/summary'
+require 'seccomp-tools/symbolic/executor'
+
+module SeccompTools
+  # Analyzes a whole seccomp filter across all execution paths and summarizes it as a per-action
+  # policy: which syscalls end in +ALLOW+, +KILL+, +ERRNO(n)+, etc., and under what argument
+  # constraints.
+  #
+  # It runs the generic {Symbolic::Executor} over the filter to collect every reachable +return+
+  # together with the path condition that leads to it, then hands those leaves to {Summary}, which
+  # interprets them with seccomp semantics (syscall numbers, architectures, actions, ...).
+  #
+  # @example
+  #   insts = SeccompTools::Disasm.to_bpf(raw, :amd64).map(&:inst)
+  #   puts SeccompTools::Explain.new(insts, arch: :amd64).summarize
+  class Explain
+    # @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 for syscall/argument names.
+    # @param [String?] source
+    #   A label for the filter (e.g. a filename) shown in the summary header.
+    def initialize(instructions, arch:, source: nil)
+      @instructions = instructions
+      @arch = arch
+      @source = source
+    end
+
+    # Walks the filter and returns a printable {Summary}.
+    # @return [Summary]
+    def summarize
+      leaves, truncated = Symbolic::Executor.new(@instructions).run
+      Summary.new(leaves, arch: @arch, source: @source, truncated:)
+    end
+  end
+end

data/lib/seccomp-tools/instruction/alu.rb

@@ -4,7 +4,9 @@ require 'seccomp-tools/instruction/base'
 
 module SeccompTools
   module Instruction
-    # Instruction alu.
+    # Instruction alu, performs an arithmetic or bitwise operation on the accumulator register A.
+    #
+    # The right operand is either the X register or the immediate +k+.
     class ALU < Base
       # Mapping from name to operator.
       OP_SYM = {
@@ -17,10 +19,12 @@ module SeccompTools
         lsh: :<<,
         rsh: :>>,
         # neg: :-, # should not be invoked
-        # mod: :%, # unsupported
+        # mod: :%, # the kernel rejects BPF_MOD (see Const::BPF::OP), so it never reaches here
         xor: :^
       }.freeze
       # Decompile instruction.
+      # @return [String]
+      #   The operation as assembly, e.g. +"A &= 0x7fff"+.
       def decompile
         return 'A = -A' if op == :neg
 
@@ -29,6 +33,8 @@ module SeccompTools
 
       # See {Instruction::Base#symbolize}.
       # @return [[:alu, Symbol, (:x, Integer, nil)]]
+      #   The operator and its right operand, which is +:x+ for the X register, an Integer for an
+      #   immediate, or +nil+ for the unary +neg+.
       def symbolize
         return [:alu, :neg, nil] if op == :neg
 
@@ -36,13 +42,12 @@ module SeccompTools
       end
 
       # See {Base#branch}.
-      # @param [Context] context
-      #   Current context.
-      # @return [Array<(Integer, Context)>]
-      def branch(context)
-        ctx = context.dup
-        ctx[:a] = Disasm::Context::Value.new
-        [[line + 1, ctx]]
+      # @param [Symbolic::State] state
+      #   Current state.
+      # @return [Array<(Integer, Symbolic::State)>]
+      #   Always the next line, with A marked as no longer tracked.
+      def branch(state)
+        [[line + 1, state.with(a: Symbolic::Expr.opaque)]]
       end
 
       private