one_gadget 2.0.0 → 2.1.1

data/lib/one_gadget/emulators/constraints.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require 'one_gadget/emulators/conditional'
+require 'one_gadget/emulators/lambda'
+
+module OneGadget
+  module Emulators
+    # What a candidate requires of its caller, collected while it is emulated and
+    # rendered once it ends. A path that dereferences a pointer, stores through an
+    # address, or reaches a call that reads one records the requirement here rather
+    # than assuming it holds; {#constraints} then drops the ones another already
+    # implies and names what is left. Mixed into {Processor}.
+    module Constraints
+      # Marks a register holding whatever a call returned or left behind; see
+      # {Processor#clobber_caller_saved}.
+      CLOBBERED = '$clobbered'
+
+      # Constraint types whose payload is an address {Lambda} asserting the target
+      # is mapped -- +:writable+ (a store target) and +:readable+ (an unconditional
+      # dereference, see {#finalize_deferred_reads}). Both are keyed, offset-
+      # normalised, and imply non-NULL identically; they differ only in how they
+      # render (see {#render_constraint}). The remaining type, +:raw+, carries a
+      # ready-made constraint string that keys on itself, and +:cmp+ a comparison
+      # recorded as its +[lhs, operator, rhs]+ parts (see {Conditional}), so it can
+      # be inspected rather than re-parsed from the rendered text.
+      ADDRESS_TYPES = %i[writable readable].freeze
+
+      # {SafeCalls} requirements naming what a callee does with a pointer argument,
+      # each recorded as something the caller must arrange (see {#record_pointer}),
+      # as opposed to a precondition read off the value as it stands.
+      POINTER_REQUIREMENTS = %i[writable deref nullable_deref null].freeze
+
+      # The {POINTER_REQUIREMENTS} a NULL argument already satisfies: both ask for
+      # a pointer the callee will leave alone, and NULL is how that is asked for.
+      NULLABLE_REQUIREMENTS = %i[nullable_deref null].freeze
+
+      # @return [Array<String>] Where each descriptor this candidate closes is read
+      #   from, in the order they are closed, without repeats.
+      def closed_fds
+        @closed_fds.uniq
+      end
+
+      # @return [Array<String>]
+      #   Extra constraints found during execution.
+      def constraints
+        finalize_deferred_reads
+        return [] if @constraints.empty?
+
+        # An address constraint is keyed by its base register (deref-0) or full
+        # expression (compound); several through one base (e.g. stores at reg+0x0
+        # and reg+0x8) impose the same requirement, so keep just the smallest
+        # offset (sort ascending, then uniq keeps that first).
+        cons = @constraints.sort_by { |type, obj| address_deref0?(type, obj) ? obj.immi : 0 }
+                           .uniq { |type, obj| constraint_key(type, obj) }
+        cons = drop_restated_null(drop_implied_nonzero(cons))
+        cons.map { |type, obj| render_constraint(type, obj) }.sort
+      end
+
+      # Whether +(type, obj)+ is an address constraint on a bare (deref-0) target,
+      # i.e. one carrying a base register and offset to normalise.
+      # @param [Symbol] type The constraint's type.
+      # @param [Object] obj Its payload.
+      # @return [Boolean]
+      def address_deref0?(type, obj)
+        ADDRESS_TYPES.include?(type) && obj.deref_count.zero?
+      end
+
+      # De-duplication key: an address constraint collapses per (type, base) so
+      # constraints of different types on the same register stay distinct; a raw
+      # constraint keys on its own text.
+      # @param [Symbol] type The constraint's type.
+      # @param [Object] obj Its payload.
+      # @return [Object] Equal for two constraints that impose the same requirement.
+      def constraint_key(type, obj)
+        return obj unless ADDRESS_TYPES.include?(type)
+
+        [type, obj.deref_count.zero? ? obj.obj.to_s : obj.to_s]
+      end
+
+      # Render a constraint to its output string.
+      # @param [Symbol] type The constraint's type.
+      # @param [Object] obj Its payload.
+      # @return [String] The constraint as reported.
+      def render_constraint(type, obj)
+        case type
+        when :writable then "writable: #{obj}"
+        when :readable then "readable: #{obj}"
+        when :cmp then obj.join(' ')
+        else obj
+        end
+      end
+
+      # Drop a "<reg> != 0x0" branch constraint that another constraint already
+      # implies: an address constraint (+writable: <reg>+imm+ store target, or
+      # +readable: <reg>+) forces <reg> to be a valid (mapped, non-NULL) pointer,
+      # so a NULL-check branch on the same register adds nothing. Keeps the
+      # emitted set minimal.
+      # @param [Array<[Symbol, Object]>] cons The de-duplicated constraint list.
+      # @return [Array<[Symbol, Object]>]
+      def drop_implied_nonzero(cons)
+        nonzero_regs = cons.filter_map do |type, obj|
+          obj.obj.to_s if address_deref0?(type, obj)
+        end
+        return cons if nonzero_regs.empty?
+
+        cons.reject do |type, obj|
+          type == :cmp && obj[1] == '!=' && obj[2] == Conditional::ZERO && nonzero_regs.include?(obj[0])
+        end
+      end
+
+      # Drop a "<X> == 0x0" branch constraint that a NULL requirement on the same
+      # value already states (see {#require_null}). Both ask for the same zero, and
+      # the one naming it NULL is the one that says what the zero is for.
+      # @param [Array<[Symbol, Object]>] cons The de-duplicated constraint list.
+      # @return [Array<[Symbol, Object]>]
+      def drop_restated_null(cons)
+        nulls = cons.filter_map { |type, obj| obj[/\A(.+) == NULL\z/, 1] if type == :raw }
+        return cons if nulls.empty?
+
+        cons.reject do |type, obj|
+          type == :cmp && obj[1] == '==' && obj[2] == Conditional::ZERO && nulls.include?(obj[0])
+        end
+      end
+
+      private
+
+      # Record a descriptor the gadget closes on its way to the terminal call, by
+      # where it is read from. Which descriptor lands there decides whether the
+      # spawned shell keeps its I/O.
+      # @param [Object] fd The descriptor argument, as {#argument} returns it.
+      # @return [void]
+      # @example One the caller chooses is recorded; one fixed in the code is
+      #   nobody's to change.
+      #   note_closed_fd(Lambda.parse('[rsp+0x60]')) ; closed_fds #=> ['[rsp+0x60]']
+      #   note_closed_fd(Lambda.parse('0x1'))        ; closed_fds #=> []
+      def note_closed_fd(fd)
+        @closed_fds << fd.to_s unless fd.is_a?(Integer)
+      end
+
+      # Record what the callee does through a pointer argument.
+      # @return [Boolean] false to abort the candidate.
+      # @example Only a symbolic address carries a precondition a caller can
+      #   arrange; a literal one is nobody's to make readable.
+      #   record_pointer(Lambda.parse('rsp+0x40'), :deref) #=> true
+      #   record_pointer(Lambda.parse('0x1'), :deref)      #=> false
+      def record_pointer(arg, req)
+        return NULLABLE_REQUIREMENTS.include?(req) if arg.is_a?(Integer) && arg.zero?
+        return false unless arg.is_a?(OneGadget::Emulators::Lambda)
+
+        case req
+        when :writable then add_writable(arg)
+        when :deref then @deferred_reads << [arg, :readable]
+        when :nullable_deref then @deferred_reads << [arg, :nullable]
+        when :null then return require_null(arg)
+        end
+        true
+      end
+
+      # Record that +arg+ has to be NULL. An address that is mapped by the time
+      # the gadget runs -- the stack, a libc global -- names real memory and so
+      # can't also be NULL, and no caller can arrange otherwise.
+      # @return [Boolean] false to abort the candidate.
+      def require_null(arg)
+        return false if mapped_nonnull_pointer?(arg)
+
+        @constraints << [:raw, "#{arg} == NULL"]
+        true
+      end
+
+      # Now that emulation is complete and the full writable set is known, record
+      # the residual constraint for each deferred pointer argument, unless it is
+      # already known to reference mapped memory. A +:nullable+ deref becomes a
+      # +:raw+ +<arg> == NULL+ (take the skip-the-dereference path); a +:readable+
+      # deref becomes a +:readable+ constraint (NULL can't satisfy an unconditional
+      # dereference) -- a typed address constraint handled like +:writable+ (see
+      # {#constraints}). Idempotent: the queue is cleared once resolved.
+      def finalize_deferred_reads
+        @deferred_reads.each do |arg, kind|
+          if kind == :readable
+            next if mapped_nonnull_pointer?(arg) || writable_pointer?(arg)
+
+            @constraints << [:readable, arg]
+          else
+            next if deref_safe_pointer?(arg) || writable_pointer?(arg)
+
+            @constraints << [:raw, "#{arg} == NULL"]
+          end
+        end
+        @deferred_reads = []
+      end
+
+      # Whether dereferencing +val+ is safe: it is NULL, or a pointer already known
+      # to reference mapped memory (see {#mapped_pointer?}).
+      def deref_safe_pointer?(val)
+        return true if val.is_a?(Integer) && val.zero?
+        return false unless val.is_a?(OneGadget::Emulators::Lambda) && val.deref_count.zero?
+
+        mapped_pointer?(val.obj.to_s)
+      end
+
+      # Whether +val+ is already known to be a non-NULL pointer into mapped memory
+      # -- the safety bar for an *unconditional* dereference, which (unlike
+      # {#deref_safe_pointer?}) NULL cannot clear.
+      def mapped_nonnull_pointer?(val)
+        return false unless val.is_a?(OneGadget::Emulators::Lambda) && val.deref_count.zero?
+
+        mapped_pointer?(val.obj.to_s)
+      end
+
+      # Whether +val+ points into memory already known mapped from a store
+      # through its base during emulation -- either an explicit +writable+
+      # constraint (a store {#get_corresponding_stack} couldn't place, e.g. a
+      # compound destination), or memory tracked against that base (a store it
+      # could place -- the same evidence, a different bookkeeping path).
+      def writable_pointer?(val)
+        return false unless val.is_a?(OneGadget::Emulators::Lambda) && val.deref_count.zero?
+
+        base = val.obj.to_s
+        return true if @constraints.any? { |type, obj| type == :writable && obj.obj.to_s == base }
+
+        stack = get_corresponding_stack(base)
+        !!stack && !stack.empty?
+      end
+
+      # Whether an address expression names memory known to be mapped: a stack slot,
+      # the libc base, or a libc global.
+      def mapped_pointer?(obj)
+        obj.include?(sp) || obj == libc_base.obj.to_s || global_var?(obj)
+      end
+
+      # Record a "must be writable" constraint for a store's target address.
+      # @param [OneGadget::Emulators::Lambda] lmda The destination address, zero-deref
+      #   (already +ref!+'d by the caller).
+      def add_writable(lmda)
+        @constraints << [:writable, lmda] if needs_writable?(lmda)
+      end
+
+      # Require +val+'s pointer be readable when a load dereferences an
+      # uncontrolled base -- one that doesn't root at mapped memory (see
+      # {#mapped_pointer?}), since a value read from the stack or a libc global is
+      # reliably valid. Deferred like a safe call's +:deref+ so a later store
+      # proving the base writable still discharges it.
+      # @param [Object] val The loaded value, as produced by {#arg_to_lambda}.
+      # @example note_read(arg_to_lambda('[x19+0xed8]')) records readable: x19+0xed8
+      def note_read(val)
+        return unless val.is_a?(OneGadget::Emulators::Lambda) && val.deref_count.positive?
+
+        ptr = val.dup.ref!
+        root = root_base(ptr)
+        return if root && mapped_pointer?(root.to_s)
+
+        @deferred_reads << [ptr, :readable]
+      end
+
+      # Whether a store through +lmda+ imposes a "must be writable" constraint. It
+      # lands on writable-or-fixed memory for free when the target is the stack
+      # pointer (the stack is always writable), the program counter, or the libc
+      # base (a fixed libc-internal address); a frame pointer or attacker register
+      # still needs the constraint.
+      # @example (sp is +rsp+, pc is +rip+)
+      #   needs_writable?(arg_to_lambda('rax'))        #=> true   # an attacker register
+      #   needs_writable?(arg_to_lambda('[rsp+0x8]'))  #=> false  # the stack is writable
+      #   needs_writable?(arg_to_lambda('$base+0x10')) #=> false  # a fixed libc global
+      def needs_writable?(lmda)
+        ![sp, pc, libc_base.obj.to_s].include?(lmda.obj.to_s)
+      end
+    end
+  end
+end

data/lib/one_gadget/emulators/data_processing.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'one_gadget/emulators/lambda'
+
+module OneGadget
+  module Emulators
+    # What an instruction leaves in a register: the architecture-independent half of
+    # an +inst_*+ handler. A result that stays an offset from a known base keeps that
+    # form, so the rest of the emulator can resolve it against tracked memory; one
+    # that does not is named as the operation it is, since a caller deriving a value
+    # that way still has to arrange its operands. Anything neither of those aborts
+    # the candidate rather than being recorded as a value it is not. Mixed into
+    # {Processor}.
+    module DataProcessing
+      private
+
+      # The value +op+ produces from +lhs+ and +rhs+: folded when both are
+      # concrete, and otherwise named as the operation itself, since no
+      # base+offset expresses it (see {Lambda.operation}). +nil+ when it is
+      # neither -- an operation on something this emulator cannot name, which the
+      # caller reports against its own mnemonic.
+      # @param [Symbol] op A Ruby operator that doubles as how the operation renders.
+      # @param [Lambda, Integer] lhs The value operated on.
+      # @param [Lambda, Integer] rhs The value it is operated on with.
+      # @return [Lambda, Integer, nil] The result, or nil when it is not one this
+      #   emulator can name.
+      # @example (amd64) +and rax, 0xf+ with rax unknown leaves +(rax & 0xf)+
+      #   operation_result(:&, registers['rax'], 0xf)
+      def operation_result(op, lhs, rhs)
+        return lhs.send(op, rhs) if lhs.is_a?(Integer) && rhs.is_a?(Integer)
+        return nil unless lhs.is_a?(OneGadget::Emulators::Lambda)
+
+        # Exclusive-or of a value with itself is zero whether or not the value is
+        # known -- how every arch spells "zero this register".
+        return 0 if op == :^ && lhs.to_s == rhs.to_s
+
+        OneGadget::Emulators::Lambda.operation(lhs, op.to_s, rhs)
+      end
+
+      # Add or subtract, and store the result.
+      # @example An offset from a known base stays one, which the rest of the
+      #   emulator resolves against tracked memory; a sum of two unknowns is named
+      #   as the operation it is, so a pointer derived that way still says what the
+      #   caller has to arrange.
+      #   arith(:+, 'rax', 'rsp', '0x10') ; registers['rax'] #=> rsp+0x10
+      #   arith(:+, 'rax', 'rdi', 'rsi')  ; registers['rax'] #=> (rdi + rsi)
+      # @param [Symbol] op +:++ or +:-+.
+      # @param [String] dst The destination register.
+      # @param [String] src The value added to, or the only operand given.
+      # @param [String, nil] op2 The value to add, or nil in the 2-operand form.
+      # @return [void]
+      # @raise [OneGadget::Error::UnsupportedInstructionArgumentError]
+      #   When the result is not one this emulator can name.
+      def arith(op, dst, src, op2)
+        check_register!(dst)
+        src, op2 = shorthand(dst, src, op2)
+        lhs = value_of(src)
+        rhs = value_of(op2)
+
+        result = offset_result(op, lhs, rhs)
+        # The stack pointer has to stay an offset from itself: every tracked
+        # stack slot is keyed on it, and a candidate that reads one back after
+        # allocating a variable-size frame would be answered from the wrong
+        # place. Such a frame also puts the array a gadget builds at an address
+        # only a register the caller supplies decides, which no constraint this
+        # emulator emits states.
+        result ||= operation_result(op, lhs, rhs) unless dst == sp
+        raise_unsupported(op, dst, src, op2) if result.nil?
+
+        registers[dst] = result
+      end
+
+      # +lhs op rhs+ when the result is an offset from +lhs+'s base, which
+      # {Lambda} expresses directly. +nil+ when it is not, leaving the caller to
+      # name the operation instead.
+      # @return [Lambda, Integer, nil]
+      def offset_result(op, lhs, rhs)
+        return lhs.send(op, rhs) if rhs.is_a?(Integer)
+        # Adding a known offset to an unknown value is the same value shifted;
+        # subtracting from one is not, so only addition commutes here.
+        return rhs + lhs if op == :+ && lhs.is_a?(Integer)
+
+        nil
+      end
+
+      # Apply a data-processing instruction and store its result. An arch that
+      # allows the 2-operand shorthand may pass +src+ as the only operand.
+      # @param [Symbol] op A Ruby operator that doubles as how the operation renders.
+      # @param [String] dst The destination register.
+      # @param [String] src The left operand, or the only one given (see {#shorthand}).
+      # @param [String, nil] op2 The right operand, or nil in the 2-operand form.
+      # @param [String] name The mnemonic, named in an abort.
+      # @return [void]
+      # @raise [OneGadget::Error::UnsupportedInstructionArgumentError]
+      #   When the result is nothing this emulator can name.
+      def data_op(op, dst, src, op2, name:)
+        check_register!(dst)
+        src, op2 = shorthand(dst, src, op2)
+        result = operation_result(op, value_of(src), value_of(op2))
+        raise_unsupported(name, dst, src, op2) if result.nil?
+
+        # A shift can push bits past the register width, which the arbitrary-
+        # precision fold above would otherwise keep.
+        registers[dst] = result.is_a?(Integer) ? result & width_mask : result
+      end
+
+      # +op2+ with every bit flipped. Only a concrete value has a complement this
+      # emulator can name; a symbolic one aborts rather than being recorded as a
+      # mask it isn't.
+      # @param [String] name The mnemonic to report an abort against.
+      # @param [String] op2 The operand to complement.
+      # @param [Array<String>] reported The operands to name in that abort.
+      # @return [Integer] +op2+ complemented, within the register width.
+      def complement(name, op2, *reported)
+        value = value_of(op2)
+        raise_unsupported(name, *reported) unless value.is_a?(Integer)
+
+        ~value & width_mask
+      end
+
+      # Every bit of a register, for masking a result back to its width.
+      # @return [Integer]
+      def width_mask = (1 << self.class.bits) - 1
+
+      # The value of an operand. {Arm} overrides it for +pc+, whose value depends
+      # on the address of the instruction reading it.
+      # @param [String] arg The operand, as written.
+      # @return [OneGadget::Emulators::Lambda, Integer] Its current value.
+      def value_of(arg) = arg_to_lambda(arg)
+
+      # Expand a 2-operand data-processing form into its (src, op2) operands:
+      # +add dst, op2+ is shorthand for +add dst, dst, op2+, while an explicit
+      # 3-operand form is passed through unchanged.
+      # @param [String] dst The destination register, which the 2-operand form
+      #   also reads as its left operand.
+      # @param [String] src The left operand, or the right one in the 2-operand form.
+      # @param [String, nil] op2 The right operand, or nil in the 2-operand form.
+      # @return [(String, String)] The left and right operands.
+      # @example
+      #   shorthand('r0', 'r4', nil) # 2-operand: add r0, r4
+      #   #=> ['r0', 'r4']
+      #   shorthand('r0', 'r4', '8') # 3-operand: add r0, r4, 8
+      #   #=> ['r4', '8']
+      def shorthand(dst, src, op2)
+        op2.nil? ? [dst, src] : [src, op2]
+      end
+
+      # An instruction with no effect this emulator models anything of.
+      # @return [void]
+      def inst_nop(*); end
+
+      # Replace register tokens that currently hold a concrete integer with that
+      # integer, so a register-indexed memory operand becomes an offset one the
+      # Lambda parser handles.
+      # @example
+      #   # with the index register currently holding 0xd8
+      #   resolve_int_regs('[r8, r2]')  #=> '[r8, 0xd8]'
+      #   resolve_int_regs('[x8, x2]')  #=> '[x8, 0xd8]'
+      def resolve_int_regs(str)
+        str.gsub(/[a-z]+\d*/) do |tok|
+          v = registers[tok] if register?(tok)
+          v.is_a?(Integer) ? OneGadget::Helper.hex(v) : tok
+        end
+      end
+    end
+  end
+end

data/lib/one_gadget/emulators/i386.rb

@@ -9,6 +9,7 @@ module OneGadget
     class I386 < X86
       class << self
         # Yap, bits.
+        # @return [Integer]
         def bits
           32
         end
@@ -19,12 +20,9 @@ module OneGadget
         super(OneGadget::ABI.i386, 'esp', 'ebp', 'eip')
       end
 
-      # Get function call arguments.
-      #
-      # For i386 this is a little bit tricky.
-      # We need to fetch the stack slots reference to current 'esp'
-      # but not original 'esp'.
-      # So we need to evaluate the offset of current esp first.
+      # The value on the stack slot holding the +idx+-th argument. The slots are
+      # relative to the +esp+ the line sees, not the one the candidate was entered
+      # with, so its offset is evaluated first.
       # @param [Integer] idx The 0-based index of the argument.
       # @return [Lambda, Integer] The value on the stack slot holding the +idx+-th argument.
       def argument(idx)

data/lib/one_gadget/emulators/instruction.rb

@@ -46,11 +46,34 @@ module OneGadget
       # @param [String] cmd One line of objdump output.
       # @return [Boolean] +true+ if +cmd+ contains this instruction's mnemonic.
       def match?(cmd)
-        (cmd =~ /#{inst}\s/) != nil
+        cmd.match?(/#{Regexp.escape(inst)}\s/)
+      end
+
+      class << self
+        # The emulator method that runs +mnemonic+. A mnemonic is not always a
+        # method name -- one can carry a suffix spelled with a dot -- so the dots
+        # become underscores. Named here, rather than at each dispatch, so an
+        # emulator defining a family of handlers at once agrees with the dispatcher
+        # about what to call them.
+        # @param [String] mnemonic
+        # @return [Symbol]
+        # @example
+        #   Instruction.handler_name('mov')     #=> :inst_mov
+        #   Instruction.handler_name('sext.w')  #=> :inst_sext_w
+        def handler_name(mnemonic) = :"inst_#{mnemonic.tr('.', '_')}"
+      end
+
+      # The emulator method that runs this instruction.
+      # @return [Symbol]
+      # @see .handler_name
+      def handler
+        @handler ||= self.class.handler_name(inst)
       end
 
       private
 
+      # Split an operand list on the commas that separate operands, which are the
+      # ones outside brackets: a memory operand carries commas of its own.
       def parse_args(str)
         args = []
         cur = +''

data/lib/one_gadget/emulators/lambda.rb

@@ -12,7 +12,7 @@ module OneGadget
     # 4. dereferenced {Lambda}
     class Lambda
       attr_accessor :obj # @return [String, Lambda] The object currently related to.
-      attr_accessor :immi # @return [Integer] The immidiate value currently added.
+      attr_accessor :immi # @return [Integer] The immediate value currently added.
       attr_accessor :deref_count # @return [Integer] The times of dereference.
       attr_accessor :op # @return [String, nil] The operator applied to {#obj}, for an operation (see {.operation}).
       attr_accessor :rhs # @return [Integer, Lambda, String, nil] The operator's right operand.
@@ -44,7 +44,7 @@ module OneGadget
       end
 
       # Implement subtract with +Numeric+.
-      # @param [Numeric] other Value to substract.
+      # @param [Numeric] other Value to subtract.
       # @return [Lambda] The result.
       def -(other)
         self + -other
@@ -58,7 +58,7 @@ module OneGadget
 
       # Decrease dereference count by 1.
       # @return [self]
-      # @raise [Error::InstrutionArgumentError] When this object cannot be referenced anymore.
+      # @raise [Error::InstructionArgumentError] When this object cannot be referenced anymore.
       def ref!
         raise Error::InstructionArgumentError, 'Cannot reference anymore!' if @deref_count <= 0
 
@@ -186,7 +186,9 @@ module OneGadget
 
         private
 
-        # @return [(String, Integer)]
+        # Split a memory operand into what it is based on and how far from it.
+        # @param [String] arg The operand, with its brackets already removed.
+        # @return [(String, Integer)] The base, and the offset from it.
         def mem_obj(arg)
           # We have three forms:
           # 0. reg