one_gadget 1.10.0 → 2.1.0

data/lib/one_gadget/emulators/register_file.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'one_gadget/emulators/lambda'
+
+module OneGadget
+  module Emulators
+    # The register state of one emulated candidate, keyed so that names sharing
+    # storage share a value: what a write through a narrower name leaves behind is
+    # what a read of the full register finds, and the other way round.
+    #
+    # Values are kept under the full register's name, so an operand rendered into a
+    # constraint names the storage the caller has to arrange, whichever name the
+    # instruction used to reach it.
+    # @example (amd64) the first argument, set through its 32-bit name
+    #   file['edi'] = 1
+    #   file['rdi'] #=> 1
+    class RegisterFile < Hash
+      # Build the initial state: one entry per distinct storage, holding the value
+      # the block returns for its full name.
+      # @param [Array<String>] names All the register names the architecture accepts.
+      # @param [Hash{String => String}] narrow_views Narrower name => full register.
+      # @yieldparam [String] name The full register's name.
+      # @return [RegisterFile]
+      def self.build(names, narrow_views)
+        new(narrow_views).tap do |file|
+          names.map { |name| narrow_views.fetch(name, name) }
+               .uniq
+               .each { |name| file[name] = yield(name) }
+        end
+      end
+
+      # @param [Hash{String => String}] narrow_views Narrower name => full register.
+      def initialize(narrow_views = {})
+        super()
+        @narrow_views = narrow_views
+        @entry_halves = {}
+      end
+
+      # @param [String] name Any name the architecture accepts, narrow or full.
+      # @return [OneGadget::Emulators::Lambda, Integer] What that name currently reads as.
+      def [](name)
+        value = super(full(name))
+        narrow?(name) ? narrowed(name, value) : value
+      end
+
+      # @param [String] name Any name the architecture accepts, narrow or full.
+      # @param [OneGadget::Emulators::Lambda, Integer] value
+      # @return [void]
+      def []=(name, value)
+        super(full(name), value)
+      end
+
+      # @param [String] name Any name the architecture accepts, narrow or full.
+      # @return [Boolean] Whether its storage holds a value.
+      def key?(name)
+        super(full(name))
+      end
+      alias has_key? key?
+      alias include? key?
+      alias member? key?
+
+      private
+
+      # The name +name+'s storage is kept under: itself, unless it is a narrower
+      # view of a wider register.
+      # @param [String] name
+      # @return [String]
+      def full(name)
+        @narrow_views.fetch(name, name)
+      end
+
+      # @param [String] name
+      # @return [Boolean] Whether +name+ addresses part of a wider register.
+      def narrow?(name)
+        @narrow_views.key?(name)
+      end
+
+      # The part of +value+ that +name+ addresses. Handing back the whole of what
+      # cannot be halved over-approximates, which only ever tightens a constraint
+      # or drops the path it renders.
+      #
+      # The name's own lambda is kept rather than rebuilt, so repeated reads of an
+      # untouched register return one object -- a value is compared by identity to
+      # tell a reassignment from what was there before (see
+      # {Processor#reg_based_stack}).
+      # @param [String] name A narrower name (see {#narrow?}).
+      # @param [Object] value The value held by the register it names part of.
+      # @return [Object]
+      # @example (amd64) The low half of a register still holding what the gadget
+      #   was entered with is the one part a name addresses exactly; no expression
+      #   names half of anything else.
+      #   narrowed('eax', Lambda.parse('rax'))      #=> eax
+      #   narrowed('eax', Lambda.parse('rsp+0x10')) #=> rsp+0x10
+      def narrowed(name, value)
+        return value unless entry_value?(value, full(name))
+
+        @entry_halves[name] ||= Lambda.new(name)
+      end
+
+      # Whether +value+ is still the untouched value +reg+ was entered with.
+      def entry_value?(value, reg)
+        value.is_a?(Lambda) && value.obj == reg && value.deref_count.zero? && value.immi.zero?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module OneGadget
+  module Emulators
+    # Arch-independent catalog of libc calls the emulator accepts without
+    # 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.
+    #
+    # Order matters: the first key that is a substring of the call symbol wins, so
+    # 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 = {
+        # sigprocmask/__sigaction dereference a pointer arg unless it is NULL, which
+        # glibc guards with an explicit NULL check (and still reaches the call on the
+        # NULL path): sigprocmask's +set+ and __sigaction's +act+ (both arg 1).
+        # __sigaction also writes back through +oldact+ (arg 2), so oldact must be NULL.
+        'sigprocmask' => { 1 => :nullable_deref },
+        '__sigaction' => { 1 => :nullable_deref, 2 => :null },
+        # Record the descriptor __close closes: which one it is decides whether the
+        # spawned shell keeps its I/O (see {Processor#note_closed_fd}).
+        '__close' => { 0 => :closed_fd },
+        # unsetenv reads its name (arg 0); +:global_var?+ may over-constrain it
+        # (readable would suffice), but no current fixture reaches unsetenv near an
+        # exec to verify -- left as-is.
+        'unsetenv' => { 0 => :global_var? },
+        # setsigmask/setsigdefault copy *set into the attr unconditionally, so the
+        # source (arg 1) must be readable and the attr they write (arg 0) writable.
+        'posix_spawnattr_setsigmask' => { 0 => :writable, 1 => :deref },
+        'posix_spawnattr_setsigdefault' => { 0 => :writable, 1 => :deref },
+        # every other attr setup helper writes its attr object (arg 0).
+        'posix_spawnattr_' => { 0 => :writable }
+        # posix_spawn_file_actions_* helpers are deliberately absent, so a candidate
+        # that calls one is aborted (see {Processor#dispatch_safe_call}) rather than
+        # walked through. Accepting them would need a model out of reach today:
+        #   * the helper returns 0 only when its fd argument is a valid fd
+        #     (0 <= fd < INT_MAX), and the caller branches on that return -- a nonzero
+        #     result skips the following +posix_spawn+ -- so treating the call as
+        #     always succeeding emits a gadget whose reachability doesn't actually hold;
+        #   * appending the action grows +__actions+ via +realloc+, which can fail
+        #     (ENOMEM) or fault on a bogus object -- not guaranteeable from a symbolic
+        #     writable pointer;
+        #   * +posix_spawn_file_actions_t+ is a glibc-internal, version-dependent
+        #     layout, so modeling its fields soundly across libc versions is fragile;
+        #   * and a successful call injects a close/open/dup2 into the spawned child
+        #     whose harmlessness depends on the fd, which isn't expressible.
+      }.freeze
+    end
+  end
+end

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