one_gadget 1.10.0 → 2.1.0

data/lib/one_gadget/emulators/mips.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require 'one_gadget/abi'
+require 'one_gadget/emulators/instruction'
+require 'one_gadget/emulators/processor'
+
+module OneGadget
+  module Emulators
+    # Emulator of MIPS (32-bit, o32).
+    class Mips < Processor
+      # Instantiate a {Mips} object.
+      def initialize
+        super(OneGadget::ABI.mips, 'sp')
+        @registers['zero'] = 0 # hardwired
+        @pc = 'pc'
+      end
+
+      # This arch compares and branches in one instruction -- there is no flag
+      # register -- so each mnemonic names the relation its operands must stand in
+      # for the branch to be taken. The spellings against zero name one operand;
+      # +zero+ is the other, and reads as the +0x0+ it holds.
+      # @return [Hash{String => Symbol}]
+      COND = {
+        'beq' => :eq, 'bne' => :ne,
+        'beqz' => :eq, 'bnez' => :ne,
+        'blez' => :sle, 'bgtz' => :sgt, 'bltz' => :slt, 'bgez' => :sge
+      }.freeze
+
+      # The data-processing instructions, mapped to the Ruby operator that folds
+      # them. An immediate form differs from its register one only in how the right
+      # operand is written, which the operand reader already handles, so both name
+      # the same operator. Arithmetic shift right is absent: a value is held masked
+      # to its width, where +>>+ is the logical shift.
+      DATA_OPS = {
+        'and' => :&, 'andi' => :&,
+        'or' => :|, 'ori' => :|,
+        'xor' => :^, 'xori' => :^,
+        'sll' => :<<, 'srl' => :>>
+      }.freeze
+      private_constant :DATA_OPS
+
+      # The loads, mapped to how many bytes each reads.
+      LOADS = { 'lw' => 4, 'lh' => 2, 'lhu' => 2, 'lb' => 1, 'lbu' => 1 }.freeze
+      private_constant :LOADS
+
+      # The stores, mapped to how many bytes each writes.
+      STORES = { 'sw' => 4, 'sh' => 2, 'sb' => 1 }.freeze
+      private_constant :STORES
+
+      # Supported instruction set. Anything not listed aborts the candidate.
+      # @return [Array<Instruction>] The supported instructions.
+      def instructions
+        [
+          Instruction.new('addiu', 3),
+          Instruction.new('addu', 3),
+          Instruction.new('bal', 1),
+          Instruction.new('jal', 1),
+          Instruction.new('jalr', 1..2),
+          Instruction.new('li', 2),
+          Instruction.new('lui', 2),
+          Instruction.new('move', 2),
+          Instruction.new('nop', 0),
+          Instruction.new('subu', 3)
+        ] + (LOADS.keys + STORES.keys).map { |mnem| Instruction.new(mnem, 2) } +
+          DATA_OPS.keys.map { |mnem| Instruction.new(mnem, 3) }
+      end
+
+      # The value of a call's +idx+-th argument. o32 states the first four in
+      # registers, and reserves a stack slot for every argument including those --
+      # so an argument's slot is its index however it is passed, and the ones past
+      # the registers are read from there.
+      # @param [Integer] idx The 0-based index of the argument.
+      # @return [Lambda, Integer]
+      def argument(idx)
+        return registers["a#{idx}"] if idx < ARG_REGISTERS
+
+        top = registers['sp'].evaluate('sp' => 0)
+        sp_based_stack[top + (idx * size_t)]
+      end
+
+      # Emulate one instruction, holding back any transfer of control.
+      #
+      # This arch delays every transfer by one instruction: whatever follows a
+      # branch or a call runs *before* it takes effect. So a transfer is held back
+      # here and applied once that instruction has run, which is the order they
+      # really happen in -- and it leaves both addresses of the pair meaning what
+      # they say, since entering at the transfer runs both, while entering at the
+      # instruction after it runs only that one.
+      # @param [String] cmd One line from result of objdump.
+      # @return [Boolean] If successfully processed.
+      # @see OneGadget::Emulators::X86#process!
+      def process!(cmd)
+        resolve_pending_branch(cmd)
+        @cur_addr = cmd[/\A\s*([0-9a-f]+):/, 1]&.to_i(16)
+
+        @got_value = cmd[GOT_VALUE, 1]&.to_i(16)
+
+        mnem = mnemonic(cmd)
+        if transfer?(mnem)
+          @delayed = [mnem, cmd]
+          return true
+        end
+
+        dispatch(cmd) && apply_delayed
+      end
+
+      # How many arguments this ABI states in registers.
+      ARG_REGISTERS = 4
+      private_constant :ARG_REGISTERS
+
+      private
+
+      # What a GOT slot holds, stated beside the load by
+      # +OneGadget::Fetchers::Mips+ because this architecture reaches its globals
+      # through that table rather than through the instruction's own address.
+      GOT_VALUE = /#\s*([0-9a-f]+)\s*\z/
+      private_constant :GOT_VALUE
+
+      # The calls, which are delayed exactly as the branches are.
+      CALLS = %w[jal jalr bal].freeze
+      private_constant :CALLS
+
+      def branch_mnem?(mnem) = mnem == 'b' || COND.key?(mnem)
+
+      # Whether +mnem+ transfers control, and so takes effect one instruction late.
+      def transfer?(mnem) = branch_mnem?(mnem) || CALLS.include?(mnem)
+
+      def dispatch(cmd)
+        inst, args = parse(cmd)
+        __send__(inst.handler, *args) != :fail
+      end
+
+      # Carry out the transfer held back from the previous instruction, now that
+      # the instruction it delays behind has run.
+      # @return [Boolean]
+      def apply_delayed
+        return true if @delayed.nil?
+
+        mnem, cmd = @delayed
+        @delayed = nil
+        return handle_branch(mnem, cmd) != :fail if branch_mnem?(mnem)
+
+        dispatch(cmd)
+      end
+
+      # Operands of +cmd+ (mnemonic dropped), each stripped of a trailing +<symbol>+.
+      def operands(cmd)
+        cmd.sub(/\A[0-9a-f]+:\s*\S+\s*/, '').split(',').map { |o| o.strip.sub(/\s*<.*>\z/, '') }
+      end
+
+      # Record the comparison and decide the branch together, since one
+      # instruction is both (see {COND}).
+      def handle_branch(mnem, cmd)
+        return true if mnem == 'b' # unconditional: control handled by the stitched path
+
+        ops = operands(cmd)
+        lhs, rhs = mnem.end_with?('z') ? [ops[0], 'zero'] : ops[0..1]
+        record_compare(:sub, operand_str(lhs), operand_str(rhs))
+        branch_on_compare(COND[mnem], ops.last.to_i(16))
+      end
+
+      # A call: record the terminal +exec*+ target, accept a known-safe libc call,
+      # or +:fail+ to abort the candidate. This arch reaches most of libc through a
+      # register, so the name comes from what the fetcher wrote beside it
+      # (+OneGadget::Fetchers::Mips+); a call it could not name is one the emulator
+      # cannot reason about either, which {Processor#dispatch_safe_call} refuses.
+      # @param [String] addr The call target, as the line names it.
+      # @return [nil, :fail]
+      def call_target(addr)
+        return reach_terminal_call(addr) if terminal_call?(addr)
+
+        dispatch_safe_call(addr)
+      end
+
+      # +jalr+ takes the register holding the target, optionally preceded by the
+      # register the return address goes to; the target is the last either way.
+      def inst_jalr(*args) = call_target(args.last)
+
+      # A direct call, which states its target outright.
+      def inst_jal(addr) = call_target(addr)
+
+      # +bal+ is the pc-relative direct call; it names its target as +jal+ does.
+      def inst_bal(addr) = call_target(addr)
+
+      def inst_nop = true
+
+      def inst_move(dst, src)
+        check_register!(dst)
+
+        registers[dst] = arg_to_lambda(src)
+      end
+
+      # +li+ is the assembler's spelling of loading a constant, whatever the
+      # instructions it expands to.
+      def inst_li(dst, imm)
+        check_register!(dst)
+
+        registers[dst] = Integer(imm)
+      end
+
+      # +lui dst, imm+ loads the immediate into the upper half of the register.
+      def inst_lui(dst, imm)
+        check_register!(dst)
+
+        registers[dst] = (imm.to_i(16) << 16) & width_mask
+      end
+
+      # +addu dst, src, op2+; +addiu+ differs only in that its right operand is
+      # written as a literal. Neither traps on overflow, which is why the compiler
+      # uses them for address arithmetic and the trapping forms are not modelled.
+      def inst_addu(dst, src, op2) = arith(:+, dst, src, op2)
+      alias inst_addiu inst_addu
+
+      # +subu dst, src, op2+. See {#inst_addu}.
+      def inst_subu(dst, src, op2) = arith(:-, dst, src, op2)
+
+      # Each data-processing mnemonic handled the one way, since they differ only
+      # in the operator applied.
+      DATA_OPS.each do |mnem, op|
+        define_method(Instruction.handler_name(mnem)) do |dst, src, op2|
+          data_op(op, dst, src, op2, name: mnem)
+        end
+      end
+
+      LOADS.each do |mnem, size|
+        define_method(Instruction.handler_name(mnem)) { |dst, mem| load_value(dst, mem, size) }
+      end
+
+      STORES.each do |mnem, size|
+        define_method(Instruction.handler_name(mnem)) { |src, mem| store_value(src, mem, size) }
+      end
+
+      # A load. The address is read like any other, so what the caller has to
+      # arrange about it is recorded the same way. A load narrower than a register
+      # only takes part of the word this emulator tracks, which is not a value it
+      # can name, so the register then holds what a call would have left.
+      # @param [String] dst The destination register.
+      # @param [String] mem The memory operand, as written.
+      # @param [Integer] size How many bytes the load reads.
+      # @return [void]
+      def load_value(dst, mem, size)
+        check_register!(dst)
+        # a GOT slot holds an address, and the file says which
+        return registers[dst] = libc_base + @got_value if @got_value && size == size_t
+
+        value = read_value(arg_to_lambda(mem_operand(mem)))
+        registers[dst] = size == size_t ? value : clobbered_value
+      end
+
+      # A store, tracked so a later load of the same slot reads it back, and
+      # requiring its target writable ({Processor#track_write}). A store narrower
+      # than a register leaves the rest of the slot as it was, so what the slot
+      # then holds is named as unknown rather than as the value stored.
+      # @param [String] src The register holding the value stored.
+      # @param [String] mem The memory operand, as written.
+      # @param [Integer] size How many bytes the store writes.
+      # @return [void]
+      def store_value(src, mem, size)
+        check_register!(src)
+
+        dst_l = arg_to_lambda(mem_operand(mem)).ref!
+        track_write(dst_l, size == size_t ? registers[src] : clobbered_value)
+      end
+
+      # This arch writes a memory operand as an offset applied to one register,
+      # which the {Lambda} parser reads in its bracketed form. The offset is
+      # decimal, as objdump prints it.
+      # @param [String] mem The operand, as written.
+      # @return [String]
+      # @example
+      #   mem_operand('-31652(gp)') #=> '[gp-31652]'
+      #   mem_operand('4(s6)')      #=> '[s6+4]'
+      def mem_operand(mem)
+        m = mem.match(/\A(-?\d+)\((\w+)\)\z/)
+        raise_unsupported('memory operand', mem) if m.nil?
+
+        "[#{m[2]}#{format('%+d', Integer(m[1]))}]"
+      end
+
+      class << self
+        # o32 is 32-bit.
+        # @return [Integer]
+        def bits
+          32
+        end
+      end
+    end
+  end
+end

data/lib/one_gadget/emulators/processor.rb

@@ -1,17 +1,39 @@
 # frozen_string_literal: true
 
+require 'one_gadget/abi'
+require 'one_gadget/emulators/conditional'
+require 'one_gadget/emulators/constraints'
+require 'one_gadget/emulators/data_processing'
 require 'one_gadget/emulators/lambda'
+require 'one_gadget/emulators/register_file'
+require 'one_gadget/emulators/safe_calls'
+require 'one_gadget/emulators/tracked_memory'
 require 'one_gadget/error'
 
 module OneGadget
   # Instruction emulator to solve the constraint of gadgets.
   module Emulators
-    # Base class of a processor.
+    # Base of the per-architecture instruction emulators, used to symbolically
+    # execute a candidate and solve its constraints. A subclass implements the
+    # arch's supported instructions, calling convention and stack model; what it
+    # inherits here is the emulation lifecycle (parse, dispatch, and the calls a
+    # candidate may cross) plus four architecture-independent concerns kept in
+    # modules of their own: {Conditional} for the branch/compare machinery,
+    # {Constraints} for what a gadget requires of its caller, {TrackedMemory} for
+    # the memory a candidate reads and writes, and {DataProcessing} for what an
+    # instruction leaves in a register.
+    #
+    # To add an architecture, see +docs/adding-an-architecture.md+.
     class Processor
-      attr_reader :registers # @return [Hash{String => OneGadget::Emulators::Lambda}] The current registers' state.
-      attr_reader :sp_based_stack # @return [Hash{Integer => OneGadget::Emulators::Lambda}] Stack content based on sp.
+      include Conditional
+      include Constraints
+      include DataProcessing
+      include TrackedMemory
+
+      attr_reader :registers # @return [RegisterFile] The current registers' state.
       attr_reader :sp # @return [String] Stack pointer.
       attr_reader :pc # @return [String] Program counter.
+      attr_reader :bp # @return [String, nil] Frame pointer, or nil when this arch tracks none.
 
       # Instantiate a {Processor} object.
       # @param [Array<String>] registers
@@ -19,15 +41,42 @@ module OneGadget
       # @param [String] sp
       #   The stack register.
       def initialize(registers, sp)
-        @registers = registers.to_h { |reg| [reg, to_lambda(reg)] }
+        @registers = RegisterFile.build(registers, OneGadget::ABI::NARROW_VIEWS.fetch(arch_name, {})) do |reg|
+          to_lambda(reg)
+        end
         @sp = sp
         @constraints = []
-        @sp_based_stack = Hash.new do |h, k|
-          h[k] = OneGadget::Emulators::Lambda.new(sp).tap do |lmda|
-            lmda.immi = k
-            lmda.deref!
-          end
-        end
+        @deferred_reads = [] # pointer args of safe calls, resolved once emulation ends
+        @closed_fds = []     # where each descriptor closed before the terminal call comes from
+        @flags = nil     # last compare, for a following conditional branch
+        @pending = nil   # a conditional branch awaiting one-line-ahead resolution
+      end
+
+      # Function names whose call ends a gadget: the real +exec*+ entry points.
+      # Deliberately excludes the +posix_spawn+ setup helpers
+      # (+posix_spawnattr_*+, +posix_spawn_file_actions_*+), which merely share the
+      # +posix_spawn+ prefix.
+      # @example matches +posix_spawn+, +execve+, +execveat+, +execlp+; not +posix_spawnattr_init+
+      TERMINAL_CALL_RE = /\A(?:posix_spawnp?|exec(?:ve|l|v)[a-z]*)\z/
+
+      # Whether +addr+ calls a terminal +exec*+ entry point (see
+      # {#reach_terminal_call}). Matches the resolved symbol name exactly so a
+      # setup helper isn't mistaken for the call it precedes.
+      # @param [String] addr The call target, e.g. +"10c7d0 <posix_spawn@@GLIBC_2.15>"+.
+      # @return [Boolean]
+      def terminal_call?(addr)
+        name = addr[/<([^@>]+)/, 1]
+        !name.nil? && TERMINAL_CALL_RE.match?(name)
+      end
+
+      # Record a reached terminal +exec*+ call as the gadget's effect and stop
+      # emulating: it is the gadget's goal, and any following instruction would
+      # clobber the argument registers that {OneGadget::Fetchers::ArgumentResolution#resolve} reads to describe it.
+      # @param [String] addr The call target.
+      # @return [Symbol] +:fail+, the sentinel {#process!} maps to "stop".
+      def reach_terminal_call(addr)
+        registers[pc] = addr
+        :fail
       end
 
       # Parse one command into instruction and arguments.
@@ -35,10 +84,41 @@ module OneGadget
       # @return [(Instruction, Array<String>)]
       #   The parsing result.
       def parse(cmd)
-        inst = instructions.find { |i| i.match?(cmd) }
-        raise Error::UnsupportedInstructionError, "Not implemented instruction in #{cmd}" if inst.nil?
+        self.class.line_memo(:parse)[cmd] ||= begin
+          list, index = self.class.instruction_table { instructions }
+          mnem = cmd[/\A[0-9a-f]+:\s*(\S+)/, 1] || cmd[/\A\s*(\S+)/, 1]
+          inst = index[mnem]
+          # Fall back to the original scan for any mnemonic that isn't a bare word.
+          inst ||= list.find { |i| i.match?(cmd) }
+          raise Error::UnsupportedInstructionError, "Not implemented instruction in #{cmd}" if inst.nil?
 
-        [inst, inst.fetch_args(cmd)]
+          [inst, inst.fetch_args(cmd)]
+        end
+      end
+
+      class << self
+        # What a line always reads as, remembered per architecture and +kind+ of
+        # reading: a candidate is emulated once for every window it yields, so the
+        # same line is read thousands of times, and nothing about how it reads
+        # depends on the state the emulator holds.
+        # @param [Symbol] kind
+        # @return [Hash]
+        def line_memo(kind)
+          (@line_memo ||= Hash.new { |memo, k| memo[k] = {} })[kind]
+        end
+
+        # The architecture's supported instructions, and the same set indexed by
+        # mnemonic, built on first use and shared by every emulator of that
+        # architecture: the set is fixed, while an emulator is made for each of the
+        # thousands of windows a candidate yields.
+        # @yieldreturn [Array<Instruction>] The table, asked for only on first use.
+        # @return [(Array<Instruction>, Hash{String => Instruction})]
+        def instruction_table
+          @instruction_table ||= begin
+            list = yield
+            [list, list.each_with_object({}) { |i, h| h[i.inst] ||= i }]
+          end
+        end
       end
 
       # Process one command, without raising any exceptions.
@@ -48,10 +128,20 @@ module OneGadget
       def process(cmd)
         process!(cmd)
       # rescue OneGadget::Error::UnsupportedError => e; p e # for debugging
+      rescue OneGadget::Error::UnsupportedInstructionError
+        @refused_line = cmd
+        false
       rescue OneGadget::Error::Error
         false
       end
 
+      # The line this emulator could not run at all: an instruction outside
+      # {#instructions}. Only what {#parse} reads decides that -- the mnemonic and
+      # the operands, never the state the emulator holds -- so the same line stops
+      # every emulation that reaches it.
+      # @return [String, nil]
+      attr_reader :refused_line
+
       # Method need to be implemented in inheritors.
       #
       # Process one command.
@@ -78,45 +168,99 @@ module OneGadget
       def argument(_idx); raise NotImplementedError
       end
 
-      # @return [Array<String>]
-      #   Extra constraints found during execution.
-      def constraints
-        return [] if @constraints.empty?
-
-        # we have these types:
-        # * :writable
-        # * :raw
-        cons = @constraints.uniq do |type, obj|
-          next obj unless type == :writable
-
-          obj.deref_count.zero? ? obj.obj.to_s : obj.to_s
-        end
-        cons.map { |type, obj| type == :writable ? "writable: #{obj}" : obj }.sort
-      end
-
-      # Method need to be implemented in inheritors.
-      #
-      # @param [String | Lambda] obj
-      #  A lambda object or its string.
-      # @return [Hash{Integer => Lambda}, nil]
-      #  The corresponding stack that +obj+ used,
-      #  or nil if +obj+ doesn't use the stack.
-      def get_corresponding_stack(obj); raise NotImplementedError
-      end
-
       private
 
       def check_register!(reg)
         raise Error::InstructionArgumentError, "#{reg.inspect} is not a valid register" unless register?(reg)
       end
 
+      # Whether the +idx+-th argument meets +expect+, a requirement a catalogued
+      # call states about it that is not about the pointer being mapped (those go
+      # through {#record_pointer}). See {SafeCalls}.
       def check_argument(idx, expect)
         case expect
         when :global_var? then global_var?(argument(idx))
-        when :zero? then argument(idx).is_a?(Integer) && argument(idx).zero?
         end
       end
 
+      # Accept a +call+ to a libc function the emulator treats as non-terminal (a
+      # syscall wrapper), applying whatever {SafeCalls::COMMON} records about its
+      # arguments. Both deref requirements are deferred to
+      # {#finalize_deferred_reads}, because a +<reg>+<imm>+ pointer may only become
+      # known-mapped once a later store marks +<reg>+ writable.
+      # @param [String] addr The call target, as objdump names it.
+      # @return [nil, :fail] +nil+ = call accepted, +:fail+ = abort the candidate.
+      def dispatch_safe_call(addr)
+        func = SafeCalls::COMMON.keys.find { |n| addr.include?(n) }
+        return :fail unless func
+
+        SafeCalls::COMMON[func].each do |idx, req|
+          next note_closed_fd(argument(idx)) if req == :closed_fd
+
+          ok = POINTER_REQUIREMENTS.include?(req) ? record_pointer(argument(idx), req) : check_argument(idx, req)
+          return :fail unless ok
+        end
+        clobber_caller_saved
+        nil
+      end
+
+      # Forget the caller-saved registers, setting the return register to zero
+      # rather than forgetting it (see {OneGadget::ABI::CALLER_SAVED}).
+      # @return [void]
+      # @example A later branch on the result resolves, rather than reading as a
+      #   condition on a value the caller chooses.
+      #   process('e6570: call 94180 <__close>')
+      #   registers['rax'] #=> 0
+      #   registers['rcx'] #=> $clobbered
+      def clobber_caller_saved
+        caller_saved.each do |reg|
+          next unless registers.key?(reg)
+
+          # A vector register holds one value per lane; keep that shape.
+          current = registers[reg]
+          registers[reg] = current.is_a?(Array) ? Array.new(current.size) { clobbered_value } : clobbered_value
+        end
+        reg = return_register
+        registers[reg] = 0 if reg && registers.key?(reg)
+      end
+
+      # The register this architecture's calling convention returns a value in.
+      def return_register
+        OneGadget::ABI::RETURN_REGISTER[arch_name]
+      end
+
+      # Registers this architecture's calling convention lets a call destroy.
+      def caller_saved
+        @caller_saved ||= OneGadget::ABI::CALLER_SAVED.fetch(arch_name, [])
+      end
+
+      def arch_name
+        self.class.name.split('::').last.downcase.to_sym
+      end
+
+      # Stands for a value left by a call: unknowable, and not the caller's to pick.
+      def clobbered_value
+        OneGadget::Emulators::Lambda.new(CLOBBERED)
+      end
+
+      # Whether +value+ is one a call left behind. Nothing can be said about it, so
+      # reading one as a constraint operand abandons the path (see
+      # {Conditional#operand_str}).
+      def clobbered?(value)
+        return value.any? { |v| clobbered?(v) } if value.is_a?(Array)
+
+        value.is_a?(OneGadget::Emulators::Lambda) && value.obj == CLOBBERED
+      end
+
+      # The libc load base as a symbolic +$base+ lambda. Only the arches that
+      # concretize libc-relative operands (amd64's +rip+, arm's +pc+) ever produce
+      # it; elsewhere it never matches a real operand, so it's harmless.
+      # @example
+      #   libc_base.to_s #=> '$base'
+      def libc_base
+        @libc_base ||= OneGadget::Emulators::Lambda.new('$base')
+      end
+
       def register?(reg)
         registers.include?(reg)
       end
@@ -137,14 +281,13 @@ module OneGadget
         raise OneGadget::Error::UnsupportedInstructionArgumentError, "#{inst} #{args.join(', ')}"
       end
 
-      def eval_dict
-        { sp => 0 }
-      end
-
       def size_t
         self.class.bits / 8
       end
 
+      # Whether +obj+ is reached through the program counter, which is what a
+      # libc global looks like once resolved -- as opposed to a value the caller
+      # supplies.
       def global_var?(obj)
         obj.to_s.include?(pc)
       end