seccomp-tools 1.6.2 → 1.7.0

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

@@ -4,10 +4,11 @@ require 'seccomp-tools/instruction/ld'
 
 module SeccompTools
   module Instruction
-    # Instruction ldx.
+    # Instruction ldx, same as {LD} but loads into the index register X.
     class LDX < LD
-      # Index register.
-      # @return ['X']
+      # Name of the register being loaded into.
+      # @return [String]
+      #   The index register, +"X"+.
       def reg
         'X'
       end

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

@@ -4,9 +4,11 @@ require 'seccomp-tools/instruction/base'
 
 module SeccompTools
   module Instruction
-    # Instruction misc.
+    # Instruction misc, copies a value between the A and X registers.
     class MISC < Base
       # Decompile instruction.
+      # @return [String]
+      #   Either +"A = X"+ or +"X = A"+.
       def decompile
         case op
         when :txa then 'A = X'
@@ -16,21 +18,21 @@ module SeccompTools
 
       # See {Instruction::Base#symbolize}.
       # @return [[:misc, (:tax, :txa)]]
+      #   +:tax+ copies A into X, +:txa+ copies X into A.
       def symbolize
         [:misc, op]
       end
 
       # See {Base#branch}.
-      # @param [Context] context
-      #   Current context.
-      # @return [Array<(Integer, Context)>]
-      def branch(context)
-        ctx = context.dup
+      # @param [Symbolic::State] state
+      #   Current state.
+      # @return [Array<(Integer, Symbolic::State)>]
+      #   Always the next line, with the copied value recorded in the register.
+      def branch(state)
         case op
-        when :txa then ctx['A'] = ctx['X']
-        when :tax then ctx['X'] = ctx['A']
+        when :txa then [[line + 1, state.with(a: state.x)]]
+        when :tax then [[line + 1, state.with(x: state.a)]]
         end
-        [[line + 1, ctx]]
       end
 
       private

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

@@ -4,22 +4,29 @@ require 'seccomp-tools/instruction/base'
 
 module SeccompTools
   module Instruction
-    # Instruction ret.
+    # Instruction ret, terminates the filter with an action such as +ALLOW+ or +KILL+.
+    #
+    # The action comes from either the accumulator register A or the immediate +k+.
     class RET < Base
       # Decompile instruction.
+      # @return [String]
+      #   The return as assembly, e.g. +"return ERRNO(1)"+.
       def decompile
         "return #{ret_str}"
       end
 
       # See {Instruction::Base#symbolize}.
       # @return [[:ret, (:a, Integer)]]
+      #   +:a+ when the action is taken from the A register, otherwise the immediate action value.
       def symbolize
         [:ret, code & 0x18 == SRC[:a] ? :a : k]
       end
 
       # See {Base#branch}.
-      # @return [[]]
-      #   Always return an empty array.
+      #
+      # Accepts and ignores any arguments, the state is irrelevant here.
+      # @return [Array]
+      #   Always an empty array, a filter stops executing at a return.
       def branch(*)
         []
       end
@@ -30,9 +37,8 @@ module SeccompTools
         _, type = symbolize
         return 'A' if type == :a
 
-        str = ACTION.invert[type & SECCOMP_RET_ACTION_FULL].to_s
-        str += "(#{type & SECCOMP_RET_DATA})" if str == 'ERRNO'
-        str
+        # fall back to the raw value (still re-assemblable) for an action the kernel does not define
+        Const::BPF.action_label(type) || "0x#{type.to_s(16)}"
       end
     end
   end

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

@@ -4,24 +4,33 @@ require 'seccomp-tools/instruction/ld'
 
 module SeccompTools
   module Instruction
-    # Instruction st.
+    # Instruction st, stores the accumulator register A into a slot of the scratch memory.
+    #
+    # {STX} inherits from this class and stores the X register instead.
     class ST < LD
       # Decompile instruction.
+      # @return [String]
+      #   The store as assembly, e.g. +"mem[0] = A"+.
       def decompile
         "mem[#{k}] = #{reg}"
       end
 
       # See {Instruction::Base#symbolize}.
       # @return [[:st, (:a, :x), Integer]]
+      #   The source register and the index of the target memory slot.
       def symbolize
         [:st, reg.downcase.to_sym, k]
       end
 
-      # @return [Array<(Integer, Context)>]
-      def branch(context)
-        ctx = context.dup
-        ctx.store(k, reg)
-        [[line + 1, ctx]]
+      # See {Base#branch}.
+      # @param [Symbolic::State] state
+      #   Current state.
+      # @return [Array<(Integer, Symbolic::State)>]
+      #   Always the next line, with the register's value recorded in the scratch slot.
+      def branch(state)
+        mem = state.mem.dup
+        mem[k] = reg == 'X' ? state.x : state.a
+        [[line + 1, state.with(mem:)]]
       end
     end
   end

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

@@ -4,10 +4,11 @@ require 'seccomp-tools/instruction/st'
 
 module SeccompTools
   module Instruction
-    # Instruction stx.
+    # Instruction stx, same as {ST} but stores the index register X.
     class STX < ST
-      # Index register.
-      # @return ['X']
+      # Name of the register being stored.
+      # @return [String]
+      #   The index register, +"X"+.
       def reg
         'X'
       end

data/lib/seccomp-tools/logger.rb

@@ -13,6 +13,9 @@ module SeccompTools
 
     # Returns a +::Logger+ object for internal logging.
     #
+    # The returned logger writes to +$stdout+ with a formatter that prefixes each message with its
+    # colorized severity and indents continuation lines to align with the first.
+    #
     # @return [::Logger]
     def logger
       ::Logger.new($stdout).tap do |log|
@@ -31,7 +34,17 @@ module SeccompTools
       end
     end
 
-    %i[error].each do |sym|
+    # @!method error(msg)
+    #   Logs +msg+ at the +error+ severity.
+    #   @param [String] msg
+    #     The message to be logged.
+    #   @return [true]
+    # @!method warn(msg)
+    #   Logs +msg+ at the +warn+ severity.
+    #   @param [String] msg
+    #     The message to be logged.
+    #   @return [true]
+    %i[error warn].each do |sym|
       define_method(sym) do |msg|
         logger.__send__(sym, msg)
       end

data/lib/seccomp-tools/symbolic/constraint.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/symbolic/expr'
+
+module SeccompTools
+  module Symbolic
+    # One fact that must hold for the executor to be on a particular path, e.g. +A == 1+ or
+    # +data[16] & 0xffff != 0+. Every conditional jump adds one {Constraint} to each branch it
+    # takes; the accumulated list is the "path condition" carried in {State#path} and reported on a
+    # {Executor::Leaf}.
+    #
+    # A constraint keeps a lone constant on the right: BPF always compares the A register against X
+    # or +k+, but A itself may hold the constant (e.g. +A = 5+ compared against a data word +tax+'d
+    # into X earlier), and every consumer reads "expression op constant". So +Constraint.new(5, :>,
+    # word)+ normalizes to +word < 5+ at construction - the two spellings are one value.
+    class Constraint
+      # The same comparison with its two sides swapped: +5 > x+ is +x < 5+. The bit tests are
+      # symmetric (+&+ commutes).
+      MIRROR = {
+        :== => :==, :!= => :!=, :> => :<, :>= => :<=, :< => :>, :<= => :>=, set: :set, unset: :unset
+      }.freeze
+
+      # Applies one of the constraint operators to concrete operands: the +jset+ bit tests
+      # (+:set+/+:unset+) and the Integer comparisons. Stateless - used to evaluate a pinned
+      # constraint or a candidate value, without building a {Constraint}.
+      # @param [Integer] value
+      # @param [Symbol] op
+      # @param [Integer] k
+      # @return [Boolean]
+      def self.evaluate(value, op, k)
+        case op
+        when :set then !value.nobits?(k)
+        when :unset then value.nobits?(k)
+        else value.public_send(op, k) # the comparisons are all Integer methods
+        end
+      end
+
+      # @return [Expr] The left-hand side (what is being tested).
+      attr_reader :lhs
+      # @return [Symbol] The comparison, one of +:==, :!=, :>, :>=, :<, :<=, :set, :unset+.
+      #   +:set+/+:unset+ mean "some/none of these bits are set" (from a +jset+ test).
+      attr_reader :op
+      # @return [Expr] The right-hand side (what it is compared against).
+      attr_reader :rhs
+
+      # @param [Expr] lhs
+      # @param [Symbol] op
+      # @param [Expr] rhs
+      def initialize(lhs, op, rhs)
+        lhs, op, rhs = rhs, MIRROR[op], lhs if lhs.imm? && !rhs.imm? # keep the constant on the right
+        @lhs = lhs
+        @op = op
+        @rhs = rhs
+      end
+
+      # Is this a fact about one plain data word compared against a constant - about the word at
+      # +offset+, when given? These are the facts rule-based consumers can reason about, e.g. the
+      # feasibility pruning in +Symbolic::Executor+.
+      # @param [Integer?] offset
+      # @return [Boolean]
+      def plain_data_fact?(offset = nil)
+        lhs.plain_data? && rhs.imm? && (offset.nil? || lhs.offset == offset)
+      end
+
+      # Is this a +word == constant+ fact - about the word at +offset+, when given?
+      # @param [Integer?] offset
+      # @return [Boolean]
+      def plain_data_eq?(offset = nil)
+        op == :== && plain_data_fact?(offset)
+      end
+
+      # A string that uniquely identifies this constraint, for both equality and hashing; the
+      # +expr op expr+ counterpart of {Expr#key}, injective for the same reason.
+      # @return [String]
+      def key
+        @key ||= "#{lhs.key}#{op}#{rhs.key}"
+      end
+    end
+  end
+end

data/lib/seccomp-tools/symbolic/executor.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'set'
+
+require 'seccomp-tools/symbolic/constraint'
+require 'seccomp-tools/symbolic/expr'
+require 'seccomp-tools/symbolic/state'
+
+module SeccompTools
+  module Symbolic
+    # Symbolic executor for classic BPF (the byte-code seccomp filters are written in).
+    #
+    # A normal interpreter (see +SeccompTools::Emulator+) runs a program *once* with concrete inputs
+    # and follows the one path those inputs select. A symbolic executor instead keeps the inputs
+    # *unknown* ({Expr}) and explores **every** path through the program at once. Wherever the
+    # program branches, it walks both sides, remembering on each side the {Constraint} that made
+    # that branch taken. When a path reaches a +return+, the executor records a {Leaf}: the value
+    # returned plus the exact list of conditions that lead there. The collection of leaves is a
+    # complete, input-independent description of what the program does.
+    #
+    # The machine model is classic BPF: two registers (A and X), 16 scratch-memory slots, and a
+    # read-only input buffer addressed by byte offset. Jumps are always forward, so a single walk
+    # with a visited-set terminates and never loops.
+    #
+    # @example
+    #   # instructions come from `SeccompTools::Disasm.to_bpf(raw, arch).map(&:inst)`
+    #   leaves, truncated = SeccompTools::Symbolic::Executor.new(instructions).run
+    #   leaves.first.ret   #=> an Expr describing the returned value
+    #   leaves.first.path  #=> the Array<Constraint> under which it is returned
+    class Executor
+      # A reached +return+: the accumulated path condition, the value returned (an {Expr}), and the
+      # line the +return+ is on.
+      Leaf = Struct.new(:path, :ret, :line)
+
+      # Upper bound on the number of states visited, so a pathological program cannot make the walk
+      # run unboundedly. When hit, {#run} stops early and reports +truncated+.
+      STEP_CAP = 100_000
+
+      # Maps a comparison operator to the pair of {Constraint} operators implied on the taken and
+      # not-taken branches (e.g. a +>=+ test learns +>=+ if taken, +<+ if not).
+      SPLIT = {
+        :== => %i[== !=],
+        :> => %i[> <=],
+        :>= => %i[>= <],
+        :& => %i[set unset]
+      }.freeze
+
+      # @param [Array<Instruction::Base>] instructions
+      #   The program to execute, as +SeccompTools::Disasm.to_bpf(raw, arch).map(&:inst)+. Only the
+      #   duck-typed +#symbolize+ method is used, so any classic-BPF instruction set works.
+      def initialize(instructions)
+        @instructions = instructions
+      end
+
+      # Walks every path and returns the reachable leaves.
+      #
+      # Leaves whose path condition is self-contradictory (e.g. +A == 1+ and +A == 2+ on the same
+      # word) are dropped - a conditional jump forks both ways regardless of feasibility, so the
+      # walk can construct paths that can never happen at runtime. See {#feasible?} for exactly
+      # what can (and deliberately cannot) be proven contradictory.
+      # @return [Array(Array<Leaf>, Boolean)]
+      #   The feasible leaves, and whether the walk was truncated at {STEP_CAP}.
+      def run
+        leaves, truncated = walk
+        [leaves.select { |leaf| feasible?(leaf.path) }, truncated]
+      end
+
+      private
+
+      # Depth-first walk of the control-flow graph. Because jumps are always forward, every successor
+      # line is strictly greater, so the walk terminates; identical +(line, state)+ pairs are
+      # visited once so that re-merging control-flow does not explode.
+      # @return [Array(Array<Leaf>, Boolean)]
+      def walk
+        leaves = []
+        visited = Set.new
+        stack = [[0, State.initial]]
+        steps = 0
+        until stack.empty?
+          return [leaves, true] if steps >= STEP_CAP
+
+          steps += 1
+          pc, st = stack.pop
+          next if pc >= @instructions.size
+          next unless visited.add?([pc, st.key])
+
+          step(pc, st, leaves, stack)
+        end
+        [leaves, false]
+      end
+
+      # Interprets one instruction symbolically, pushing the successor state(s) onto +stack+ (or
+      # appending a {Leaf} when it is a +return+).
+      def step(pc, st, leaves, stack)
+        op, *args = @instructions[pc].symbolize
+        case op
+        when :ret then leaves << Leaf.new(st.path, args[0] == :a ? st.a : Expr.imm(args[0]), pc)
+        when :ld then stack << [pc + 1, load(st, args[0], args[1])]
+        when :st then stack << [pc + 1, store(st, args[0], args[1])]
+        when :alu then stack << [pc + 1, st.with(a: st.a.apply(args[0], alu_operand(st, args[1])))]
+        when :misc then stack << [pc + 1, args[0] == :txa ? st.with(a: st.x) : st.with(x: st.a)]
+        when :jmp then stack << [pc + args[0] + 1, st]
+        when :cmp then branch_cmp(pc, st, args, stack)
+        end
+      end
+
+      # The right operand of an ALU instruction: the X register, an immediate, or +nil+ for the
+      # unary +neg+ (whose symbolized operand is +nil+).
+      def alu_operand(st, src)
+        return st.x if src == :x
+
+        src && Expr.imm(src)
+      end
+
+      # Loads an immediate, a scratch slot, or a data-buffer word into register A or X.
+      def load(st, dst, src)
+        val = case src[:rel]
+              when :immi then Expr.imm(src[:val])
+              when :mem then st.mem[src[:val]]
+              when :data then Expr.data(src[:val])
+              end
+        dst == :x ? st.with(x: val) : st.with(a: val)
+      end
+
+      # Stores register A or X into a scratch slot.
+      def store(st, reg, idx)
+        mem = st.mem.dup
+        mem[idx] = reg == :x ? st.x : st.a
+        st.with(mem:)
+      end
+
+      # Forks a conditional jump into its taken and not-taken successors, recording the {Constraint}
+      # each branch implies. A comparison between two constants (e.g. against the guaranteed-zero
+      # initial A or X) does not fork: only the branch it actually selects is walked, and no fact
+      # is recorded.
+      def branch_cmp(pc, st, args, stack)
+        op, src, jt, jf = args
+        # jt == jf: the jump is unconditional, so no fact is learned.
+        return stack << [pc + jt + 1, st] if jt == jf
+
+        rhs = src == :x ? st.x : Expr.imm(src)
+        taken, els = SPLIT[op]
+        if st.a.imm? && rhs.imm?
+          j = Constraint.evaluate(st.a.val, taken, rhs.val) ? jt : jf
+          return stack << [pc + j + 1, st]
+        end
+
+        stack << [pc + jt + 1, st.with(path: st.path + [Constraint.new(st.a, taken, rhs)])]
+        stack << [pc + jf + 1, st.with(path: st.path + [Constraint.new(st.a, els, rhs)])]
+      end
+
+      # Is +path+ satisfiable? Deliberately a small rule-based check, not a solver.
+      #
+      # Only facts of the shape "untransformed data word compared to a constant" are examined,
+      # grouped by which word they constrain; any other fact (a transformed word, a comparison
+      # against X, an opaque value) is assumed satisfiable. So an impossible path is never
+      # *wrongly* dropped - the cost of not understanding a fact is noise in the caller's output,
+      # never hidden behavior.
+      #
+      # That fragment is where essentially all real contradictions live. The walk forks every
+      # conditional both ways, so re-merging tests over the same word manufacture impossible
+      # paths: a syscall allowlist behind an x32 range guard yields
+      # +sys >= 0x40000000 && sys == 2+, libseccomp's binary-search dispatch yields the same
+      # equality-versus-range shapes, and sentinel tests yield +sys == 0xffffffff && sys == 2+.
+      # All of these are caught, and since the data words are independent inputs, checking
+      # word-by-word is exact for this fragment, not an approximation: a conjunction of
+      # single-word facts is satisfiable iff each word's facts are.
+      #
+      # What it cannot prove infeasible are contradictions through *derived* values:
+      # +(args[0] & 0xff) == 0x100+ (impossible by masking), wraparound arithmetic like
+      # +args[0] + 1 == 0 && args[0] == 5+, or relations between two transforms of one word
+      # (+sys >> 8 == 1 && sys < 0x100+). Deciding those in general is bit-vector SMT; a filter
+      # convoluted enough to produce them (a deliberately obfuscated challenge, not a seccomp
+      # library) calls for a real solver anyway, so rule-based pruning of that space would add
+      # complexity without making such filters readable. Their paths are kept and rendered with
+      # their full conditions instead.
+      # @param [Array<Constraint>] path
+      # @return [Boolean]
+      def feasible?(path)
+        path.select(&:plain_data_fact?)
+            .group_by { |c| c.lhs.offset }
+            .all? { |_offset, cs| cell_feasible?(cs) }
+      end
+
+      # Are the constraints on a single data word jointly satisfiable? Two different +==+ values
+      # are impossible (+A == 1 && A == 2+). A single +==+ pins the word, so every other fact -
+      # +!=+, the four bounds, and both jset forms - is simply evaluated against it
+      # (+A >= 0x40000000 && A == 2+ dies here). With no +==+, the inequalities must leave a
+      # non-empty range (+A > 10 && A < 5+); +!=+ and jset facts are ignored in that case, since
+      # ruling out a 32-bit word with them alone would take a filter no library generates.
+      def cell_feasible?(constraints)
+        eqs = constraints.select { |c| c.op == :== }.map { |c| c.rhs.val }.uniq
+        return false if eqs.size > 1
+        return constraints.all? { |c| Constraint.evaluate(eqs.first, c.op, c.rhs.val) } unless eqs.empty?
+
+        lo = 0
+        hi = 0xffffffff
+        constraints.each do |c|
+          case c.op
+          when :> then lo = [lo, c.rhs.val + 1].max
+          when :>= then lo = [lo, c.rhs.val].max
+          when :< then hi = [hi, c.rhs.val - 1].min
+          when :<= then hi = [hi, c.rhs.val].min
+          end
+        end
+        lo <= hi
+      end
+    end
+  end
+end

data/lib/seccomp-tools/symbolic/expr.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/instruction/alu'
+
+module SeccompTools
+  # Generic symbolic execution of classic BPF, with no seccomp knowledge. Where +SeccompTools::Emulator+
+  # runs a program once with concrete inputs, the {Executor} here keeps the inputs unknown and walks
+  # *every* path, reporting each reachable +return+ together with the conditions that lead to it. The
+  # values it manipulates are the {Expr}, {Constraint}, and {State} types; see {Executor} for the
+  # full picture.
+  module Symbolic
+    # A value the executor only knows *symbolically* - that is, without picking concrete inputs.
+    #
+    # Every register and scratch slot in the {State} holds an {Expr}, which is one of:
+    # * {.imm} - a known 32-bit constant, e.g. the result of +A = 5+.
+    # * {.data} - a single word of the input data buffer, at some byte +offset+. Its value is
+    #   unknown; we only remember where it was read from.
+    # * {.binop} - an arithmetic combination of two sub-expressions, e.g. +data[16] & 0xffff+ or even
+    #   +data[16] & data[24]+ (two buffer words combined). This is what lets a caller later describe a
+    #   branch condition faithfully.
+    # * {.unop} - a unary operation on a sub-expression; the only one BPF has is negation (+-A+).
+    # * {.opaque} - a value we cannot describe (an unsupported operation, or one whose operand is
+    #   itself opaque). Nothing can be concluded about it.
+    class Expr
+      # The binary ALU operators {#apply} accepts - exactly the ones +Instruction::ALU#symbolize+
+      # can produce (its unary +neg+ is handled separately).
+      REPRESENTABLE = Instruction::ALU::OP_SYM.values.freeze
+
+      # @return [:imm, :data, :binop, :unop, :opaque] Which kind of expression this is.
+      attr_reader :kind
+      # @return [Integer?] The constant, when +kind+ is +:imm+.
+      attr_reader :val
+      # @return [Integer?] The byte offset into the input data buffer, when +kind+ is +:data+.
+      attr_reader :offset
+      # @return [Symbol?] The operator, when +kind+ is +:binop+ or +:unop+.
+      attr_reader :op
+      # @return [Expr?] The left and right operands, when +kind+ is +:binop+; a +:unop+ keeps its
+      #   only operand in +lhs+.
+      attr_reader :lhs, :rhs
+
+      # A known constant.
+      # @param [Integer] val
+      # @return [Expr]
+      def self.imm(val)
+        new(:imm, val: val & 0xffffffff)
+      end
+
+      # A single word of the input data buffer.
+      # @param [Integer] offset
+      #   Byte offset into the buffer.
+      # @return [Expr]
+      def self.data(offset)
+        new(:data, offset:)
+      end
+
+      # An arithmetic combination of two expressions.
+      # @param [Symbol] op
+      # @param [Expr] lhs
+      # @param [Expr] rhs
+      # @return [Expr]
+      def self.binop(op, lhs, rhs)
+        new(:binop, op:, lhs:, rhs:)
+      end
+
+      # A unary operation on one expression (its operand is kept in +lhs+).
+      # @param [Symbol] op
+      # @param [Expr] operand
+      # @return [Expr]
+      def self.unop(op, operand)
+        new(:unop, op:, lhs: operand)
+      end
+
+      # A value that cannot be described symbolically.
+      # @return [Expr]
+      def self.opaque
+        new(:opaque)
+      end
+
+      # @param [:imm, :data, :binop, :unop, :opaque] kind
+      # @param [Hash] fields
+      #   The kind-specific fields: +:val+, +:offset+, +:op+, +:lhs+, +:rhs+.
+      def initialize(kind, **fields)
+        @kind = kind
+        @val = fields[:val]
+        @offset = fields[:offset]
+        @op = fields[:op]
+        @lhs = fields[:lhs]
+        @rhs = fields[:rhs]
+      end
+
+      # @return [Boolean]
+      def imm?
+        kind == :imm
+      end
+
+      # Is this a bare data-buffer word (no arithmetic applied)? These are the values a caller can
+      # compare directly against a constant.
+      # @return [Boolean]
+      def plain_data?
+        kind == :data
+      end
+
+      # @return [Boolean]
+      def opaque?
+        kind == :opaque
+      end
+
+      # Applies an ALU operation, returning the resulting {Expr}. +neg+ is unary (its operand is
+      # ignored). Two constants fold into a new constant; an operation on non-opaque operands
+      # becomes a {.binop}; an opaque operand makes the result {.opaque}.
+      # @param [Symbol] op
+      #   A Ruby operator symbol as produced by +Instruction::ALU#symbolize+, or +:neg+.
+      # @param [Expr, nil] operand
+      #   The right operand (+nil+ for the unary +neg+).
+      # @return [Expr]
+      # @raise [ArgumentError]
+      #   When +op+ is not one of seccomp's ALU operators (+:neg+ or {REPRESENTABLE}).
+      def apply(op, operand)
+        return apply_neg if op == :neg
+        raise ArgumentError, "unsupported operator #{op}" unless REPRESENTABLE.include?(op)
+        return Expr.opaque if opaque? || operand.opaque?
+        return Expr.imm(self.class.fold(val, op, operand.val)) if imm? && operand.imm?
+
+        Expr.binop(op, self, operand)
+      end
+
+      # A string that uniquely identifies this expression, used for both equality and hashing;
+      # memoized, since an {Expr} is immutable. The operator is written as text, not left a {Symbol},
+      # because Ruby's +Symbol#hash+ maps the operators to very few values (+:==+ and +:!=+ hash
+      # alike) - a key carrying them would collapse when hashed and drag the walk's visited +Set+
+      # down to a linear scan; a string hashes over its bytes cleanly. The encoding is injective
+      # (leaves are +i<val>+ / +d<offset>+ / +o+, compounds are parenthesised, and no operator
+      # contains a leaf-start char, a digit, or the +;+ / +,+ that {State} joins with), so it is
+      # safe to compare on.
+      # @return [String]
+      def key
+        @key ||= case kind
+                 when :binop then "(#{lhs.key}#{op}#{rhs.key})"
+                 when :unop  then "(#{op}#{lhs.key})"
+                 when :imm   then "i#{val}"
+                 when :data  then "d#{offset}"
+                 else 'o'
+                 end
+      end
+
+      # @param [Expr] other
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(Expr) && key == other.key
+      end
+      alias eql? ==
+
+      # @return [Integer]
+      def hash
+        key.hash
+      end
+
+      # Folds a binary ALU operation on two constants, wrapping to 32 bits (classic BPF is 32-bit).
+      # Every {REPRESENTABLE} operator is a Ruby +Integer+ method, so it applies directly.
+      # @return [Integer]
+      def self.fold(lhs, op, rhs)
+        return 0 if op == :/ && rhs.zero? # a real BPF program is rejected at load for div-by-zero
+        # ... and for shifts of 32+ bits; short-circuit them to their masked result (everything
+        # shifted out) instead of building a needlessly huge integer.
+        return 0 if %i[<< >>].include?(op) && rhs >= 32
+
+        lhs.public_send(op, rhs) & 0xffffffff
+      end
+
+      private
+
+      # The unary negation +A = -A+ (two's complement, 32-bit). Negating a negation cancels - exact
+      # in 32-bit two's complement - instead of stacking into +--x+, which C would even lex as a
+      # decrement.
+      # @return [Expr]
+      def apply_neg
+        return Expr.opaque if opaque?
+        return Expr.imm(self.class.fold(0, :-, val)) if imm?
+        return lhs if kind == :unop # the only unop is :neg
+
+        Expr.unop(:neg, self)
+      end
+    end
+  end
+end