seccomp-tools 1.6.1 → 1.7.0

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

@@ -3,9 +3,15 @@
 require 'seccomp-tools/const'
 
 module SeccompTools
-  # For instructions' class.
+  # Classes of BPF instructions, one per opcode class.
+  #
+  # Each instruction wraps a {SeccompTools::BPF} and knows how to render itself as assembly
+  # (+decompile+), as tokens ({Base#symbolize}), and how it moves the disassembler's state
+  # forward ({Base#branch}).
   module Instruction
     # Base class of instructions.
+    #
+    # Subclasses must implement {#branch} and {#symbolize}.
     class Base
       include SeccompTools::Const::BPF
 
@@ -25,29 +31,52 @@ module SeccompTools
       end
 
       # Returns the possible branches after executing this instruction.
-      # @param [Context] _context
-      #   Current context.
-      # @return [Array<(Integer, Context)>]
+      #
+      # Each branch is the line number to be executed next, paired with the {Symbolic::State} that
+      # reaching that line implies. Non-jump instructions have exactly one branch, the following
+      # line.
+      # @param [Symbolic::State] _state
+      #   Current state.
+      # @return [Array<(Integer, Symbolic::State)>]
+      #   Pairs of the next line number and the state at that line.
+      # @raise [NotImplementedError]
+      #   Always, subclasses must override this method.
       # @example
       #   # For ALU, LD, LDX, ST, STX
       #   inst.line #=> 10
-      #   inst.branch(ctx)
-      #   #=> [[11, ctx]]
-      def branch(_context); raise NotImplmentedError
+      #   inst.branch(state)
+      #   #=> [[11, state]]
+      def branch(_state); raise NotImplementedError
       end
 
-      # Return tokens stand for this instruction.
+      # Returns tokens that represent this instruction.
       # @return [Array<Symbol, Integer>]
+      #   The instruction as a tuple, the exact shape depends on the instruction class.
+      # @raise [NotImplementedError]
+      #   Always, subclasses must override this method.
       # @example
       #   ret_a.symbolize #=> [:ret, :a]
       #   ret_k.symbolize #=> [:ret, 0x7fff0000]
       #   jeq.symbolize #=> [:cmp, :==, 0, 0, 1]
-      def symbolize; raise NotImplmentedError
+      def symbolize; raise NotImplementedError
       end
 
       private
 
-      %i(code jt jf k arch line contexts show_arg_infer?).each do |sym|
+      # The architecture this instruction's operands should be read as: the one the filter has
+      # branched on (+arch == AUDIT_ARCH_*+) when the reaching states pin a single value, else +nil+
+      # so callers fall back to the declared {#arch}. Lets syscall/argument names stay correct even
+      # when the filter is disassembled under a different +--arch+ than it targets.
+      # @return [Symbol?]
+      def infer_arch
+        arches = states.map { |st| st.pinned(Const::BPF::SeccompData::ARCH) }.uniq
+        return nil unless arches.size == 1 && !arches.first.nil?
+
+        Const::Audit.arch_symbol(arches.first)
+      end
+
+      # Delegate the accessors of the wrapped {SeccompTools::BPF} so subclasses can use them directly.
+      %i(code jt jf k arch line states show_arg_infer?).each do |sym|
         define_method(sym) do
           @bpf.__send__(sym)
         end

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

@@ -5,9 +5,13 @@ require 'seccomp-tools/instruction/base'
 
 module SeccompTools
   module Instruction
-    # Instruction jmp.
+    # Instruction jmp, an unconditional jump or a comparison of A against X or an immediate.
+    #
+    # Jumps are always forward, +jt+ and +jf+ being offsets relative to the following line.
     class JMP < Base
       # Decompile instruction.
+      # @return [String]
+      #   The jump as assembly, e.g. +"if (A == read) goto 0003"+.
       def decompile
         return goto(k) if jop == :none
         # if jt == 0 && jf == 0 => no-op # should not happen
@@ -23,6 +27,8 @@ module SeccompTools
 
       # See {Instruction::Base#symbolize}.
       # @return [[:cmp, Symbol, (:x, Integer), Integer, Integer], [:jmp, Integer]]
+      #   +[:jmp, offset]+ for an unconditional jump, otherwise +[:cmp, operator, right operand,
+      #   jt, jf]+.
       def symbolize
         return [:jmp, k] if jop == :none
 
@@ -30,19 +36,49 @@ module SeccompTools
       end
 
       # See {Base#branch}.
-      # @param [Context] context
-      #   Current context.
-      # @return [Array<(Integer, Context)>]
-      def branch(context)
-        return [[at(k), context]] if jop == :none
-        return [[at(jt), context]] if jt == jf
-        return [[at(jt), context.dup.eql!(src)], [at(jf), context]] if jop == :==
-
-        [[at(jt), context], [at(jf), context]]
+      #
+      # Unlike the other instructions, a conditional jump has two possible successors. On the
+      # taken branch of an equality test the state is narrowed, recording that A is known to equal
+      # the compared value.
+      # @param [Symbolic::State] state
+      #   Current state.
+      # @return [Array<(Integer, Symbolic::State)>]
+      #   One pair for an unconditional jump, two otherwise.
+      # @example
+      #   # 0000: if (A == 0) goto 0002 else goto 0003
+      #   jeq.branch(state) #=> [[2, narrowed_state], [3, state]]
+      def branch(state)
+        return [[at(k), state]] if jop == :none
+        return [[at(jt), state]] if jt == jf
+        return [[at(jt), narrow(state)], [at(jf), state]] if jop == :==
+
+        [[at(jt), state], [at(jf), state]]
       end
 
       private
 
+      # The taken branch of +A == src+ learns +A == value+. When A holds a plain data word and the
+      # compared side is (or resolves to) a constant, that pins the word - recorded as a
+      # {Symbolic::Constraint} on the path. Anything else leaves the state unchanged.
+      # @param [Symbolic::State] state
+      # @return [Symbolic::State]
+      def narrow(state)
+        return state unless state.a.plain_data?
+
+        rhs = src == :x ? resolve(state, state.x) : Symbolic::Expr.imm(k)
+        return state unless rhs.imm?
+
+        state.with(path: state.path + [Symbolic::Constraint.new(state.a, :==, rhs)])
+      end
+
+      # Replaces a data-word +expr+ with the constant it is pinned to on +state+'s path, if any;
+      # otherwise returns it unchanged.
+      def resolve(state, expr)
+        return expr unless expr.plain_data?
+
+        state.path.find { |c| c.plain_data_eq?(expr.offset) }&.rhs || expr
+      end
+
       def jop
         case Const::BPF::JMP.invert[code & 0x70]
         when :ja then :none
@@ -57,15 +93,15 @@ module SeccompTools
       def src_str
         return 'X' if src == :x
 
-        # if A in all contexts are same
-        a = contexts.map(&:a).uniq
+        # only when A holds the same data word across every reaching state
+        a = states.map(&:a).uniq
         return k.to_s if a.size != 1
 
         a = a[0]
-        return k.to_s unless a.data?
+        return k.to_s unless a.plain_data?
 
         hex = "0x#{k.to_s(16)}"
-        case a.val
+        case a.offset
           # interpret as syscalls only if it's an equality test
         when 0 then Util.colorize(jop == :== ? sysname_by_k || hex : hex, t: :syscall)
         when 4 then Util.colorize(Const::Audit::ARCH.invert[k] || hex, t: :arch)
@@ -81,15 +117,6 @@ module SeccompTools
         a == arch ? name : "#{a}.#{name}"
       end
 
-      # Infers the architecture from context.
-      # @return [Symbol?]
-      def infer_arch
-        arches = contexts.map { |ctx| ctx.known_data[4] }.uniq
-        return nil unless arches.size == 1 && !arches.first.nil?
-
-        Const::Audit::ARCH_NAME.invert[Const::Audit::ARCH.invert[arches.first]]
-      end
-
       def src
         SRC.invert[code & 8] == :x ? :x : k
       end

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

@@ -6,9 +6,14 @@ require 'seccomp-tools/util'
 
 module SeccompTools
   module Instruction
-    # Instruction ld.
+    # Instruction ld, loads a value into the accumulator register A.
+    #
+    # The value can be an immediate, a word of +struct seccomp_data+, or a slot of the scratch
+    # memory. {LDX} inherits from this class and targets the X register instead.
     class LD < Base
       # Decompile instruction.
+      # @return [String]
+      #   The assignment as assembly, e.g. +"A = sys_number"+.
       def decompile
         ret = "#{reg} = "
         _, _reg, type = symbolize
@@ -18,26 +23,35 @@ module SeccompTools
         ret + seccomp_data_str
       end
 
-      # @return [void]
+      # See {Instruction::Base#symbolize}.
+      # @return [[:ld, Symbol, {rel: Symbol, val: Integer}]]
+      #   The target register and the value being loaded, whose +:rel+ is one of +:immi+, +:mem+
+      #   or +:data+.
       def symbolize
         type = load_val
         [:ld, reg.downcase.to_sym, type]
       end
 
-      # Accumulator register.
-      # @return ['A']
+      # Name of the register being loaded into.
+      # @return [String]
+      #   The accumulator register, +"A"+.
       def reg
         'A'
       end
 
       # See {Base#branch}.
-      # @param [Context] context
-      #   Current context.
-      # @return [Array<(Integer, Context)>]
-      def branch(context)
-        ctx = context.dup
-        ctx.load(reg, **load_val)
-        [[line + 1, ctx]]
+      # @param [Symbolic::State] state
+      #   Current state.
+      # @return [Array<(Integer, Symbolic::State)>]
+      #   Always the next line, with the loaded value recorded in the register.
+      def branch(state)
+        v = load_val
+        val = case v[:rel]
+              when :immi then Symbolic::Expr.imm(v[:val])
+              when :mem then state.mem[v[:val]]
+              when :data then Symbolic::Expr.data(v[:val])
+              end
+        [[line + 1, reg == 'X' ? state.with(x: val) : state.with(a: val)]]
       end
 
       private
@@ -64,33 +78,44 @@ module SeccompTools
       #   __u64 args[6];
       # };
       def seccomp_data_str
+        data = Const::BPF::SeccompData
         case k
-        when 0 then 'sys_number'
-        when 4 then 'arch'
-        when 8 then 'instruction_pointer'
-        when 12 then 'instruction_pointer >> 32'
+        when data::SYS_NUMBER, data::ARCH then data::NAMES[k]
+        when data::INSTRUCTION_POINTER, data::INSTRUCTION_POINTER + 4
+          ip = data::NAMES[data::INSTRUCTION_POINTER]
+          hi_word?(k) ? "#{ip} >> 32" : ip
         else
-          idx = Array.new(12) { |i| i * 4 + 16 }.index(k)
+          idx = (data::ARGS...data::SIZE).step(4).to_a.index(k)
           return 'INVALID' if idx.nil?
 
           args_name(idx)
         end
       end
 
+      # Is the 32-bit word at byte offset +k+ the high half of its 64-bit +seccomp_data+ field?
+      # The high word comes second on little-endian architectures but first on big-endian ones
+      # (s390x); see +arch_arg_offset_hi+ in libseccomp.
+      def hi_word?(k)
+        (k % 8 == 4) ^ Const::Endian.big?(arch)
+      end
+
       def args_name(idx)
-        default = idx.even? ? "args[#{idx / 2}]" : "args[#{idx / 2}] >> 32"
+        hi = hi_word?((idx * 4) + Const::BPF::SeccompData::ARGS)
+        default = hi ? "args[#{idx / 2}] >> 32" : "args[#{idx / 2}]"
         return default unless show_arg_infer?
 
-        sys_nrs = contexts.map { |ctx| ctx.known_data[0] }.uniq
+        sys_nrs = states.map { |st| st.pinned(Const::BPF::SeccompData::SYS_NUMBER) }.uniq
         return default if sys_nrs.size != 1 || sys_nrs.first.nil?
 
-        sys = Const::Syscall.const_get(arch.upcase.to_sym).invert[sys_nrs.first]
+        a = infer_arch || arch
+        sys = Const::Syscall.const_get(a.upcase.to_sym).invert[sys_nrs.first]
         args = Const::SYS_ARG[sys]
         return default if args.nil? || args[idx / 2].nil? # function prototype doesn't have that argument
 
-        comment = "# #{sys}(#{args.join(', ')})"
+        name = a == arch ? sys : "#{a}.#{sys}"
+        comment = "# #{name}(#{args.join(', ')})"
         arg_name = Util.colorize(args[idx / 2], t: :args)
-        "#{idx.even? ? arg_name : "#{arg_name} >> 32"} #{Util.colorize(comment, t: :gray)}"
+        "#{hi ? "#{arg_name} >> 32" : arg_name} #{Util.colorize(comment, t: :gray)}"
       end
     end
   end

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|
@@ -24,14 +27,24 @@ module SeccompTools
             str.strip.empty? ? str : prep + str
           end
           color = severity.downcase.to_sym
-          msg = +"[#{SeccompTools::Util.colorize(severity, t: color)}] #{message.join}"
+          msg = "[#{SeccompTools::Util.colorize(severity, t: color)}] #{message.join}"
           msg << "\n" unless msg.end_with?("\n")
           msg
         end
       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