one_gadget 2.0.0 → 2.1.0

data/lib/one_gadget/emulators/riscv64.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require 'one_gadget/abi'
+require 'one_gadget/emulators/instruction'
+require 'one_gadget/emulators/processor'
+
+module OneGadget
+  module Emulators
+    # Emulator of RISC-V (RV64).
+    class Riscv64 < Processor
+      # Instantiate a {Riscv64} object.
+      def initialize
+        super(OneGadget::ABI.riscv64, 'sp')
+        @registers['zero'] = 0 # hardwired
+        @pc = 'pc'
+        setup_frame_pointer('s0') # track argv/data staged off the frame pointer
+      end
+
+      # @see OneGadget::Emulators::X86#process!
+      # @param [String] cmd One line from result of objdump.
+      # @return [Boolean] If successfully processed.
+      def process!(cmd)
+        resolve_pending_branch(cmd)
+        @cur_addr = cmd[/\A\s*([0-9a-f]+):/, 1]&.to_i(16)
+
+        mnem = mnemonic(cmd)
+        return handle_branch(mnem, cmd) != :fail if branch_mnem?(mnem)
+
+        inst, args = parse(cmd)
+        __send__(inst.handler, *args) != :fail
+      end
+
+      # A conditional branch of this arch compares its operands itself -- there is
+      # no flag register and no compare instruction -- so each mnemonic names the
+      # relation the operands must stand in for the branch to be taken. The
+      # assembler's spellings against zero (+beqz+, +blez+, ...) name one register
+      # and the reversed ones (+bgt+, +ble+, ...) read a relation the other way
+      # round; each is listed as the relation it states, so a constraint reads as
+      # the comparison was written.
+      COND = {
+        'beq' => :eq, 'bne' => :ne,
+        'blt' => :slt, 'bge' => :sge, 'bltu' => :ult, 'bgeu' => :uge,
+        'bgt' => :sgt, 'ble' => :sle, 'bgtu' => :ugt, 'bleu' => :ule,
+        'beqz' => :eq, 'bnez' => :ne,
+        'bltz' => :slt, 'bgez' => :sge, 'blez' => :sle, 'bgtz' => :sgt
+      }.freeze
+
+      # The data-processing instructions, mapped to the Ruby operator that folds
+      # them and renders them alike. 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, and naming the arithmetic one as that would state a different
+      # instruction.
+      DATA_OPS = {
+        'and' => :&, 'andi' => :&,
+        'or' => :|, 'ori' => :|,
+        'xor' => :^, 'xori' => :^,
+        'sll' => :<<, 'slli' => :<<,
+        'srl' => :>>, 'srli' => :>>
+      }.freeze
+      private_constant :DATA_OPS
+
+      # The loads, mapped to how many bytes each reads.
+      LOADS = { 'ld' => 8, 'lw' => 4, 'lwu' => 4, 'lh' => 2, 'lhu' => 2, 'lb' => 1, 'lbu' => 1 }.freeze
+      private_constant :LOADS
+
+      # The stores, mapped to how many bytes each writes.
+      STORES = { 'sd' => 8, '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('add', 3),
+          Instruction.new('addi', 3),
+          Instruction.new('auipc', 2),
+          Instruction.new('jal', 1..2),
+          Instruction.new('li', 2),
+          Instruction.new('lui', 2),
+          Instruction.new('mv', 2),
+          Instruction.new('nop', 0),
+          Instruction.new('sub', 3),
+          Instruction.new('not', 2)
+        ] + (LOADS.keys + STORES.keys).map { |mnem| Instruction.new(mnem, 2) } +
+          DATA_OPS.keys.map { |mnem| Instruction.new(mnem, 3) }
+      end
+
+      # Return the argument value of calling a function.
+      # @param [Integer] idx The 0-based index of the argument.
+      # @return [Lambda, Integer] The value held in register +a<idx>+, used for the +idx+-th argument.
+      def argument(idx)
+        registers["a#{idx}"]
+      end
+
+      private
+
+      def branch_mnem?(mnem)
+        mnem == 'j' || COND.key?(mnem)
+      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}). The zero spellings leave their second
+      # operand out; +zero+ names it, and reads as the +0x0+ it holds.
+      def handle_branch(mnem, cmd)
+        return true if mnem == 'j' # 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 direct call: record the terminal +exec*+ target, accept a known-safe
+      # syscall wrapper, or +:fail+ to abort the candidate. The two-operand form
+      # names the register the return address is written to, which is +ra+ for a
+      # call and is not modelled either way.
+      def inst_jal(*args)
+        addr = args.last
+        return reach_terminal_call(addr) if terminal_call?(addr)
+
+        dispatch_safe_call(addr)
+      end
+
+      # +auipc dst, imm+ is how this arch names an address relative to the
+      # instruction itself: the immediate objdump prints is the upper 20 bits, so
+      # the value is +pc + (imm << 12)+. The +addi+/load that follows applies the
+      # low half, which is what makes the pair resolve to the +$base+<off>+ form
+      # the rest of the engine reads as a libc global.
+      # @example the pair objdump resolves to 171fc0 in its own comment
+      #   9f48e: auipc a5,0xd3     # a5 = $base+0x17248e
+      #   9f492: ld    a5,-1230(a5) # a5 = [$base+0x171fc0]
+      def inst_auipc(dst, imm)
+        check_register!(dst)
+
+        registers[dst] = pc_value + (imm.to_i(16) << 12)
+      end
+
+      # +lui dst, imm+ loads the same upper 20 bits, but as a plain value rather
+      # than an address, so nothing about the instruction's own location enters it.
+      def inst_lui(dst, imm)
+        check_register!(dst)
+
+        registers[dst] = (imm.to_i(16) << 12) & width_mask
+      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
+
+      # This arch spells no modifier on an operand and has no 2-operand shorthand,
+      # so the arithmetic is the plain three-operand form; +addi+ differs from
+      # +add+ only in that its right operand is written as a literal.
+      def inst_add(dst, src, op2) = arith(:+, dst, src, op2)
+      alias inst_addi inst_add
+
+      # +sub dst, src, op2+. See {#inst_add}.
+      def inst_sub(dst, src, op2) = arith(:-, dst, src, op2)
+
+      def inst_mv(dst, src)
+        check_register!(dst)
+
+        registers[dst] = arg_to_lambda(src)
+      end
+
+      # Each data-processing mnemonic handled the one way, since they differ only
+      # in the operator applied (see {Processor#data_op} for the operands).
+      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
+
+      # +not dst, src+ is every bit of +src+ flipped. Only a concrete value has a
+      # complement this emulator can name ({Processor#complement}); a symbolic one
+      # aborts rather than being recorded as a mask it isn't.
+      def inst_not(dst, src)
+        check_register!(dst)
+
+        registers[dst] = complement('not', src, dst, src)
+      end
+
+      # Each load and store handled the one way, since within a family they differ
+      # only in the width they touch (see {#load_value} and {#store_value}).
+      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: a path
+      # that goes on to depend on it is abandoned rather than described wrongly.
+      # @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)
+
+        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 holding whatever was there, so
+      # what the slot then holds is named as unknown rather than as the value
+      # stored -- the requirement that it be writable is what the candidate really
+      # establishes, and that is kept.
+      # @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 every operand but an upper immediate.
+      # @param [String] mem The operand, as written.
+      # @return [String]
+      # @example
+      #   mem_operand('-1230(a5)') #=> '[a5-1230]'
+      #   mem_operand('0(s1)')     #=> '[s1+0]'
+      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
+
+      # The value +pc+ holds while the instruction at {@cur_addr} runs: this arch
+      # reads its own address, with no pipeline bias to add.
+      def pc_value
+        libc_base + @cur_addr
+      end
+
+      class << self
+        # RV64 is 64-bit.
+        # @return [Integer]
+        def bits
+          64
+        end
+      end
+    end
+  end
+end

data/lib/one_gadget/emulators/safe_calls.rb

@@ -3,9 +3,9 @@
 module OneGadget
   module Emulators
     # Arch-independent catalog of libc calls the emulator accepts without
-    # executing them (see {Processor#dispatch_safe_call} for how an entry's
-    # per-argument requirements are applied and what each requirement symbol
-    # means). These functions -- syscall wrappers and +posix_spawn+'s setup
+    # executing them (see {COMMON} for what each requirement means, and
+    # {Processor#dispatch_safe_call} for how they are applied). These
+    # functions -- syscall wrappers and +posix_spawn+'s setup
     # helpers -- have identical semantics on every architecture, so their
     # requirements live here once instead of being copied into each arch's
     # emulator, keeping the arches from drifting.
@@ -14,6 +14,12 @@ module OneGadget
     # the specific +posix_spawnattr_setsigmask+/+setsigdefault+ keys precede the
     # generic +posix_spawnattr_+ prefix.
     module SafeCalls
+      # What each requirement asks of the caller:
+      # * +:global_var?+ -- nothing; it must already hold, or the candidate is aborted.
+      # * +:closed_fd+ -- nothing; the descriptor is recorded (see {Processor#note_closed_fd}).
+      # * +:null+, +:nullable_deref+ -- +<arg> == NULL+.
+      # * +:deref+ -- +readable: <arg>+.
+      # * +:writable+ -- +writable: <arg>+.
       # @return [Hash{String => Hash{Integer => Symbol}}]
       #   Function name (or name prefix) => argument index => requirement.
       COMMON = {

data/lib/one_gadget/emulators/tracked_memory.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'one_gadget/emulators/lambda'
+
+module OneGadget
+  module Emulators
+    # The memory a candidate reads and writes. Every store is filed under the base
+    # its address is an offset from -- the stack pointer, the frame pointer, or any
+    # register holding a pointer the caller supplies -- so a later load of the same
+    # slot reads back what this candidate put there, and a load of an untouched one
+    # is answered as what the caller left. Mixed into {Processor}.
+    module TrackedMemory
+      # @return [Hash{Integer => OneGadget::Emulators::Lambda}] Memory written through +sp+.
+      def sp_based_stack = get_corresponding_stack(sp)
+
+      # @return [Hash{Integer => Lambda}, nil] Memory written through {Processor#bp}, or nil when the arch has none.
+      def bp_based_stack = bp && get_corresponding_stack(bp)
+
+      # Enable frame-pointer stack tracking with +bp+ as the frame register, so a
+      # gadget staging data at +[bp+imm]+ (e.g. an argv array off the frame
+      # pointer) is recovered instead of collapsing to a bare +writable:+. A nil
+      # +bp+ leaves the arch +sp+-only. Call from the arch initializer after +super+.
+      # @param [String, nil] bp The frame register's name, or nil for an arch with none.
+      # @return [void]
+      def setup_frame_pointer(bp)
+        @bp = bp
+      end
+
+      # Where +address+ lands in the memory this emulator tracks: the stack it
+      # falls in and its offset within it. A load or store passes the address it
+      # dereferences, i.e. its operand with that dereference peeled off.
+      # @param [Lambda, String] address An address.
+      # @return [(Hash{Integer => Lambda}?, Integer)] The stack, +nil+ if none
+      #   tracks this address, and the offset to index it at.
+      # @example an offset from a register
+      #   resolve_address(Lambda.parse('rsp+0x10')) #=> [sp_based_stack, 0x10]
+      # @example an offset from a pointer no register names
+      #   resolve_address(Lambda.parse('[rbp-0x48]+0x8')) #=> [the "[rbp-0x48]" stack, 0x8]
+      def resolve_address(address)
+        base, offset = address_base(address)
+        [get_corresponding_stack(base), offset]
+      end
+
+      # The memory +base+ addresses: what this candidate has written through it,
+      # keyed by offset. Every base gets one -- the stack pointer, the frame
+      # pointer, any other register, and a value no register names at all (a
+      # pointer the candidate derived and then built an array through).
+      #
+      # Keyed by how the base renders, which is what makes one store enough: a
+      # register that gets reassigned addresses somewhere else and renders
+      # differently, so it lands on a different key without any invalidation to
+      # arrange. Only a store overwriting what the base itself reads from would
+      # break that, which a candidate short enough to be a gadget doesn't do.
+      # @example (amd64) After +mov QWORD PTR [rsp+0x10], rdi+, keyed by offset.
+      #   get_corresponding_stack('rsp') #=> { 0x10 => rdi }
+      # @param [String, Lambda] base A base, as {#resolve_address} yields it --
+      #   not an offset expression, whose offset belongs in the key it indexes.
+      # @return [Hash{Integer => Lambda}, nil] nil when +base+ names nothing this
+      #   emulator tracks memory for.
+      def get_corresponding_stack(base)
+        return nil unless base.is_a?(OneGadget::Emulators::Lambda) || registers.key?(base.to_s)
+
+        tracked_memory[base.to_s]
+      end
+
+      # The values this candidate wrote through an address built from +text+, which
+      # the array reported at +text+ therefore holds -- wherever in it they landed.
+      # A reader told about that array has to be told about these too, or it is
+      # described as though the gadget had not written to it.
+      # @param [String] text How the address is named.
+      # @return [Array<String>] Each value written, rendered, without duplicates.
+      # @example (riscv64) a store of +s8+ through +((a5 << 0x3) + [sp+0xd0])+
+      #   writes_through('[sp+0xd0]') #=> ['s8']
+      def writes_through(text)
+        return [] if text.empty?
+
+        derived_writes.filter_map do |base, values|
+          next unless operands_of(base).any? { |operand| operand.to_s == text }
+
+          # A literal is not the caller's to arrange -- it is already what it is,
+          # and the NULL such a loop writes to terminate the array is one.
+          values.grep_v(Integer).map(&:to_s)
+        end.flatten.uniq
+      end
+
+      private
+
+      # Every base this candidate has written through, each mapped to the memory
+      # it addresses. See {#get_corresponding_stack}, which is how it is reached.
+      # @return [Hash{String => Hash{Integer => Lambda}}]
+      def tracked_memory
+        @tracked_memory ||= Hash.new { |memory, base| memory[base] = tracked_stack(base) }
+      end
+
+      # Split +address+ into the base it is offset from and that offset, in the
+      # forms {#get_corresponding_stack} and a tracked stack expect.
+      # @param [Lambda, String] address See {#resolve_address}.
+      # @return [(String, Lambda), Integer]
+      def address_base(address)
+        return [address, 0] unless address.is_a?(OneGadget::Emulators::Lambda)
+        # Still a dereference deep, so the whole thing names one value rather than
+        # an offset from anything: its own immediate is part of that name.
+        return [address, 0] if address.deref_count.positive?
+        # An operation's +obj+ is only the value it operates on, which addresses
+        # somewhere else entirely -- a candidate building an array through
+        # +(rsi & ~0xf)+ is not writing through +rsi+.
+        return [address.dup.tap { |base| base.immi = 0 }, address.immi] if address.operation?
+
+        [address.obj, address.immi]
+      end
+
+      # An always-on tracked stack keyed by offset: a Hash that lazily materialises
+      # +[reg+off]+ as a one-deref {Lambda}. Used for the +sp+- and {Processor#bp}-based stacks.
+      def tracked_stack(reg)
+        Hash.new do |h, k|
+          h[k] = OneGadget::Emulators::Lambda.new(reg).tap do |lmda|
+            lmda.immi = k
+            lmda.deref!
+          end
+        end
+      end
+
+      # The value an instruction reads through +val+: what this candidate put at
+      # that address, when it is one the candidate has written, and the
+      # dereference itself otherwise (recording the read, see {#note_read}).
+      #
+      # A slot the gadget fills in reads back as what was put there, so a
+      # constraint on it names the value the caller has to arrange rather than
+      # whatever the slot held on entry -- which the gadget has already replaced.
+      # @param [Object] val The operand's value, as produced by {#arg_to_lambda}.
+      # @return [Object]
+      # @example (arm) +str r3, [sp, #4]+ then +ldr r0, [sp, #4]+ reads back r3
+      def read_value(val)
+        stored = stored_value(val)
+        return stored unless stored.nil?
+
+        note_read(val)
+        val
+      end
+
+      # What this candidate stored at the address +val+ dereferences, or +nil+ if
+      # it stored nothing there. Only a single dereference of an address this
+      # emulator tracks names a slot it can answer for (see {#resolve_address}).
+      # @param [Object] val
+      # @return [Object, nil]
+      def stored_value(val)
+        return nil unless val.is_a?(OneGadget::Emulators::Lambda) && val.deref_count.positive?
+
+        stack, offset = resolve_address(val.dup.ref!)
+        stack&.key?(offset) ? stack[offset] : nil
+      end
+
+      # The innermost base name of a (possibly nested or dereferenced) address
+      # lambda, following +obj+ through any nested lambdas.
+      # @param [OneGadget::Emulators::Lambda] lmda
+      # @return [String, nil] The root base name, or +nil+ for an absolute address.
+      # @example
+      #   root_base(arg_to_lambda('[[$base+0x10]+0x8]')) #=> '$base'
+      #   root_base(arg_to_lambda('x19+0xed8'))          #=> 'x19'
+      def root_base(lmda)
+        obj = lmda.obj
+        obj = obj.obj while obj.is_a?(OneGadget::Emulators::Lambda)
+        obj
+      end
+
+      # Stores whose address is an operation rather than a base and a displacement
+      # -- a scaled index added to a pointer, say. Such a write lands somewhere in
+      # whatever that pointer addresses, at an offset only a value the caller
+      # supplies decides, so it is tracked under a base of its own that nothing
+      # reads back (see {#writes_through}).
+      # @return [Array<(Lambda, Array)>] Each address operation, and what went there.
+      def derived_writes
+        @derived_writes ||= []
+      end
+
+      # The values an operation is built from, flattened out of its tree, so an
+      # operand is recognised as itself rather than as text inside a rendering
+      # (where +x3+ would be found in +x30+).
+      # @param [Lambda, Object] lmda An address, or one part of one.
+      # @return [Array] Its leaf operands, or +lmda+ itself when it is not an operation.
+      def operands_of(lmda)
+        return [lmda] unless lmda.is_a?(OneGadget::Emulators::Lambda) && lmda.operation?
+
+        operands_of(lmda.obj) + operands_of(lmda.rhs)
+      end
+
+      # Track a store: write +values+ (one per word from +dst_l+) into the stack
+      # {#resolve_address} resolves +dst_l+ to, and require +dst_l+
+      # writable -- unless it is a pure +sp+ store. +sp+ is invariantly the
+      # writable stack; the frame pointer only conventionally is, so a store
+      # through it stays a real precondition (like amd64's +writable: rbp+imm+).
+      # @param [OneGadget::Emulators::Lambda] dst_l The destination, zero-deref.
+      # @param [Array<OneGadget::Emulators::Lambda, Integer>] values One per word.
+      # @return [void]
+      def track_write(dst_l, *values)
+        stack, offset = resolve_address(dst_l)
+        base, = address_base(dst_l)
+        derived_writes << [base, values] if base.is_a?(OneGadget::Emulators::Lambda) && base.operation?
+        values.each_with_index { |v, i| stack[offset + size_t * i] = v } if stack
+        add_writable(dst_l) unless stack.equal?(sp_based_stack)
+      end
+
+      # Resolve +sp+- and (when tracked) {Processor#bp}-relative operands to their offset.
+      def eval_dict
+        bp ? { sp => 0, bp => 0 } : { sp => 0 }
+      end
+    end
+  end
+end

data/lib/one_gadget/emulators/x86.rb

@@ -10,6 +10,10 @@ module OneGadget
     # Super class for amd64 and i386 processor.
     class X86 < Processor
       # Constructor for a x86 processor.
+      # @param [Array<String>] registers All the register names this architecture accepts.
+      # @param [String] sp The stack pointer's name.
+      # @param [String] bp The frame pointer's name.
+      # @param [String] pc The program counter's name.
       def initialize(registers, sp, bp, pc)
         super(registers, sp)
         @pc = pc
@@ -30,8 +34,7 @@ module OneGadget
         return handle_branch(mnem, cmd) != :fail if branch_mnem?(mnem)
 
         inst, args = parse(cmd)
-        sym = :"inst_#{inst.inst}"
-        __send__(sym, *args) != :fail
+        __send__(inst.handler, *args) != :fail
       end
 
       # x86 conditional-jump mnemonics mapped to shared {Conditional::RELATION}
@@ -51,14 +54,11 @@ module OneGadget
       COMPARES = { 'cmp' => :sub, 'test' => :and }.freeze
 
       # A segment-prefixed operand reads thread-local storage, which isn't modelled
-      # (nor is its counterpart on the other arches -- aarch64's +mrs tpidr_el0+
-      # and arm's +mrc p15+ are unsupported instructions, so those paths already
-      # abort). Every gadget observed behind one tests +errno == ENOEXEC+ on
-      # glibc's +execvpe+ path -- a value the caller would have to have arranged
-      # beforehand, since the gadget is entered after the +execve+ that would set
-      # it -- so modelling this only produces gadgets that all but never apply.
-      # Worth revisiting if a libc is found reaching a terminal call under a
-      # condition that commonly holds, e.g. +errno != <some error>+.
+      # (the other arches reach it by instructions that are unsupported anyway).
+      # Every gadget observed behind one tests +errno == ENOEXEC+, which the caller
+      # would have had to arrange before entering, so modelling it would produce
+      # gadgets that all but never apply. Worth revisiting for a libc found
+      # reaching a terminal call under a condition that commonly holds.
       # @example +cmp DWORD PTR fs:[r14], 0x8+ -- errno == ENOEXEC
       SEGMENT_OPERAND = /\b(?:fs|gs|ds|es|ss|cs):/
 
@@ -125,6 +125,8 @@ module OneGadget
         branch_on_compare(JCC[mnem], jump_target(cmd))
       end
 
+      # The counter register a +jcxz+-family branch tests, at the width its
+      # mnemonic names.
       def cx_reg(mnem)
         { 'jcxz' => 'cx', 'jecxz' => 'ecx', 'jrcxz' => 'rcx' }[mnem]
       end
@@ -267,10 +269,17 @@ module OneGadget
         registers[dst] = 0
       end
 
+      # A {Lambda} knows how to add a number to itself, not the other way round,
+      # and addition commutes -- adding an unknown value to a known one is the
+      # same unknown value shifted (see {DataProcessing#offset_result}, which
+      # states the same rule for the architectures that go through it).
       def inst_add(dst, src)
         check_register!(dst)
 
-        registers[dst] += read_value(arg_to_lambda(src))
+        lhs = registers[dst]
+        rhs = read_value(arg_to_lambda(src))
+        lhs, rhs = rhs, lhs if lhs.is_a?(Integer)
+        registers[dst] = lhs + rhs
       end
 
       # +and dst, src+ both writes +dst+ and sets the flags a following branch
@@ -303,22 +312,20 @@ module OneGadget
         registers[dst] -= src
       end
 
-      # yap, nop
-      def inst_nop(*); end
-
       # A marker for the branch predictor: it says a jump may land here and leaves
       # every value alone.
       def inst_endbr64(*); end
       alias inst_endbr32 inst_endbr64
 
-      # Swap what two registers hold. Two forms are not that, and stay refused: a
-      # memory operand is an exchange with memory (and an atomic one), and a
-      # narrower view names part of a register, which swapping whole values cannot
-      # express. Naming one place twice is nothing at all, whatever it names --
-      # that is the multi-byte nop a compiler pads with.
-      # @example
-      #   xchg ebx,edi  -- a swap
-      #   xchg ax,ax    -- padding
+      # Swap what two registers hold. Naming one place twice is nothing at all,
+      # whatever it names -- the multi-byte nop a compiler pads with.
+      # @raise [OneGadget::Error::UnsupportedInstructionArgumentError]
+      #   For a memory operand, which is an exchange with memory and an atomic one,
+      #   or a narrower view, which names part of a register where swapping whole
+      #   values cannot reach.
+      # @example (amd64) A swap, then the padding.
+      #   inst_xchg('rbx', 'rdi') #=> [rdi, rbx]
+      #   inst_xchg('rax', 'rax') #=> nil
       def inst_xchg(dst, src)
         return if dst == src
         raise Error::UnsupportedInstructionArgumentError, "xchg #{dst},#{src}" unless
@@ -334,6 +341,9 @@ module OneGadget
         dispatch_safe_call(addr)
       end
 
+      # A vector register holds one value per lane, so it becomes an array of
+      # them -- each lane named by the shift that reaches it -- where an ordinary
+      # register becomes a single {Lambda}.
       def to_lambda(reg)
         return super unless reg =~ /^xmm\d+$/
 

data/lib/one_gadget/fetchers/aarch64.rb

@@ -46,33 +46,6 @@ module OneGadget
       def call_str
         'bl'
       end
-
-      def bin_sh_offset
-        @bin_sh_offset ||= str_offset('/bin/sh')
-      end
-
-      def str_bin_sh?(str)
-        str.include?('$base') && str.include?(bin_sh_offset.to_s(16))
-      end
-
-      # Offset of the standalone "sh" string (\0-preceded and \0-terminated) that
-      # glibc passes as argv[0] in execl("/bin/sh", "sh", ...). Its distance from
-      # "/bin/sh" is build-specific, so locate it directly instead of guessing.
-      # +nil+ when the libc has no such string.
-      def sh_offset
-        return @sh_offset if defined?(@sh_offset)
-
-        idx = File.binread(file).index("\x00sh\x00")
-        @sh_offset = idx && idx + 1
-      end
-
-      def str_sh?(str)
-        !sh_offset.nil? && str.include?('$base') && str.include?(sh_offset.to_s(16))
-      end
-
-      def global_var?(str)
-        base_relative?(str, '$base')
-      end
     end
   end
 end

data/lib/one_gadget/fetchers/amd64.rb

@@ -12,30 +12,6 @@ module OneGadget
       def emulator
         OneGadget::Emulators::Amd64.new
       end
-
-      # The branch-aware walker (see {Base#branch_aware_candidates}) already
-      # stitches +jmp+ targets, so only the filter remains.
-      def candidates
-        super do |candidate|
-          next true if candidate.include?('posix_spawn@')
-          next false unless candidate.include?(bin_sh_hex) # works in x86-64
-          next false unless candidate.lines.last.include?('execve') # only care execve
-
-          true
-        end
-      end
-
-      def bin_sh_hex
-        @bin_sh_hex ||= str_offset('/bin/sh').to_s(16)
-      end
-
-      def str_bin_sh?(str)
-        str.include?('$base') && str.include?(bin_sh_hex)
-      end
-
-      def global_var?(str)
-        base_relative?(str, '$base')
-      end
     end
   end
 end