seccomp-tools 1.6.1 → 1.7.0

data/lib/seccomp-tools/dumper.rb

@@ -1,57 +1,64 @@
 # frozen_string_literal: true
 
 require 'os'
+require 'timeout'
 
 require 'seccomp-tools/logger'
 require 'seccomp-tools/ptrace' if OS.linux?
 require 'seccomp-tools/syscall'
+require 'seccomp-tools/util'
 
 module SeccompTools
   # Dump seccomp-bpf using ptrace of binary.
   module Dumper
     # Whether the dumper is supported.
-    # Dumper works based on ptrace, so we need the platform be Linux.
+    # Dumper works based on ptrace, so we need the platform to be Linux.
     SUPPORTED = OS.linux?
 
     module_function
 
     # Main bpf dump function.
-    # Yield seccomp bpf whenever find a +prctl(SET_SECCOMP)+ call.
+    # Yields seccomp bpf whenever a +prctl(SET_SECCOMP)+ call is found.
     #
     # @param [Array<String>] args
-    #   The arguments for target execution file.
+    #   The command to be executed, i.e. the target executable followed by its arguments.
     # @param [Integer] limit
     #   By default, +dump+ will only dump the first +SET_SECCOMP+ call.
     #   Set +limit+ to the number of calling +prctl(SET_SECCOMP)+ then the child process will be killed when number of
     #   calling +prctl+ reaches +limit+.
     #
     #   Negative number for unlimited.
+    # @param [Float?] timeout
+    #   Number of seconds to wait for the target process. When the timeout is reached, the target
+    #   process is killed and the filters dumped so far are returned. +nil+ for no timeout.
     # @yieldparam [String] bpf
     #   Seccomp bpf in raw bytes.
-    # @yieldparam [Symbol] arch
-    #   Architecture of the target process.
+    # @yieldparam [Symbol?] arch
+    #   Architecture of the target process, +nil+ when it cannot be determined.
+    #   See {SeccompTools::Util.process_arch}.
     # @return [Array<Object>, Array<String>]
-    #   Return the block returned. If block is not given, array of raw bytes will be returned.
+    #   One entry per dumped filter: the block's return values when a block is given, otherwise the
+    #   raw bytes. Empty on a non-Linux platform, where dumping is unsupported.
     # @example
     #   dump('ls', '-l', '-a')
     #   #=> []
     #   dump('spec/binary/twctf-2016-diary') { |c| c[0, 10] }
     #   #=> [" \x00\x00\x00\x00\x00\x00\x00\x15\x00"]
-    # @todo
-    #   +timeout+ option.
-    def dump(*args, limit: 1, &block)
+    def dump(*args, limit: 1, timeout: nil, &block)
       return [] unless SUPPORTED
 
       pid = fork { handle_child(*args) }
-      Handler.new(pid).handle(limit, &block)
+      Handler.new(pid).handle(limit, timeout: timeout, &block)
     end
 
-    # Do the tracer things.
+    # Traces a forked child, single-stepping it through its syscalls and capturing the seccomp
+    # filters it installs.
     class Handler
       # Instantiate a {Handler} object.
       # @param [Integer] pid
       #   The process id after fork.
       def initialize(pid)
+        @pids = [pid]
         Process.waitpid(pid)
         opt = Ptrace::O_TRACESYSGOOD | Ptrace::O_TRACECLONE | Ptrace::O_TRACEFORK | Ptrace::O_TRACEVFORK
         Ptrace.setoptions(pid, 0, opt)
@@ -62,46 +69,60 @@ module SeccompTools
       #
       # @param [Integer] limit
       #   Child will be killed when number of calling +prctl(SET_SECCOMP)+ reaches +limit+.
+      # @param [Float?] timeout
+      #   Kill the child processes when +timeout+ seconds have elapsed. +nil+ for no timeout.
       # @yieldparam [String] bpf
       #   Seccomp bpf in raw bytes.
       # @yieldparam [Symbol] arch
       #   Architecture. See {SeccompTools::Syscall::ABI} for supported architectures.
       # @return [Array<Object>, Array<String>]
-      #   Return the block returned. If block is not given, array of raw bytes will be returned.
-      def handle(limit, &block)
+      #   One entry per dumped filter: the block's return values when a block is given, otherwise
+      #   the raw bytes.
+      def handle(limit, timeout: nil, &block)
         collect = []
         syscalls = {} # record last syscall
-        loop while wait_syscall do |child|
-          if syscalls[child].nil? # invoke syscall
-            syscalls[child] = syscall(child)
-            next true
+        begin
+          Timeout.timeout(timeout) do
+            loop while wait_syscall do |child|
+              if syscalls[child].nil? # invoke syscall
+                syscalls[child] = syscall(child)
+                next true
+              end
+              # syscall finished
+              sys = syscalls[child]
+              syscalls[child] = nil
+              if sys.set_seccomp? && syscall(child).ret.zero? # consider successful call only
+                bpf = sys.dump_bpf
+                collect << (block.nil? ? bpf : yield(bpf, sys.arch))
+                limit -= 1
+              end
+              !limit.zero?
+            end
           end
-          # syscall finished
-          sys = syscalls[child]
-          syscalls[child] = nil
-          if sys.set_seccomp? && syscall(child).ret.zero? # consider successful call only
-            bpf = sys.dump_bpf
-            collect << (block.nil? ? bpf : yield(bpf, sys.arch))
-            limit -= 1
-          end
-          !limit.zero?
+        rescue Timeout::Error
+          # keep the filters dumped so far; fall through to kill the children
         end
-        syscalls.each_key { |cpid| Process.kill('KILL', cpid) if alive?(cpid) }
+        @pids.each { |cpid| Process.kill('KILL', cpid) if alive?(cpid) }
         Process.waitall
         collect
       end
 
       private
 
+      # Waits until a traced child enters or leaves a syscall, then resumes it.
+      #
       # @yieldparam [Integer] pid
+      #   Id of the child that stopped.
+      # @yieldreturn [Boolean]
+      #   Whether tracing should continue.
       # @return [Boolean]
       #   +true+ for continue,
-      #   +false+ for break.
+      #   +false+ for break. Also +false+ once no children are left.
       def wait_syscall
         child, status = Process.wait2
+        @pids << child unless @pids.include?(child)
         cont = true
-        # TODO: Test if clone / vfork works
-        if [Ptrace::EVENT_CLONE, Ptrace::EVENT_FORK, Ptrace::EVENT_VFORK].include?(status >> 16)
+        if [Ptrace::EVENT_CLONE, Ptrace::EVENT_FORK, Ptrace::EVENT_VFORK].include?(status.to_i >> 16)
           # New child launched!
           # newpid = SeccompTools::Ptrace.geteventmsg(child)
         elsif status.stopped? && status.stopsig & 0x80 != 0
@@ -113,11 +134,20 @@ module SeccompTools
         false
       end
 
+      # Reads the syscall the stopped child is currently invoking.
+      #
+      # @param [Integer] pid
+      #   Id of the stopped child.
       # @return [SeccompTools::Syscall]
       def syscall(pid)
         SeccompTools::Syscall.new(pid)
       end
 
+      # Is the process still running?
+      #
+      # @param [Integer] pid
+      #   Id of the process to be checked.
+      # @return [Boolean]
       def alive?(pid)
         Process.getpgid(pid)
         true
@@ -132,7 +162,7 @@ module SeccompTools
       def handle_child(*args)
         Ptrace.traceme_and_stop
         exec(*args)
-      rescue # rubocop:disable Style/RescueStandardError # exec fail
+      rescue # rubocop:disable Style/RescueStandardError
         Logger.error("Failed to execute #{args.join(' ')}")
         exit(1)
       end
@@ -149,10 +179,11 @@ module SeccompTools
     #   Number of filters to dump. Negative number for unlimited.
     # @yieldparam [String] bpf
     #   Seccomp bpf in raw bytes.
-    # @yieldparam [Symbol] arch
-    #   Architecture of the target process (always nil right now).
+    # @yieldparam [Symbol?] arch
+    #   Architecture of the target process, +nil+ when it cannot be determined.
+    #   See {SeccompTools::Util.process_arch}.
     # @return [Array<Object>, Array<String>]
-    #   Return the block returned. If block is not given, array of raw bytes will be returned.
+    #   Returns what the block returned. If a block is not given, an array of raw bytes will be returned.
     # @raise [Errno::ESRCH]
     #   Raises when the target process does not exist.
     # @raise [Errno::EPERM]
@@ -174,6 +205,7 @@ module SeccompTools
       return [] unless SUPPORTED
 
       collect = []
+      arch = Util.process_arch(pid)
       Ptrace.attach_and_wait(pid)
       begin
         i = 0
@@ -183,7 +215,7 @@ module SeccompTools
           rescue Errno::ENOENT, Errno::EINVAL
             break
           end
-          collect << (block.nil? ? bpf : yield(bpf, nil))
+          collect << (block.nil? ? bpf : yield(bpf, arch))
           i += 1
         end
       ensure

data/lib/seccomp-tools/emulator.rb

@@ -3,20 +3,21 @@
 require 'seccomp-tools/const'
 
 module SeccompTools
-  # For emulating seccomp.
+  # Runs a seccomp filter against a hypothetical syscall to find out which action it returns.
   class Emulator
     # Instantiate a {Emulator} object.
     #
     # All parameters except +instructions+ are optional. A warning is shown when uninitialized data is accessed.
     # @param [Array<Instruction::Base>] instructions
-    # @param [Integer] sys_nr
+    #   The filter to be emulated, as returned by +SeccompTools::Disasm.to_bpf(raw, arch).map(&:inst)+.
+    # @param [Integer?] sys_nr
     #   Syscall number.
     # @param [Array<Integer>] args
-    #   Syscall arguments
-    # @param [Integer] instruction_pointer
-    #   Program counter address when this syscall invoked.
+    #   Syscall arguments.
+    # @param [Integer?] instruction_pointer
+    #   Program counter address when this syscall is invoked.
     # @param [Symbol?] arch
-    #   System architecture is used when this parameter is not provided.
+    #   Defaults to the system architecture when not provided.
     #
     #   See {SeccompTools::Util.supported_archs} for list of supported architectures.
     def initialize(instructions, sys_nr: nil, args: [], instruction_pointer: nil, arch: nil)
@@ -24,16 +25,27 @@ module SeccompTools
       @sys_nr = sys_nr
       @args = args
       @ip = instruction_pointer
-      @arch = audit(arch || Util.system_arch)
+      arch ||= Util.system_arch
+      @arch = audit(arch)
+      # On a big-endian architecture the high 32-bit word of a 64-bit field comes first.
+      @big_endian = Const::Endian.big?(arch)
     end
 
     # Run emulation!
+    #
+    # Executes the filter until it returns, then reports the final machine state.
+    # @yieldparam [{Symbol, Integer => Integer}] values
+    #   If a block is given, it is invoked before each instruction with the current machine state.
     # @return [{Symbol, Integer => Integer}]
+    #   The final state: +:ret+ is the action the filter returned, +:pc+ the line it returned from,
+    #   +:a+ and +:x+ the registers, and Integer keys the scratch memory slots.
+    # @example
+    #   insts = SeccompTools::Disasm.to_bpf(raw, :amd64).map(&:inst)
+    #   SeccompTools::Emulator.new(insts, sys_nr: 0).run[:ret]
+    #   #=> 2147418112 # SECCOMP_RET_ALLOW
     def run
       @values = { pc: 0, a: 0, x: 0 }
       loop do
-        break if @values[:ret] # break when returned
-
         yield(@values) if block_given?
         inst = @instructions[pc]
         op, *args = inst.symbolize
@@ -46,6 +58,8 @@ module SeccompTools
         when :alu then alu(args[0], args[1]) # alu
         when :misc then misc(args[0]) # misc: txa/tax
         end
+        break if @values[:ret] # break when returned
+
         set(:pc, get(:pc) + 1) if %i[ld st alu misc].include?(op)
       end
       @values
@@ -98,9 +112,12 @@ module SeccompTools
 
     def alu(op, src)
       if op == :neg
-        set(:a, 2**32 - get(:a))
+        set(:a, (2**32) - get(:a))
       else
         src = get(:x) if src == :x
+        # Classic BPF aborts the whole program on division by zero.
+        return set(:ret, Const::BPF::ACTION[:KILL_THREAD]) if op == :/ && src.zero?
+
         set(:a, get(:a).__send__(op, src))
       end
     end
@@ -140,20 +157,28 @@ module SeccompTools
     end
 
     def data_of(index)
-      raise IndexError, "Invalid index: #{index}" unless (index & 3).zero? && index.between?(0, 63)
+      data = Const::BPF::SeccompData
+      raise IndexError, "Invalid index: #{index}" unless index.nobits?(3) && index.between?(0, data::SIZE - 1)
 
       index /= 4
       case index
-      when 0 then @sys_nr || undefined('sys_number')
-      when 1 then @arch || undefined('arch')
-      when 2 then @ip & 0xffffffff || undefined('instruction_pointer')
-      when 3 then @ip >> 32 || undefined('instruction_pointer')
+      when 0 then @sys_nr || undefined(data::NAMES[data::SYS_NUMBER])
+      when 1 then @arch || undefined(data::NAMES[data::ARCH])
+      when 2, 3 then word_of(@ip || undefined(data::NAMES[data::INSTRUCTION_POINTER]), index)
       else
         val = @args[(index - 4) / 2] || undefined("args[#{(index - 4) / 2}]")
-        (val >> (index.even? ? 0 : 32)) & 0xffffffff
+        word_of(val, index)
       end
     end
 
+    # The 32-bit word of the 64-bit value +val+ that lives at word-index +index+ of
+    # +seccomp_data+: the high word comes second on little-endian architectures but first on
+    # big-endian ones (s390x).
+    def word_of(val, index)
+      hi = index.odd? ^ @big_endian
+      (val >> (hi ? 32 : 0)) & 0xffffffff
+    end
+
     def undefined(var)
       raise format("Undefined Variable\n\t%04d: %s <- `%s` is undefined", pc, @instructions[pc].decompile, var)
     end

data/lib/seccomp-tools/error.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module SeccompTools
-  # Base error class.
+  # Base class of all errors raised by this library.
+  #
+  # Rescue this class to catch every assembler error at once.
   class Error < StandardError
   end
 
@@ -9,7 +11,7 @@ module SeccompTools
   class UnrecognizedTokenError < Error
   end
 
-  # Raised when a referred label is defined no where on compiling seccomp assembly.
+  # Raised when a referenced label is defined nowhere on compiling seccomp assembly.
   class UndefinedLabelError < Error
   end
 

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+require 'seccomp-tools/explain/path_facts'
+require 'seccomp-tools/explain/verdict'
+
+module SeccompTools
+  class Explain
+    # What a walk of one filter amounts to: the reachable returns, each one's facts read once, and
+    # the split into the architectures the filter distinguishes.
+    #
+    # Everything that reads a walk needs the same groundwork - {Summary} to render a per-architecture
+    # policy, {Audit} to assess each architecture's reachable syscalls - so it is derived here once
+    # rather than in each of them.
+    class Analysis
+      # @param [Array<Symbolic::Executor::Leaf>] leaves
+      def initialize(leaves)
+        @leaves = leaves
+        @facts = Hash.new { |h, leaf| h[leaf] = PathFacts.new(leaf.path) }
+      end
+
+      # The {PathFacts} of +leaf+, computed once and shared across all consumers.
+      # @param [Symbolic::Executor::Leaf] leaf
+      # @return [PathFacts]
+      def facts(leaf)
+        @facts[leaf]
+      end
+
+      # The distinct architecture values (+AUDIT_ARCH_*+) the filter explicitly branches on.
+      # @return [Array<Integer>]
+      def arch_values
+        @arch_values ||= @leaves.filter_map { |l| facts(l).arch_eq }.uniq
+      end
+
+      # One entry per architecture section: its +AUDIT_ARCH+ value (+nil+ when the filter never
+      # branches on +arch+), the architecture symbol whose syscall names apply (+nil+ when the checked
+      # value is not one seccomp-tools knows), a display title, and the leaves reachable on it.
+      # @param [Symbol] declared_arch
+      #   The architecture assumed when the filter itself does not branch on +arch+.
+      # @return [Array<Array(Integer?, Symbol?, Object, Array<Symbolic::Executor::Leaf>)>]
+      def sections(declared_arch)
+        vals = arch_values
+        return [[nil, declared_arch, declared_arch, @leaves]] if vals.empty?
+
+        vals.map do |v|
+          sym = Const::Audit.arch_symbol(v)
+          [v, sym, sym || format('0x%x (unknown)', v), @leaves.select { |l| facts(l).arch_consistent?(v) }]
+        end
+      end
+
+      # Leaves reachable when +arch+ is none of the explicitly-checked values.
+      # @return [Array<Symbolic::Executor::Leaf>]
+      def other_leaves
+        @leaves.reject { |l| facts(l).arch_eq }
+      end
+
+      # The catch-all action of +leaves+: the verdict of a leaf that matches no syscall, no range and
+      # no arguments (or the first leaf, if none is a pure catch-all), or +nil+ when +leaves+ is empty.
+      # @param [Array<Symbolic::Executor::Leaf>] leaves
+      # @return [String?]
+      def default_label(leaves)
+        catch_all = leaves.find { |l| facts(l).catch_all? }
+        (catch_all || leaves.first)&.then { |l| Verdict.label(l.ret) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/const'
+require 'seccomp-tools/symbolic/constraint'
+
+module SeccompTools
+  class Explain
+    # The seccomp reading of one leaf's path condition: which syscall number it pins or bounds,
+    # which architecture value it pins, and which facts remain for the rule's +when+ clause. The
+    # path is immutable, so every query is derived once, eagerly.
+    class PathFacts
+      SYS = Const::BPF::SeccompData::SYS_NUMBER
+      ARCH = Const::BPF::SeccompData::ARCH
+      # Largest 32-bit value, the upper end of an unconstrained syscall-number range.
+      U32_MAX = 0xffffffff
+
+      # The syscall number the path pins with +==+, or +nil+.
+      # @return [Integer?]
+      attr_reader :sys_eq
+      # The architecture value the path pins with +==+, or +nil+.
+      # @return [Integer?]
+      attr_reader :arch_eq
+      # The +[lo, hi]+ range (inclusive; +hi+ is +nil+ when unbounded) all bound facts restrict the
+      # syscall number to, or +nil+ when there is no lower bound. An upper bound alone does not
+      # make a range rule: it is the complement of one (e.g. the +sys < 0x40000000+ side of an x32
+      # guard) and reads naturally as part of the default bucket.
+      # @return [Array(Integer, Integer?)?]
+      attr_reader :sys_range
+      # Constraints not already conveyed by the syscall-number / architecture presentation.
+      #
+      # Consumed (dropped): +==+, +!=+ and range facts on +sys_number+ - the named/ranged buckets
+      # and the "any other syscall" default wording express them; +==+/+!=+ facts on +arch+ - the
+      # per-architecture sections and the "any other" fall-through express them; and any non-+==+
+      # fact on a word that some +==+ on the same path already pins (it is then redundant - a
+      # contradicting combination would have been pruned as infeasible).
+      #
+      # Everything else is kept so a kernel-valid check is never silently dropped: bit-tests on an
+      # unpinned +sys_number+ (e.g. an odd/even dispatch), bit-tests or ranges on +arch+ (e.g.
+      # testing the +__AUDIT_ARCH_64BIT+ flag instead of pinning one value), and any comparison
+      # against a register rather than a constant.
+      # @return [Array<Symbolic::Constraint>]
+      attr_reader :residual
+
+      # @param [Array<Symbolic::Constraint>] path
+      def initialize(path)
+        @path = path
+        @sys_eq = eq(SYS)
+        @arch_eq = eq(ARCH)
+        @sys_range = compute_sys_range
+        @residual = compute_residual
+      end
+
+      # Is the path consistent with the architecture being +val+? Every constant arch fact is
+      # evaluated against +val+.
+      # @param [Integer] val
+      # @return [Boolean]
+      def arch_consistent?(val)
+        @path.all? do |c|
+          next true unless c.plain_data_fact?(ARCH)
+
+          Symbolic::Constraint.evaluate(val, c.op, c.rhs.val)
+        end
+      end
+
+      # Does the path match no syscall, no range, and no arguments - i.e. describe the filter's
+      # catch-all behavior?
+      # @return [Boolean]
+      def catch_all?
+        sys_eq.nil? && sys_range.nil? && residual.empty?
+      end
+
+      private
+
+      # The value of the single +data[offset] == k+ fact, if any.
+      def eq(offset)
+        @path.find { |c| c.plain_data_eq?(offset) }&.rhs&.val
+      end
+
+      def compute_sys_range
+        lo = nil
+        hi = nil
+        @path.each do |c|
+          next unless c.plain_data_fact?(SYS)
+
+          case c.op
+          when :> then lo = [lo || 0, c.rhs.val + 1].max
+          when :>= then lo = [lo || 0, c.rhs.val].max
+          when :< then hi = [hi || U32_MAX, c.rhs.val - 1].min
+          when :<= then hi = [hi || U32_MAX, c.rhs.val].min
+          end
+        end
+        lo && [lo, hi]
+      end
+
+      def compute_residual
+        pinned = @path.filter_map { |c| c.lhs.offset if c.plain_data_eq? }
+        @path.reject do |c|
+          next false unless c.plain_data_fact?
+
+          redundant = c.op != :== && pinned.include?(c.lhs.offset)
+          case c.lhs.offset
+          when SYS then redundant || !%i[set unset].include?(c.op)
+          when ARCH then redundant || %i[== !=].include?(c.op)
+          else redundant
+          end
+        end.uniq(&:key)
+      end
+    end
+  end
+end