one_gadget 2.0.0 → 2.1.1

data/lib/one_gadget/builds/libc-2.43-b50ceafbd17dc6bceee344a66671c7eaa152bef4.rb

@@ -15,15 +15,30 @@ require 'one_gadget/gadget'
 # <https://bugs.launchpad.net/ubuntu/+source/glibc/+bugs>.
 
 build_id = File.basename(__FILE__, '.rb').split('-').last
+OneGadget::Gadget.add(build_id, 310192,
+                      constraints: ["readable: x22", "x0 != 0x1", "{\"sh\", \"-c\", \"--\", x21, ...} is a valid argv", "sp+0x218 == NULL || (u16)[sp+0x218] == 0x0"],
+                      effect: "posix_spawn(sp+0xc, \"/bin/sh\", 0, sp+0x218, sp+0x50, environ)")
 OneGadget::Gadget.add(build_id, 310192,
                       constraints: ["readable: x22", "x0 == 0x1", "{\"sh\", \"-c\", \"--\", x21, ...} is a valid argv", "sp+0x218 == NULL || (u16)[sp+0x218] == 0x0"],
                       effect: "posix_spawn(sp+0xc, \"/bin/sh\", 0, sp+0x218, sp+0x50, environ)")
+OneGadget::Gadget.add(build_id, 310196,
+                      constraints: ["readable: x22", "x0 != 0x1", "{\"sh\", \"-c\", \"--\", x21, ...} is a valid argv", "sp+0x218 == NULL || (u16)[sp+0x218] == 0x0"],
+                      effect: "posix_spawn(sp+0xc, \"/bin/sh\", 0, sp+0x218, sp+0x50, environ)")
 OneGadget::Gadget.add(build_id, 310196,
                       constraints: ["readable: x22", "x0 == 0x1", "{\"sh\", \"-c\", \"--\", x21, ...} is a valid argv", "sp+0x218 == NULL || (u16)[sp+0x218] == 0x0"],
                       effect: "posix_spawn(sp+0xc, \"/bin/sh\", 0, sp+0x218, sp+0x50, environ)")
+OneGadget::Gadget.add(build_id, 310200,
+                      constraints: ["readable: x22", "x0 != 0x1", "{\"sh\", \"-c\", \"--\", x21, ...} is a valid argv", "sp+0x218 == NULL || (u16)[sp+0x218] == 0x0"],
+                      effect: "posix_spawn(sp+0xc, \"/bin/sh\", 0, sp+0x218, sp+0x50, environ)")
 OneGadget::Gadget.add(build_id, 310200,
                       constraints: ["readable: x22", "x0 == 0x1", "{\"sh\", \"-c\", \"--\", x21, ...} is a valid argv", "sp+0x218 == NULL || (u16)[sp+0x218] == 0x0"],
                       effect: "posix_spawn(sp+0xc, \"/bin/sh\", 0, sp+0x218, sp+0x50, environ)")
+OneGadget::Gadget.add(build_id, 310208,
+                      constraints: ["readable: x22", "{\"sh\", \"-c\", \"--\", x21, ...} is a valid argv", "sp+0x218 == NULL || (u16)[sp+0x218] == 0x0"],
+                      effect: "posix_spawn(sp+0xc, \"/bin/sh\", 0, sp+0x218, sp+0x50, environ)")
+OneGadget::Gadget.add(build_id, 310212,
+                      constraints: ["readable: x22", "{\"sh\", \"-c\", \"--\", x21, ...} is a valid argv", "sp+0x218 == NULL || (u16)[sp+0x218] == 0x0"],
+                      effect: "posix_spawn(sp+0xc, \"/bin/sh\", 0, sp+0x218, sp+0x50, environ)")
 OneGadget::Gadget.add(build_id, 310216,
                       constraints: ["readable: x22", "{\"sh\", \"-c\", \"--\", x21, ...} is a valid argv", "sp+0x218 == NULL || (u16)[sp+0x218] == 0x0"],
                       effect: "posix_spawn(sp+0xc, \"/bin/sh\", 0, sp+0x218, sp+0x50, environ)")

data/lib/one_gadget/emulators/aarch64.rb

@@ -19,6 +19,8 @@ module OneGadget
       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)
         cmd = cmd.gsub(/#-?(0x)?[0-9a-f]+/) { |v| v[1..] }
@@ -27,8 +29,7 @@ module OneGadget
         return handle_branch(mnem, cmd) != :fail if branch_mnem?(mnem)
 
         inst, args = parse(cmd)
-        sym = :"inst_#{inst.inst}"
-        __send__(sym, *args) != :fail
+        __send__(inst.handler, *args) != :fail
       end
 
       # Supported instruction set.
@@ -61,6 +62,7 @@ module OneGadget
 
       # A landing pad marks where an indirect branch may arrive; nothing about the
       # state changes at one.
+      # @return [void]
       alias inst_bti inst_nop
 
       # Return the argument value of calling a function.
@@ -158,6 +160,7 @@ module OneGadget
 
       class << self
         # AArch64 is 64-bit.
+        # @return [Integer]
         def bits
           64
         end

data/lib/one_gadget/emulators/amd64.rb

@@ -9,6 +9,7 @@ module OneGadget
     class Amd64 < X86
       class << self
         # Bits.
+        # @return [Integer]
         def bits
           64
         end

data/lib/one_gadget/emulators/arm.rb

@@ -28,11 +28,15 @@ module OneGadget
       end
 
       # Memoized bytes of +file+ (the target libc), shared across emulator instances.
+      # @param [String] file Path to the target libc.
+      # @return [String] Its bytes.
       def self.file_data(file)
         (@file_data ||= {})[file] ||= File.binread(file)
       end
 
       # @see OneGadget::Emulators::AArch64#process!
+      # @param [String] cmd One line from result of objdump.
+      # @return [Boolean] If successfully processed.
       def process!(cmd)
         resolve_pending_branch(cmd)
         line = cmd.strip
@@ -45,7 +49,7 @@ module OneGadget
         return __send__(:"inst_#{mnem}", rest) != :fail if %w[push pop].include?(mnem)
 
         inst, args = parse(body)
-        __send__(:"inst_#{inst.inst}", *args) != :fail
+        __send__(inst.handler, *args) != :fail
       end
 
       # The flag-setting spelling of an instruction we model, which differs from
@@ -101,17 +105,16 @@ module OneGadget
       end
 
       # Settle Thumb vs A32 from a whole candidate, before any of it is emulated.
-      # {#track_mode} can only learn from lines already seen, so the FIRST
-      # instruction is judged on no evidence at all -- and when that instruction
-      # reads +pc+, the bias it picks decides an address the constraints go on to
-      # name. Applying the same evidence up front removes that dependence on
-      # whatever happened to be processed first.
-      #
-      # A32 is left alone: it shows neither a width suffix nor a 2-byte stride, so
-      # a genuinely A32 candidate keeps the whole-word bias. A single-instruction
-      # Thumb candidate offers no evidence either and is no better served than
-      # before.
+      # {#track_mode} learns only from lines already seen, so the first instruction
+      # would otherwise be judged on no evidence -- and when it reads +pc+, that
+      # decides an address the constraints go on to name.
       # @param [Array<String>] lines The candidate's objdump lines.
+      # @return [void]
+      # @example A 2-byte stride settles it as Thumb, where +pc+ reads four ahead
+      #   of the instruction rather than eight.
+      #   note_instruction_set(['4a1c0: ldr r0, [pc, #8]', '4a1c2: add r0, pc'])
+      #   process('4a1c2: mov r0, pc')
+      #   registers['r0'] #=> $base+0x4a1c6
       def note_instruction_set(lines)
         return if @thumb
 
@@ -133,12 +136,6 @@ module OneGadget
         @prev_addr = @cur_addr
       end
 
-      # Split an objdump line into its instruction body and the literal-pool address
-      # embedded in the trailing +@+ comment (used by PC-relative +ldr+).
-      # @return [(String, Integer?)] The instruction body, and the literal address (or +nil+).
-      # @example
-      #   split_line('2c626: ldr r2, [pc, #128] @ (2c6a8 <x>)')
-      #   #=> ['ldr r2, [pc, #128]', 0x2c6a8]
       # The instruction body a line carries, in the plain form the generic parser
       # expects, and the literal-pool address it points at. Both are decided by the
       # text alone (see {Processor.line_memo}).
@@ -151,9 +148,20 @@ module OneGadget
         end
       end
 
+      # Split an objdump line into its instruction body and the literal-pool address
+      # embedded in the trailing +@+ comment (used by PC-relative +ldr+).
+      # @return [(String, Integer?)] The instruction body, and the literal address (or +nil+).
+      # @example The same load, as objdump writes it from an ELF and from bytes --
+      #   it states the address differently when it cannot name what is there.
+      #   split_line('2c626: ldr r2, [pc, #128] @ (2c6a8 <x>)')
+      #   #=> ['ldr r2, [pc, #128]', 0x2c6a8]
+      #   split_line('2c626: ldr r2, [pc, #128] @ (0x2c6a8)')
+      #   #=> ['ldr r2, [pc, #128]', 0x2c6a8]
+      #   split_line('2c626: ldr.w r2, [pc, #128] @ 2c6a8')
+      #   #=> ['ldr.w r2, [pc, #128]', 0x2c6a8]
       def split_line(line)
         body = line.sub(/\A[0-9a-f]+:\s*/, '')
-        literal = body[/@\s*\(?([0-9a-f]+)\s/, 1]&.to_i(16)
+        literal = body[/@\s*\(?(?:0x)?([0-9a-f]+)(?:[\s)]|\z)/, 1]&.to_i(16)
         # Strip a trailing comment. The marker is whitespace-prefixed, which avoids
         # eating the +@@+ inside symbol names such as +<execve@@GLIBC_2.4>+.
         [body.sub(/\s+[@;].*\z/, '').strip, literal]
@@ -297,6 +305,7 @@ module OneGadget
 
       class << self
         # ARM (32-bit) is 32-bit.
+        # @return [Integer]
         def bits
           32
         end

data/lib/one_gadget/emulators/arm_family.rb

@@ -13,10 +13,13 @@ module OneGadget
     # 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}.)
+      # shared {Conditional::RELATION} predicate. (x86 uses {X86::JCC}.)
+      # @example Aliases decode alike, the sign bit reads as a signed comparison,
+      #   and overflow has no constraint form -- a branch on it aborts the path.
+      #   COND['hs'] #=> :uge
+      #   COND['cs'] #=> :uge
+      #   COND['mi'] #=> :slt
+      #   COND['vs'] #=> nil
       COND = {
         'eq' => :eq, 'ne' => :ne,
         'hs' => :uge, 'cs' => :uge, 'lo' => :ult, 'cc' => :ult,
@@ -69,6 +72,23 @@ module OneGadget
         OneGadget::Helper.hex(m[1] == 'lsl' ? value << Integer(m[2]) : value >> Integer(m[2]))
       end
 
+      # +op2+ with the modifier this family may spell on it folded in. Yields for a
+      # modifier it does not model, so an unmodelled one aborts the candidate
+      # instead of being silently dropped.
+      # @param [String] op2 The operand the modifier applies to.
+      # @param [String, nil] mode The modifier, as written -- +nil+ for none.
+      # @return [String] The operand {Processor#arith} then reads.
+      # @example (aarch64, +x2+ holding +0x1+) A constant shift folds in, a
+      #   sign-extension is taken whole, and a rotate is not modelled.
+      #   modified_operand('x2', 'lsl 3')            #=> '0x8'
+      #   modified_operand('x2', 'sxtw')             #=> 'x2'
+      #   modified_operand('x2', 'ror 3') { :abort } #=> :abort
+      def modified_operand(op2, mode)
+        return op2 if mode.nil? || mode == 'sxtw'
+
+        shifted_operand(value_str(value_of(op2)), mode) || yield
+      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.
@@ -77,94 +97,22 @@ module OneGadget
       # @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)
+      def inst_add(dst, src, op2 = nil, mode = nil)
+        arith(:+, dst, src, modified_operand(op2, mode) { raise_unsupported(:+, dst, src, op2, mode) })
       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.
+      # +sub dst, src, op2+. See {#inst_add} for the operands.
       # @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
+      def inst_sub(dst, src, op2 = nil, mode = nil)
+        arith(:-, dst, src, modified_operand(op2, mode) { raise_unsupported(:-, dst, src, op2, mode) })
       end
 
       # Each {DATA_OPS} mnemonic handled the one way, since they differ only in the
-      # operator applied (see {#data_op} for the operands).
+      # operator applied (see {Processor#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) }
+        define_method(:"inst_#{name}") do |dst, src, op2 = nil|
+          data_op(DATA_OPS.fetch(name), dst, src, op2, name:)
+        end
       end
 
       # +bic dst, src, op2+ clears the bits +op2+ sets, which is +and+ against its
@@ -176,7 +124,8 @@ module OneGadget
       # @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)))
+        data_op(DATA_OPS.fetch('and'), dst, src,
+                OneGadget::Helper.hex(complement('bic', op2, dst, src, op2)), name: 'and')
       end
 
       # +mvn dst, op2+ is that complement on its own.
@@ -189,51 +138,6 @@ module OneGadget
         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.
@@ -249,21 +153,6 @@ module OneGadget
         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
@@ -281,20 +170,6 @@ module OneGadget
       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

@@ -11,10 +11,6 @@ module OneGadget
     # 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),
@@ -27,8 +23,11 @@ module OneGadget
     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.
+      # +u+ = unsigned, +s+ = signed.
+      # @example The value is the relation, and the cast its operands take.
+      #   RELATION[:eq]  #=> ['==', nil]
+      #   RELATION[:ult] #=> ['<', :u]
+      #   RELATION[:sge] #=> ['>=', :s]
       #   :eq  :ne                equality
       #   :ult :ule :ugt :uge     unsigned  <  <=  >  >=
       #   :slt :sle :sgt :sge     signed    <  <=  >  >=
@@ -42,11 +41,12 @@ module OneGadget
       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.
+      # performs. An arch maps its own mnemonics onto these (its +COMPARES+), so
+      # adding one needs no change here.
+      # @example Whether magnitude conditions are sound after it, and what renders
+      #   its constraint text.
+      #   COMPARE_OPS[:sub] #=> { ordered: true, render: :render_sub }
+      #   COMPARE_OPS.keys  #=> [:sub, :add, :and]
       COMPARE_OPS = {
         sub: { ordered: true,  render: :render_sub },  # subtraction: flags from  lhs - rhs
         add: { ordered: true,  render: :render_add },  # addition:    flags from  lhs + rhs
@@ -56,9 +56,9 @@ module OneGadget
       # 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.
+      # into a constraint. Recorded here and read back by {Constraints}, whose drop
+      # rules recognise a compare against zero by it.
       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
@@ -188,6 +188,7 @@ module OneGadget
       #   # 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)
+      # @return [true] Registering the branch is how the line is handled.
       def branch_on_zero(target, operand, negate:)
         reg = operand_str(operand)
         hit = negate ? '!=' : '==' # taken (not negated) => reg == 0
@@ -205,6 +206,7 @@ module OneGadget
       # @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
+      # @return [true] Registering the branch is how the line is handled.
       def branch_on_bit(target, operand, bit, negate:)
         reg = operand_str(operand)
         mask = OneGadget::Helper.hex(1 << bit)
@@ -227,6 +229,9 @@ module OneGadget
       #   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
+      # @return [void]
+      # @raise [OneGadget::Error::InfeasiblePathError]
+      #   When the resolved relation cannot hold with the ones already recorded.
       def resolve_pending_branch(cmd)
         return if @pending.nil?
 
@@ -244,6 +249,8 @@ module OneGadget
       # 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).
+      # @param [String] expr The left side, as rendered.
+      # @return [Array<(String, String, String)>] The comparisons recorded on it.
       def comparisons_on(expr)
         @constraints.filter_map { |type, obj| obj if type == :cmp && obj.first == expr }
       end
@@ -304,15 +311,14 @@ module OneGadget
         ["#{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.
+      # Addition (+:add+): the flags reflect +lhs + rhs+ against 0, except under an
+      # unsigned condition, which reads the carry instead -- set exactly when the
+      # sum wraps, that is when +lhs >= -rhs+.
+      # @example Read as an equality, then unsigned -- the second is glibc's "the
+      #   syscall didn't return -errno" check, which +x0 == 0+ satisfies and
+      #   +(x0 + 0x1000) <= 0+ would wrongly exclude.
+      #   render_add(nil, 'x0', '0x1000', :ne, nil) #=> ['(x0 + 0x1000)', :ne, '0x0']
+      #   render_add(nil, 'x0', '0x1000', :le, :u)  #=> ['x0', :le, '0xfffffffffffff000']
       def render_add(cast, lhs, rhs, op, sign)
         return ["#{cast}(#{lhs} + #{rhs})", op, ZERO] unless sign == :u && negatable?(rhs)