one_gadget 2.0.0 → 2.1.0

data/lib/one_gadget/emulators/processor.rb

@@ -2,9 +2,12 @@
 
 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
@@ -12,24 +15,26 @@ module OneGadget
   module Emulators
     # 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; the
-    # shared branch/compare machinery comes from {Conditional}.
+    # 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
       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.
 
-      # @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 {#bp}, or nil when the arch has none.
-      def bp_based_stack = bp && get_corresponding_stack(bp)
-
       # Instantiate a {Processor} object.
       # @param [Array<String>] registers
       #   Registers that supported in the architecture.
@@ -47,15 +52,6 @@ module OneGadget
         @pending = nil   # a conditional branch awaiting one-line-ahead resolution
       end
 
-      # 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+.
-      # @return [void]
-      def setup_frame_pointer(bp)
-        @bp = bp
-      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
@@ -75,7 +71,7 @@ module OneGadget
 
       # 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 {#resolve} reads to describe it.
+      # 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)
@@ -172,225 +168,27 @@ module OneGadget
       def argument(_idx); raise NotImplementedError
       end
 
-      # Marks a register holding whatever a call returned or left behind; see
-      # {#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.
-      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.
-      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.
-      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] == 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] == ZERO && nulls.include?(obj[0])
-        end
-      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 a register
-      #   get_corresponding_stack('x21')
-      # @example a pointer rounded down before use
-      #   get_corresponding_stack(Lambda.parse('(rsi & 0xfffffffffffffff0)'))
-      # @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
-
       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 {#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
-
       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))
         end
       end
 
-      # Accept a +call+ to a libc function the emulator treats as non-terminal
-      # (a syscall wrapper). {SafeCalls::COMMON} maps each function name to its
-      # per-argument requirements: an argument index paired with one of
-      # * +:global_var?+ - a precondition that must already hold, else the
-      #   candidate is aborted (+:fail+).
-      # * +:closed_fd+ - the descriptor the callee closes. Nothing is required of
-      #   it; it is recorded, because closing a standard descriptor changes what
-      #   the spawned shell can still do (see {#note_closed_fd}).
-      # * +:null+ - the callee must be given NULL here, so +<arg> == NULL+ is
-      #   recorded for the caller to arrange. A value that can never be NULL --
-      #   a fixed address, or any other non-zero literal -- aborts the candidate.
-      #   @example +__sigaction(sig, act, oldact)+ writes the old action through
-      #     +oldact+ unless it is NULL
-      # * +:nullable_deref+ - the callee dereferences this argument *unless it is
-      #   NULL*, which glibc guards with an explicit NULL check. When the pointer
-      #   isn't already known to be mapped, +<arg> == NULL+ is recorded so the
-      #   callee takes the skip-the-dereference path. Only tag an argument this way
-      #   after confirming the callee both NULL-checks it and still reaches the
-      #   terminal call on the NULL path.
-      # * +:deref+ - the callee dereferences this argument *unconditionally* (no
-      #   NULL guard), so it can't be made safe by forcing it NULL. When the pointer
-      #   isn't already known to be mapped, +readable: <arg>+ is recorded so the
-      #   attacker knows it must reference readable memory.
-      #   @example +posix_spawnattr_setsigmask(attr, set)+ runs +attr->__ss = *set+
-      # * +:writable+ - the callee *writes through* this argument (an out-param), so
-      #   +writable: <arg>+ is recorded (via {#add_writable}, which drops the
-      #   pc/+$base+/sp targets that are writable or fixed for free).
-      #   @example +posix_spawnattr_init(attr)+ writes +*attr+
-      # Both deref checks are deferred to {#finalize_deferred_reads} because a
-      # +<reg>+<imm>+ pointer may only become known-mapped once a later store marks
-      # +<reg>+ writable.
+      # 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) }
@@ -406,23 +204,14 @@ module OneGadget
         nil
       end
 
-      # Forget the caller-saved registers, which the call it just accepted is free
-      # to leave in any state (see {OneGadget::ABI::CALLER_SAVED}). Keeping their
-      # entry values would let a later branch on one -- +call __close+ then
-      # +test eax, eax+ -- read as a condition on a value the caller chooses, when
-      # it is really the callee's return.
-      #
-      # The return register is set to zero rather than forgotten: these calls are
-      # accepted on the basis that they succeed, and success is what they all
-      # report that way, so a branch on the result resolves instead of ending the
-      # path. A path that needs the failing side then contradicts itself and drops.
-      #
-      # TODO: success is assumed, not required. A path that keeps going after the
-      # call fails can reach a terminal call just as well, and is dropped here
-      # only because the return is pinned. Modelling the result per function --
-      # which values it can return, and what each one requires -- would let both
-      # sides be walked, at the cost of a constraint describing the failing one.
+      # 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)
@@ -463,112 +252,6 @@ module OneGadget
         value.is_a?(OneGadget::Emulators::Lambda) && value.obj == CLOBBERED
       end
 
-      # Record a descriptor the gadget closes on its way to the terminal call, by
-      # where it is read from.
-      #
-      # Only one the caller chooses is worth recording, since which descriptor
-      # lands there decides whether the spawned shell keeps its I/O. One fixed in
-      # the code is nobody's to change, and no path that reaches a terminal call
-      # closes one, so it isn't modelled.
-      # @param [Object] fd The descriptor argument, as {#argument} returns it.
-      # @return [void]
-      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.
-      #
-      # Only a symbolic value carries a precondition the caller can arrange: an
-      # address that arrived as a literal is either one nobody can make readable
-      # or writable, or NULL. The exception is the argument a callee leaves alone
-      # when it is NULL -- passing NULL is exactly how that is asked for, so it is
-      # accepted and needs nothing of the caller.
-      # @return [Boolean] false to abort the candidate.
-      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
-
       # 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.
@@ -578,86 +261,6 @@ module OneGadget
         @libc_base ||= OneGadget::Emulators::Lambda.new('$base')
       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
-
-      # 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
-
-      # 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
-
-      # 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
-
-      # 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
-
       def register?(reg)
         registers.include?(reg)
       end
@@ -674,42 +277,17 @@ module OneGadget
         OneGadget::Emulators::Lambda.parse(arg, predefined: registers)
       end
 
-      # 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
-
       def raise_unsupported(inst, *args)
         raise OneGadget::Error::UnsupportedInstructionArgumentError, "#{inst} #{args.join(', ')}"
       end
 
-      # Resolve +sp+- and (when tracked) {#bp}-relative operands to their offset.
-      def eval_dict
-        bp ? { sp => 0, bp => 0 } : { 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

data/lib/one_gadget/emulators/register_file.rb

@@ -36,15 +36,22 @@ module OneGadget
         @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
@@ -68,20 +75,22 @@ module OneGadget
         @narrow_views.key?(name)
       end
 
-      # The part of +value+ that +name+ addresses. Only one such part can be named
-      # exactly: the low half of a register still holding what the gadget was
-      # entered with, which is what the narrower name means. Anything else is
-      # handed back whole, since no expression names half of it -- an
-      # over-approximation, and one that only ever tightens a constraint or drops
-      # the path it renders.
+      # 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 that repeated reads
-      # of an untouched register return one object: a register's value is compared
-      # by identity to tell a reassignment from the value that was there before
-      # (see {Processor#reg_based_stack}).
+      # 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))