one_gadget 1.10.0 → 2.0.0

data/lib/one_gadget/emulators/arm_family.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require 'one_gadget/emulators/lambda'
+require 'one_gadget/emulators/processor'
+
+module OneGadget
+  module Emulators
+    # Behaviour shared by the two ARM-architecture emulators, {Arm} (AArch32) and
+    # {AArch64}: the condition-code table plus the parts of the calling convention
+    # and memory model that are identical in 32- and 64-bit mode. The common base
+    # each inherits (the ARM counterpart of {X86}); everything that genuinely
+    # differs (instruction set, register width, +pc+ handling) stays in the
+    # individual classes.
+    class ArmFamily < Processor
+      # ARM condition-code suffix (the +<cc>+ in +b<cc>+ / +b.<cc>+) mapped to a
+      # shared {Conditional::RELATION} predicate. Decodes the opaque mnemonics once:
+      # +hs+/+cs+ and +lo+/+cc+ are aliases; +mi+/+pl+ (sign bit) act as signed
+      # +</+>=+. +vs+/+vc+ (overflow) have no constraint form and are absent, so a
+      # branch on them maps to +nil+ and aborts the path. (x86 uses {X86::JCC}.)
+      COND = {
+        'eq' => :eq, 'ne' => :ne,
+        'hs' => :uge, 'cs' => :uge, 'lo' => :ult, 'cc' => :ult,
+        'hi' => :ugt, 'ls' => :ule,
+        'ge' => :sge, 'lt' => :slt, 'gt' => :sgt, 'le' => :sle,
+        'mi' => :slt, 'pl' => :sge
+      }.freeze
+
+      # This arch family's flag-setting compare mnemonics, mapped to the ALU op
+      # whose result their flags reflect (see {Conditional::COMPARE_OPS}). x86 has
+      # its own {X86::COMPARES}.
+      COMPARES = { 'cmp' => :sub, 'cmn' => :add, 'tst' => :and }.freeze
+
+      # The data-processing instructions both ARM families spell the same way,
+      # mapped to the Ruby operator that folds them and renders them alike.
+      # +bic+ and +mvn+ are absent: they complement their operand first, which
+      # {#complement} turns back into one of these (see {#inst_bic}).
+      DATA_OPS = { 'and' => :&, 'orr' => :|, 'eor' => :^, 'lsl' => :<<, 'lsr' => :>> }.freeze
+      private_constant :DATA_OPS
+
+      private
+
+      # A compare whose second operand may carry a shift modifier, e.g.
+      # +cmn x0, 0x1, lsl 12+ (the immediate is 0x1000, not 0x1). Fold a constant
+      # shift into the operand; abort on any modifier not modelled, since dropping
+      # it would silently understate the constraint.
+      # @return [Boolean] false aborts the candidate.
+      def handle_compare(op, cmd)
+        ops = operands(cmd)
+        return false if ops.size > 3
+
+        rhs = operand_str(ops[1])
+        if ops.size == 3
+          rhs = shifted_operand(rhs, ops[2])
+          return false if rhs.nil?
+        end
+        record_compare(op, operand_str(ops[0]), rhs)
+      end
+
+      # Apply a constant shift modifier to an already-rendered operand.
+      # @return [String, nil] nil when the shift isn't a constant amount applied to
+      #   a known integer, which the caller treats as unmodelled.
+      # @example
+      #   shifted_operand('0x1', 'lsl 12') #=> '0x1000'
+      def shifted_operand(rhs, modifier)
+        m = modifier.match(/\A(lsl|lsr|asr)\s+(\d+)\z/)
+        return nil unless m && OneGadget::Helper.integer?(rhs)
+
+        value = Integer(rhs)
+        OneGadget::Helper.hex(m[1] == 'lsl' ? value << Integer(m[2]) : value >> Integer(m[2]))
+      end
+
+      # +add+/+sub+, shared by both families. Each allows the 2-operand shorthand,
+      # and each may carry a modifier on +op2+ -- a shift, or (aarch64) a
+      # sign-extension of its low half.
+      # @param [String] dst The destination register.
+      # @param [String] src The value added to, or the only operand given.
+      # @param [String, nil] op2 The value to add, or nil in the 2-operand form.
+      # @param [String, nil] mode A modifier applied to +op2+ (see {#modified_operand}).
+      # @return [void]
+      def inst_add(dst, src, op2 = nil, mode = nil) = arith(:+, dst, src, op2, mode)
+
+      # +sub dst, src, op2+. See {#inst_add} for the operands.
+      # @return [void]
+      def inst_sub(dst, src, op2 = nil, mode = nil) = arith(:-, dst, src, op2, mode)
+
+      # Add or subtract, and store the result.
+      #
+      # A sum of two values neither of which is known folds into no base+offset,
+      # so it is named as the operation it is -- a candidate deriving a pointer
+      # that way still says what the caller has to arrange. That is the only
+      # fallback: an offset from a known base stays a base+offset, which the rest
+      # of the emulator can resolve against tracked memory.
+      # @param [Symbol] op +:++ or +:-+.
+      # @return [void]
+      # @raise [OneGadget::Error::UnsupportedInstructionArgumentError]
+      #   When the modifier, or the result, is not one this emulator can name.
+      def arith(op, dst, src, op2, mode)
+        check_register!(dst)
+        src, op2 = shorthand(dst, src, op2)
+        lhs = value_of(src)
+        rhs = modified_operand(value_of(op2), mode) { raise_unsupported(op, dst, src, op2, mode) }
+
+        result = offset_result(op, lhs, rhs)
+        # The stack pointer has to stay an offset from itself: every tracked
+        # stack slot is keyed on it, and a candidate that reads one back after
+        # allocating a variable-size frame would be answered from the wrong
+        # place. Such a frame also puts the array a gadget builds at an address
+        # only a register the caller supplies decides, which no constraint this
+        # emulator emits states.
+        result ||= operation_result(op, lhs, rhs) unless dst == sp
+        raise_unsupported(op, dst, src, op2) if result.nil?
+
+        registers[dst] = result
+      end
+
+      # +lhs op rhs+ when the result is an offset from +lhs+'s base, which
+      # {Lambda} expresses directly. +nil+ when it is not, leaving the caller to
+      # name the operation instead.
+      # @return [Lambda, Integer, nil]
+      def offset_result(op, lhs, rhs)
+        return lhs.send(op, rhs) if rhs.is_a?(Integer)
+        # Adding a known offset to an unknown value is the same value shifted;
+        # subtracting from one is not, so only addition commutes here.
+        return rhs + lhs if op == :+ && lhs.is_a?(Integer)
+
+        nil
+      end
+
+      # +value+ with an operand modifier applied. +nil+ +mode+ is the bare
+      # operand. Yields, rather than returning, for a modifier this emulator does
+      # not model, so an unmodelled one aborts instead of being silently dropped.
+      # @example (aarch64) +add x0, x1, w2, sxtw+ -- +mode+ is +"sxtw"+
+      # @example (arm) +add r0, r1, r2, lsl 3+ -- +mode+ is +"lsl 3"+
+      # @return [Lambda, Integer]
+      def modified_operand(value, mode)
+        return value if mode.nil? || mode == 'sxtw' # a sign-extension we take whole
+
+        shifted = shifted_operand(value_str(value), mode)
+        return yield if shifted.nil?
+
+        Integer(shifted)
+      end
+
+      # Apply a data-processing instruction and store its result. Both families
+      # allow the 2-operand shorthand, so +src+ may be the only operand given.
+      # @param [String] name The mnemonic, and the {DATA_OPS} key naming its operator.
+      # @param [String] dst The destination register.
+      # @param [String] src The left operand, or the only one given (see {#shorthand}).
+      # @param [String, nil] op2 The right operand, or nil in the 2-operand form.
+      # @return [void]
+      # @raise [OneGadget::Error::UnsupportedInstructionArgumentError]
+      #   When the result is nothing this emulator can name.
+      def data_op(name, dst, src, op2)
+        check_register!(dst)
+        src, op2 = shorthand(dst, src, op2)
+        result = operation_result(DATA_OPS.fetch(name), value_of(src), value_of(op2))
+        raise_unsupported(name, dst, src, op2) if result.nil?
+
+        # A shift can push bits past the register width, which the arbitrary-
+        # precision fold above would otherwise keep.
+        registers[dst] = result.is_a?(Integer) ? result & width_mask : result
+      end
+
+      # Each {DATA_OPS} mnemonic handled the one way, since they differ only in the
+      # operator applied (see {#data_op} for the operands).
+      %w[and orr eor lsl lsr].each do |name|
+        define_method(:"inst_#{name}") { |dst, src, op2 = nil| data_op(name, dst, src, op2) }
+      end
+
+      # +bic dst, src, op2+ clears the bits +op2+ sets, which is +and+ against its
+      # complement -- the form a constraint should read as, since that complement
+      # is the mask the caller has to arrange.
+      # @param [String] dst The destination register.
+      # @param [String] src The value to clear bits of, or the only operand given.
+      # @param [String, nil] op2 The bits to clear, or nil in the 2-operand form.
+      # @return [void]
+      def inst_bic(dst, src, op2 = nil)
+        src, op2 = shorthand(dst, src, op2)
+        data_op('and', dst, src, OneGadget::Helper.hex(complement('bic', op2, dst, src, op2)))
+      end
+
+      # +mvn dst, op2+ is that complement on its own.
+      # @param [String] dst The destination register.
+      # @param [String] op2 The value to complement.
+      # @return [void]
+      def inst_mvn(dst, op2)
+        check_register!(dst)
+
+        registers[dst] = complement('mvn', op2, dst, op2)
+      end
+
+      # +op2+ with every bit flipped. Only a concrete value has a complement this
+      # emulator can name; a symbolic one aborts rather than being recorded as a
+      # mask it isn't.
+      # @param [String] name The mnemonic to report an abort against.
+      # @param [String] op2 The operand to complement.
+      # @param [Array<String>] reported The operands to name in that abort.
+      # @return [Integer] +op2+ complemented, within the register width.
+      def complement(name, op2, *reported)
+        value = value_of(op2)
+        raise_unsupported(name, *reported) unless value.is_a?(Integer)
+
+        ~value & width_mask
+      end
+
+      # Every bit of a register, for masking a result back to its width.
+      # @return [Integer]
+      def width_mask = (1 << self.class.bits) - 1
+
+      # The value of an operand. {Arm} overrides it for +pc+, whose value depends
+      # on the address of the instruction reading it.
+      # @param [String] arg The operand, as written.
+      # @return [OneGadget::Emulators::Lambda, Integer] Its current value.
+      def value_of(arg) = arg_to_lambda(arg)
+
+      # Expand a 2-operand data-processing form into its (src, op2) operands:
+      # +add dst, op2+ is shorthand for +add dst, dst, op2+, while an explicit
+      # 3-operand form is passed through unchanged.
+      # @param [String] dst The destination register, which the 2-operand form
+      #   also reads as its left operand.
+      # @param [String] src The left operand, or the right one in the 2-operand form.
+      # @param [String, nil] op2 The right operand, or nil in the 2-operand form.
+      # @return [(String, String)] The left and right operands.
+      # @example
+      #   shorthand('r0', 'r4', nil) # 2-operand: add r0, r4
+      #   #=> ['r0', 'r4']
+      #   shorthand('r0', 'r4', '8') # 3-operand: add r0, r4, 8
+      #   #=> ['r4', '8']
+      def shorthand(dst, src, op2)
+        op2.nil? ? [dst, src] : [src, op2]
+      end
+
+      # An instruction with no effect this emulator models anything of.
+      # @return [void]
+      def inst_nop(*); end
+
+      # A memory barrier orders accesses without changing any value, so a path
+      # crossing one carries on unchanged. The operand naming its scope (+dmb ish+)
+      # says which accesses, not what they hold.
+      alias inst_dmb inst_nop
+      alias inst_dsb inst_nop
+      alias inst_isb inst_nop
+
+      # A +bl+/+blx+ call: record the terminal +exec*+ target, accept a known-safe
+      # syscall wrapper, or +:fail+ to abort the candidate.
+      def inst_bl(addr)
+        return reach_terminal_call(addr) if terminal_call?(addr)
+
+        dispatch_safe_call(addr)
+      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+).
+      # Shared by +str+ (one value) and +stp+ (two).
+      # @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)
+        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
+
+      # A byte load. The address is read like any other, so what the caller has to
+      # arrange about it is recorded the same way -- but one byte of a word is not
+      # a value this emulator can name, so the register holds what a call would
+      # have left: a path that goes on to depend on it is abandoned rather than
+      # described wrongly.
+      def inst_ldrb(dst, src, index = 0)
+        inst_ldr(dst, src, index)
+        registers[dst] = clobbered_value
+      end
+
+      # +cbz+/+cbnz+ (compare-and-branch-on-zero): identical decoding in ARM and
+      # AArch64. +ops+ is +[register, target-address-hex]+, as {#operands} splits it.
+      # @param [Array<String>] ops The branch's operands.
+      # @param [Boolean] negate +false+ for +cbz+, +true+ for +cbnz+.
+      def handle_cbz(ops, negate:)
+        branch_on_zero(ops[1].to_i(16), ops[0], negate:)
+      end
+
+      # Replace register tokens that currently hold a concrete integer with that
+      # integer, so a register-indexed memory operand becomes an offset one the
+      # Lambda parser handles.
+      # @example
+      #   # with the index register currently holding 0xd8
+      #   resolve_int_regs('[r8, r2]')  #=> '[r8, 0xd8]'
+      #   resolve_int_regs('[x8, x2]')  #=> '[x8, 0xd8]'
+      def resolve_int_regs(str)
+        str.gsub(/[a-z]+\d*/) do |tok|
+          v = registers[tok] if register?(tok)
+          v.is_a?(Integer) ? OneGadget::Helper.hex(v) : tok
+        end
+      end
+    end
+  end
+end

data/lib/one_gadget/emulators/conditional.rb

@@ -0,0 +1,348 @@
+# frozen_string_literal: true
+
+require 'one_gadget/error'
+require 'one_gadget/helper'
+
+module OneGadget
+  module Emulators
+    # Shared modelling of compare instructions and conditional branches.
+    #
+    # A gadget candidate may cross a conditional branch: the fetcher stitches the
+    # actual taken/not-taken path (see {OneGadget::Fetchers::Base#candidates}), and
+    # the emulator turns the branch decision into a gadget constraint.
+    #
+    # Branches are resolved with one line of look-ahead: at the branch we record a
+    # pending decision, and on the next line we compare that line's address to the
+    # branch target to learn whether the stitched path took the branch.
+    #
+    # The including class (an {OneGadget::Emulators::Processor} subclass) must
+    # provide +registers+ and +register?+ (operand lookup), +operands(cmd)+ (the
+    # arch's operand splitter), +self.class.bits+ (32/64, for the signedness cast),
+    # and the +@flags+/+@pending+/+@constraints+ state {Processor#initialize} sets up.
+    #
+    # @example A +b.ne+ whose branch is *not* taken becomes the constraint +x2 == 0x1+
+    #   #   c7a4c: cmp  x2, 1
+    #   #   c7a50: b.ne c7a9c    # stitched path falls through (does not jump)
+    #   # => emitted gadget constraint:  x2 == 0x1
+    module Conditional
+      # Taken-semantics of each supported branch condition, keyed by a predicate
+      # named after the comparison it encodes (the LLVM +icmp+ names): a leading
+      # +u+ = unsigned, +s+ = signed. Value is +[relation, signedness]+, where
+      # signedness (+nil+/+:u+/+:s+) selects the operand cast.
+      #   :eq  :ne                equality
+      #   :ult :ule :ugt :uge     unsigned  <  <=  >  >=
+      #   :slt :sle :sgt :sge     signed    <  <=  >  >=
+      RELATION = {
+        eq: ['==', nil], ne: ['!=', nil],
+        ult: ['<', :u], ule: ['<=', :u], ugt: ['>', :u], uge: ['>=', :u],
+        slt: ['<', :s], sle: ['<=', :s], sgt: ['>', :s], sge: ['>=', :s]
+      }.freeze
+
+      # Relation under the not-taken branch.
+      NEGATE = { '==' => '!=', '!=' => '==', '>=' => '<', '<' => '>=', '>' => '<=', '<=' => '>' }.freeze
+
+      # The flag-setting compares we model, keyed by the ALU operation the compare
+      # performs -- its flags reflect that result. Each entry says whether magnitude
+      # conditions (anything beyond +eq+/+ne+) are sound afterwards (+ordered+) and
+      # names the method that renders its constraint text. An arch maps its own
+      # mnemonics onto these ops (its +COMPARES+), so adding an arch needs no change
+      # here; adding a genuinely new ALU op means one entry plus its +render_*+ method.
+      COMPARE_OPS = {
+        sub: { ordered: true,  render: :render_sub },  # subtraction: flags from  lhs - rhs
+        add: { ordered: true,  render: :render_add },  # addition:    flags from  lhs + rhs
+        and: { ordered: false, render: :render_and }   # bitwise AND: flags from  lhs & rhs (zero flag)
+      }.freeze
+
+      # A value comparison's zero literal, always hex. Pointer operands render
+      # +NULL+ (chosen by the arg resolvers); every value-context zero here is
+      # +0x0+, so a bare +0+ (and objdump's arch-specific +#0+ vs +0x0+) never leaks
+      # into a constraint.
+      ZERO = '0x0'
+      private_constant :ZERO
+
+      # Record a compare so a following conditional branch can be rendered.
+      # Normally reached through {#handle_compare}; call it directly only when an
+      # arch models a flag-setting instruction that {#handle_compare} doesn't cover.
+      # @param [Symbol] op The ALU operation the compare performs -- a {COMPARE_OPS}
+      #   key (+:sub+/+:add+/+:and+). Its flags reflect this result, which decides
+      #   both which branch conditions are expressible and how the constraint is
+      #   rendered. Each arch maps its own mnemonics to these ops (their +COMPARES+);
+      #   a new arch adds a {COMPARE_OPS} entry only for a genuinely new operation.
+      # @param [String] lhs Rendered left operand: a register's current value, or an immediate in hex.
+      # @param [String] rhs Rendered right operand.
+      # @return [true]
+      # @example Record +cmp x2, 0x1+ (subtraction), readying the next branch
+      #   record_compare(:sub, '0x1', '0x1') #=> true
+      #   # a following +b.ne+ not taken renders  0x1 == 0x1  (a stripped tautology)
+      def record_compare(op, lhs, rhs)
+        @flags = { op:, lhs:, rhs: }
+        true
+      end
+
+      # Model a compare line: record its two operands' current values under the
+      # compare's ALU op, so a following conditional branch can be rendered.
+      #
+      # Call this from +process!+ when the mnemonic is one of the arch's compares
+      # (its +COMPARES+ maps the mnemonic to the op), *before* dispatching to the
+      # +inst_*+ handlers.
+      # @param [Symbol] op The compare's ALU operation (a {COMPARE_OPS} key), which the
+      #   arch resolves from the mnemonic.
+      # @param [String] cmd Passed to the arch's +operands+ splitter, so it is whatever
+      #   that splitter expects (a full objdump line, or just its operand part).
+      # @return [true]
+      # @example Wiring in an arch's +process!+ (its +COMPARES+ holds the mnemonic map)
+      #   return handle_compare(COMPARES[mnem], cmd) if COMPARES.key?(mnem)
+      # @example What it records for +cmp x2, 1+ (x2 currently 0x30)
+      #   handle_compare(:sub, '4a1c0: cmp x2, 1') #=> true
+      #   # records op :sub, lhs = 0x30, rhs = 0x1, ready for the next branch
+      def handle_compare(op, cmd)
+        lhs, rhs = operands(cmd)
+        record_compare(op, operand_str(lhs), operand_str(rhs))
+      end
+
+      # The mnemonic of an objdump line. Use it at the top of +process!+ to decide
+      # whether a line is a compare or a branch.
+      # @param [String] cmd One objdump line.
+      # @return [String] The mnemonic, or +''+ when the line has none.
+      # @example
+      #   mnemonic('4a1c0: cmp x2, 1')           #=> 'cmp'
+      #   mnemonic('4a1d0: b.ne 4a200 <foo>')    #=> 'b.ne'
+      #   mnemonic('4a1d4: je   4a200')          #=> 'je'
+      #   mnemonic('')                           #=> ''
+      def mnemonic(cmd)
+        cmd[/\A[0-9a-f]+:\s*(\S+)/, 1] || ''
+      end
+
+      # Render an operand for a constraint: a register becomes its current value,
+      # an immediate becomes hex, anything else (a memory operand) stays as-is.
+      # {#handle_compare} uses it on each compare operand; call it yourself only
+      # when writing a bespoke +branch_on_*+ helper.
+      # @param [String] operand A single operand string from a compare/branch line.
+      # @return [String] The rendered operand.
+      # @example (assuming register +x2+ currently holds the immediate +0x1+)
+      #   operand_str('x2')       #=> '0x1'       # a register -> its current value
+      #   operand_str('0x40')     #=> '0x40'      # a hex immediate -> unchanged
+      #   operand_str('16')       #=> '0x10'      # a decimal immediate -> hex
+      #   operand_str('[sp+0x8]') #=> '[sp+0x8]'  # a memory operand -> unchanged
+      def operand_str(operand)
+        if register?(operand)
+          raise Error::ClobberedRegisterError, operand if clobbered?(registers[operand])
+
+          return value_str(registers[operand])
+        end
+
+        OneGadget::Helper.hex(Integer(operand))
+      rescue ArgumentError
+        operand
+      end
+
+      # A value as a constraint reads it: a concrete one in hex, whichever side of
+      # a compare it came from, and anything else as it renders itself.
+      # @param [Object] val The value to render.
+      # @return [String] Its constraint form.
+      # @example value_str(1) #=> '0x1', so a folded register reads like an immediate
+      def value_str(val)
+        val.is_a?(Integer) ? OneGadget::Helper.hex(val) : val.to_s
+      end
+
+      # Register a branch on the last recorded compare's flags, resolved on the next
+      # line. Call it from +handle_branch+; +cond+ is the comparison predicate and
+      # +target+ is the branch's direct destination address.
+      # @param [Symbol] cond The comparison predicate, a {RELATION} key. Each arch
+      #   first maps its own branch mnemonic to it via its adapter table.
+      # @param [Integer] target Destination address of the branch.
+      # @return [true, :fail] +:fail+ (abort the path) when it cannot be expressed
+      #   soundly: no compare was seen, or a magnitude condition follows an
+      #   equality-only compare (a {COMPARE_OPS} op with +ordered: false+).
+      # @example After +cmp x2, #1+, a following +b.ne 4a200+ (arch maps +b.ne+ to +:ne+)
+      #   branch_on_compare(:ne, 0x4a200) #=> true
+      #   # if the stitched path FALLS THROUGH (doesn't reach 0x4a200) the not-taken
+      #   # relation of +:ne+ is emitted:  x2 == 0x1 ; if it jumps there:  x2 != 0x1
+      # @example No preceding compare -> the path is unsound and is aborted
+      #   branch_on_compare(:ne, 0x4a200) #=> :fail   # when @flags is nil
+      def branch_on_compare(cond, target)
+        return :fail if @flags.nil?
+
+        rel = RELATION[cond]
+        return :fail if rel.nil?
+        # A magnitude condition needs a compare whose flags reflect a full ordering
+        # (+:sub+/+:add+); an equality-only compare (+:and+) supports just eq/ne.
+        return :fail unless COMPARE_OPS.fetch(@flags[:op])[:ordered] || %i[eq ne].include?(cond)
+
+        op = @flags[:op]
+        lhs = @flags[:lhs]
+        rhs = @flags[:rhs]
+        @pending = { target:, compare: ->(taken) { compare_triple(op, lhs, rhs, rel, taken) } }
+        true
+      end
+
+      # Register a self-contained branch that tests a register against zero. It carries
+      # its own compare, so no preceding compare is needed. +negate:+ selects the sense:
+      # +false+ branches when the register is zero, +true+ when it isn't.
+      # @param [Integer] target Destination address of the branch.
+      # @param [String] operand The tested register, as the instruction writes it;
+      #   rendered here, so a value the caller cannot reason about stops the path.
+      # @param [Boolean] negate +false+ = branch when it is zero, +true+ = when it isn't.
+      # @example aarch64 +cbz x0, 4a200+ - branch taken when +x0 == 0+
+      #   branch_on_zero(0x4a200, 'x0', negate: false) #=> true
+      #   # fall-through path emits  x0 != 0 ; taken path emits  x0 == 0
+      # @example x86 reuses it for +jrcxz+/+jecxz+/+jcxz+ (always branch-if-zero)
+      #   branch_on_zero(0x4a200, 'rcx', negate: false)
+      def branch_on_zero(target, operand, negate:)
+        reg = operand_str(operand)
+        hit = negate ? '!=' : '==' # taken (not negated) => reg == 0
+        miss = negate ? '==' : '!='
+        @pending = { target:, compare: ->(taken) { [reg, taken ? hit : miss, ZERO] } }
+        true
+      end
+
+      # Register a self-contained branch that tests a single bit of a register: also
+      # carries its own test, so no preceding compare is needed. Renders a bitmask test.
+      # @param [Integer] target Destination address of the branch.
+      # @param [String] operand The tested register, as the instruction writes it (see {#branch_on_zero}).
+      # @param [Integer] bit The bit index being tested.
+      # @param [Boolean] negate +false+ = branch when the bit is zero, +true+ = when it's set.
+      # @example aarch64 +tbz w0, #4, 4a200+ - branch taken when bit 4 of +w0+ is 0
+      #   branch_on_bit(0x4a200, 'w0', 4, negate: false) #=> true
+      #   # taken path emits  (w0 & 0x10) == 0 ; fall-through emits  (w0 & 0x10) != 0
+      def branch_on_bit(target, operand, bit, negate:)
+        reg = operand_str(operand)
+        mask = OneGadget::Helper.hex(1 << bit)
+        hit = negate ? '!=' : '=='
+        miss = negate ? '==' : '!='
+        @pending = { target:, compare: ->(taken) { ["(#{reg} & #{mask})", taken ? hit : miss, ZERO] } }
+        true
+      end
+
+      # Resolve the pending branch using +cmd+'s address: if it equals the branch
+      # target the stitched path took the branch, else it fell through. On
+      # resolution the rendered relation is appended to the gadget's constraints.
+      # Must be called at the top of +process!+ for every line (a no-op when nothing
+      # is pending), so the branch registered on the previous line sees this line's address.
+      # @param [String] cmd The current objdump line.
+      # @example The fixed first line of every arch's +process!+
+      #   def process!(cmd)
+      #     resolve_pending_branch(cmd)
+      #     ...
+      #   end
+      #   # if the previous line did +branch_on_compare(:ne, 0x4a200)+ and this
+      #   # +cmd+ sits at 0x4a200, the branch was taken; otherwise it fell through
+      def resolve_pending_branch(cmd)
+        return if @pending.nil?
+
+        taken = branch_addr(cmd) == @pending[:target]
+        triple = @pending[:compare].call(taken)
+        @pending = nil
+        @constraints << [:cmp, triple]
+        return if satisfiable?(comparisons_on(triple.first))
+
+        raise Error::InfeasiblePathError, "cannot hold together: #{triple.first}"
+      end
+
+      # Every comparison recorded so far on +expr+, the left side as rendered.
+      # Matching on that text is what makes this sound: the renderer substitutes
+      # each register's current value, so two constraints printing the same left
+      # side really are about the same tracked value (and a differing signedness
+      # cast is part of that text, keeping incomparable ones apart).
+      def comparisons_on(expr)
+        @constraints.filter_map { |type, obj| obj if type == :cmp && obj.first == expr }
+      end
+
+      # Whether some value satisfies every comparison in +triples+ at once, by
+      # intersecting the range each one allows. Comparisons against anything but
+      # an integer are ignored rather than guessed at, so an undecidable one never
+      # makes a path look impossible.
+      # @param [Array<(String, String, String)>] triples Comparisons on one expression.
+      # @return [Boolean]
+      # @example  x != 0x0  together with  x == 0x0  #=> false
+      def satisfiable?(triples)
+        low = nil
+        high = nil
+        excluded = []
+        triples.each do |_expr, op, rhs|
+          next unless OneGadget::Helper.integer?(rhs)
+
+          value = Integer(rhs)
+          case op
+          when '=='
+            low = [low, value].compact.max
+            high = [high, value].compact.min
+          when '!=' then excluded << value
+          when '<' then high = [high, value - 1].compact.min
+          when '<=' then high = [high, value].compact.min
+          when '>' then low = [low, value + 1].compact.max
+          when '>=' then low = [low, value].compact.max
+          end
+        end
+        return false if low && high && (low > high || (low == high && excluded.include?(low)))
+
+        true
+      end
+
+      private
+
+      # Render the constraint a taken/not-taken branch imposes on the recorded
+      # compare: flip the operator via {NEGATE} on the not-taken edge, prefix the
+      # signedness cast, then defer to the op's +render_*+ method (see {COMPARE_OPS}).
+      # Raises +KeyError+ if +op+ isn't a known {COMPARE_OPS} entry.
+      # @param [Symbol] op The compare's ALU operation (a {COMPARE_OPS} key).
+      # @param [Array(String, Symbol)] rel The +[operator, signedness]+ from {RELATION}.
+      # @example +b.ne+ (not taken) after +cmp x2, 1+ -- a +:sub+ compare, 64-bit
+      #   compare_constraint(:sub, 'x2', '0x1', ['!=', nil], false) #=> 'x2 == 0x1'
+      # @example +jne+ (taken) after +test eax, eax+ -- an +:and+ compare
+      #   compare_constraint(:and, 'eax', 'eax', ['!=', nil], true) #=> 'eax != 0'
+      def compare_triple(op, lhs, rhs, rel, taken)
+        operator, sign = rel
+        operator = NEGATE[operator] unless taken
+        cast = sign ? "(#{sign}#{self.class.bits})" : ''
+        __send__(COMPARE_OPS.fetch(op)[:render], cast, lhs, rhs, operator, sign)
+      end
+
+      # Subtraction (+:sub+): a direct comparison of the two operands.
+      def render_sub(cast, lhs, rhs, op, _sign)
+        rhs = ZERO if rhs == '0'
+        ["#{cast}#{lhs}", op, rhs]
+      end
+
+      # Addition (+:add+): the flags reflect +lhs + rhs+ compared against 0 -- but
+      # only for a signed or equality condition. An *unsigned* condition reads the
+      # carry out of the addition instead, which holds over a whole range of +lhs+,
+      # not just the one value making the sum zero: the carry is set exactly when
+      # +lhs + rhs+ wraps, i.e. when +lhs >= -rhs+. So the condition is +lhs+
+      # against +-rhs+, the form the subtractive compares already produce.
+      # @example glibc's "the syscall didn't return -errno" check, +cmn x0, 0x1000+
+      #   followed by a not-taken +b.hi+, is +(u64)x0 <= 0xfffffffffffff000+ --
+      #   satisfied by x0 == 0, which "(x0 + 0x1000) <= 0" would wrongly exclude.
+      def render_add(cast, lhs, rhs, op, sign)
+        return ["#{cast}(#{lhs} + #{rhs})", op, ZERO] unless sign == :u && negatable?(rhs)
+
+        ["#{cast}#{lhs}", op, OneGadget::Helper.hex((-Integer(rhs)) & mask)]
+      end
+
+      # Bitwise AND (+:and+): a bitmask test; identical operands collapse to a plain zero test.
+      def render_and(_cast, lhs, rhs, op, _sign)
+        [lhs == rhs ? lhs : "(#{lhs} & #{rhs})", op, ZERO]
+      end
+
+      # Whether +rhs+ can be moved to the other side of an unsigned add-compare.
+      # A zero addend never carries, so the condition doesn't reduce to a bound and
+      # the sum form is kept.
+      def negatable?(rhs)
+        OneGadget::Helper.integer?(rhs) && !Integer(rhs).zero?
+      end
+
+      # All-ones for this architecture's word size.
+      def mask
+        (1 << self.class.bits) - 1
+      end
+
+      # The address of an objdump line, used to tell whether the pending branch
+      # was taken.
+      # @example
+      #   branch_addr('4a200: nop') #=> 0x4a200
+      def branch_addr(cmd)
+        cmd[/\A\s*([0-9a-f]+):/, 1].to_i(16)
+      end
+    end
+  end
+end

data/lib/one_gadget/emulators/i386.rb

@@ -25,8 +25,8 @@ module OneGadget
       # We need to fetch the stack slots reference to current 'esp'
       # but not original 'esp'.
       # So we need to evaluate the offset of current esp first.
-      # @param [Integer] idx
-      # @return [Lambda, Integer]
+      # @param [Integer] idx The 0-based index of the argument.
+      # @return [Lambda, Integer] The value on the stack slot holding the +idx+-th argument.
       def argument(idx)
         cur_top = registers['esp'].evaluate('esp' => 0)
         sp_based_stack[cur_top + idx * 4]