one_gadget 1.10.0 → 2.1.0

data/lib/one_gadget/fetchers/argument_resolution.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+module OneGadget
+  module Fetchers
+    # What a reached +exec+/+posix_spawn+ call requires of its caller. Reads the
+    # arguments the emulator left, decides whether each is something a caller can
+    # arrange -- a +"/bin/sh"+ pointer, an argv array that is already valid or can
+    # be built in place, an acceptable envp -- and states what is left as the
+    # gadget's constraints. Anything it cannot describe drops the candidate rather
+    # than reporting a gadget that would not run. Mixed into {Base}.
+    module ArgumentResolution
+      private
+
+      # Generating constraints for being a valid gadget.
+      # @param [OneGadget::Emulators::Processor] processor The processor after executing the gadgets.
+      # @return [Hash{Symbol => Array<String>, String}?]
+      #   The options to create a {OneGadget::Gadget::Gadget} object.
+      #   Keys might be:
+      #   1. constraints: Array<String> List of constraints.
+      #   2. effect: String Result function call of this gadget.
+      #   If the constraints can never be satisfied, +nil+ is returned.
+      def resolve(processor)
+        call = processor.registers[processor.pc].to_s
+        return resolve_posix_spawn(processor) if call.include?('posix_spawn')
+        return resolve_execve(processor) if call.include?('execve')
+
+        resolve_execl(processor) if call.include?('execl')
+      end
+
+      def resolve_execve(processor)
+        arg0, arg1, arg2 = (0..2).map { |i| processor.argument(i) }
+        res = resolve_execve_args(processor, arg0, arg1, arg2)
+        return nil if res.nil?
+
+        { constraints: res[:constraints], effect: %(execve("/bin/sh", #{arg1}, #{res[:envp]})) }
+      end
+
+      def resolve_execve_args(processor, arg0, arg1, arg2, allow_null_argv: true)
+        return unless str_bin_sh?(arg0.to_s)
+
+        # arg1 == NULL || [arg1] == NULL
+        # arg2 == NULL || [arg2] == NULL || arg[2] == envp
+        cons = processor.constraints
+        con = check_argv(processor, arg1, allow_null_argv)
+        cons << con unless con.nil?
+        return nil unless cons.all?
+
+        envp = 'environ'
+        return nil unless check_envp(processor, arg2) do |c|
+          cons << c
+          envp = arg2
+        end
+
+        { constraints: cons, envp: }
+      end
+
+      # Generate the +argv+-related constraint for an +exec*+ call.
+      #
+      # Terminology shared by all the +argv+ helpers below:
+      # * +argv_ptr+ - the *pointer to* the argv array, i.e. the emulated content of the register passed
+      #   as +argv+ ({OneGadget::Emulators::Processor#argument}), kept as the emulator produced it.
+      #   Examples: +rsi+, +rsp+0x10+, +[rbp-0x8]+, a global-variable reference, or a bare integer.
+      # * +argv+ - the array *pointed to* by +argv_ptr+: its dereferenced entries
+      #   +[argv[0], argv[1], argv[2], argv[3]]+, each already converted to a string.
+      #
+      # @param [OneGadget::Emulators::Processor] processor The processor state at the call site.
+      # @param [OneGadget::Emulators::Lambda, Integer] argv_ptr The pointer to the argv array. See above.
+      # @param [Boolean] allow_null
+      #   Whether +argv_ptr+ itself may be +NULL+ (true for +execve+, false for +posix_spawn+).
+      # @return [String, nil, false] How {#resolve_execve_args} should treat this argv:
+      #   a +String+ is a constraint it must add; +nil+ means the argv is already
+      #   valid so no constraint is needed; +false+ means the argv can never launch
+      #   a shell (e.g. a fixed noexec option), which it consumes as an
+      #   unsatisfiable constraint and drops the gadget.
+      def check_argv(processor, argv_ptr, allow_null)
+        argv_ptr = resolve_stack_deref(processor, argv_ptr)
+        return check_stack_argv(processor, argv_ptr, allow_null) if resolvable_stack(processor, argv_ptr)
+
+        check_nonstack_argv(argv_ptr, allow_null)
+      end
+
+      # Whether resolving +lmda+'s target via tracked memory is worth attempting,
+      # as opposed to the plain opaque "==NULL || is a valid .." form
+      # ({#check_nonstack_argv}/the envp equivalent). Always true for the arch's
+      # dedicated stack/frame pointer. For anything else, only when element
+      # 0 -- what {#argv_already_valid?}/{#generate_argv_with_sh} branch on --
+      # was actually written within this candidate.
+      # @example element 0 tracked -- resolvable
+      #   reg tracked (element 0), reg+0x8 tracked (element 1) => resolvable
+      # @example a later, unrelated write must not trigger array resolution
+      #   reg+0x10 (element 2) tracked, reg/reg+0x8 (elements 0/1) untracked
+      #   => not resolvable; falls back to the opaque form instead of a garbled array
+      # @param [OneGadget::Emulators::Processor] processor
+      # @param [OneGadget::Emulators::Lambda, Integer] lmda A pointer operand. A
+      #   concrete address is never resolvable: nothing was tracked against it.
+      # @return [Hash{Integer => OneGadget::Emulators::Lambda}, nil]
+      def resolvable_stack(processor, lmda)
+        return nil unless lmda.is_a?(OneGadget::Emulators::Lambda)
+
+        stack, offset = processor.resolve_address(lmda)
+        return nil unless stack
+        return stack if lmda.deref_count.zero? && OneGadget::ABI.stack_register?(lmda.obj)
+
+        stack if stack.key?(offset)
+      end
+
+      # Handle the case where +argv_ptr+ points into memory this candidate wrote,
+      # so the +argv+ entries can be read off it.
+      # @param [OneGadget::Emulators::Lambda] argv_ptr The pointer to the argv array. See {#check_argv}.
+      # @return [String, nil, false] The same three-way contract as {#check_argv},
+      #   which returns this value unchanged: a constraint, +nil+ (already valid),
+      #   or +false+ (drop the gadget).
+      def check_stack_argv(processor, argv_ptr, allow_null)
+        stack, offset = processor.resolve_address(argv_ptr)
+        # A stack register we don't track a stack for (the frame pointer):
+        # fall back to treating it as an opaque pointer.
+        return check_nonstack_argv(argv_ptr, allow_null) if stack.nil?
+
+        argv = (0..3).map { |i| stack[offset + processor.class.bits / 8 * i].to_s }
+
+        # A shell spawned with a fixed "noexec" option never runs a command, so
+        # drop the gadget (see this method's @return for the +false+ contract).
+        return false if noexec_shell_argv?(argv)
+
+        # if argv is already valid, no constraints are needed! (but probably won't happen :p)
+        return if argv_already_valid?(argv)
+
+        return generate_argv_with_sh(argv) if global_var?(argv[0])
+
+        generate_argv_without_sh(argv_ptr, argv, allow_null)
+      end
+
+      # Whether the array is usable as it stands: an empty argv, or one whose only
+      # entry is a libc global.
+      def argv_already_valid?(argv)
+        argv[0] == '0' || (global_var?(argv[0]) && argv[1] == '0')
+      end
+
+      # The constraint for an argv whose first entry libc has already filled in
+      # with the shell's own name, leaving the caller to arrange the rest.
+      def generate_argv_with_sh(argv)
+        # argv[0] is not controlled by the user, argv[0] probably is "/bin/sh" or "sh" (but actually, the content of
+        # argv[0] doesn't quite matter, just need to make sure it's readable)
+        # So far (I checked glibc 2.37), we can make argv to be {"/bin/sh", sth, NULL} or {"sh", "-c", sth, NULL}
+        # TODO: We need to update this when the above assumption is no longer true
+        if argv[2] == '0' && !global_var?(argv[1])
+          "#{argv[1]} == NULL || {\"/bin/sh\", #{argv[1]}, NULL} is a valid argv"
+        else
+          argv_gte3 = argv[3] == '0' ? 'NULL' : "#{argv[3]}, ..."
+          if global_var?(argv[1])
+            # A leading "sh -c" whose fixed elements (e.g. "-c", the "--" separator)
+            # are libc globals -- resolve them so the controllable command operand
+            # stands out (e.g. {"sh", "-c", "--", x21, ...}).
+            "{\"sh\", #{resolve_argv_element(argv[1])}, #{resolve_argv_element(argv[2])}, #{argv_gte3}} is a valid argv"
+          else
+            "#{argv[1]} == NULL || {\"sh\", #{argv[1]}, #{argv[2]}, #{argv_gte3}} is a valid argv"
+          end
+        end
+      end
+
+      # @param [String] argv_ptr The pointer to the argv array. See {#check_argv}.
+      # @param [Array<String>] argv The argv entries +argv_ptr+ points to, i.e. +[argv[0], .., argv[3]]+.
+      def generate_argv_without_sh(argv_ptr, argv, allow_null)
+        argv_cons = "{#{argv[0]}"
+        (1..argv.length - 1).each do |i|
+          if argv[i] == '0'
+            argv_cons += ', NULL'
+            break
+          elsif global_var?(argv[i])
+            # A fixed libc-global entry (e.g. "-c", "--") -- show its true content.
+            argv_cons += ", #{resolve_argv_element(argv[i])}"
+          else
+            argv_cons += ", #{argv[i]}"
+          end
+        end
+        argv_cons += ', ...' unless argv_cons.end_with?('NULL')
+        argv_cons += '} is a valid argv'
+
+        if allow_null && argv.all? { |a| OneGadget::ABI.stack_register?(a) }
+          # If libc writes something into the stack, argv_ptr cannot be NULL.
+          # TODO: Find a better way to check can argv_ptr be NULL
+          "#{argv_ptr} == NULL || #{argv[0]} == NULL || #{argv_cons}"
+        else
+          "#{argv[0]} == NULL || #{argv_cons}"
+        end
+      end
+
+      # Whether +argv+ invokes the shell with a fixed option word that disables
+      # command execution. execve's program is always "/bin/sh", so +argv[1]+ is
+      # that shell's option word; a libc-global bundle carrying the noexec flag
+      # there yields a shell that reaches execve yet can never run a command --
+      # a false positive to drop.
+      # @param [Array<String>] argv The resolved argv entries. See {#check_stack_argv}.
+      # @return [Boolean]
+      # @example decided by argv[1]'s libc-global content (via global_str_content)
+      #   # content "-nc" carries bash's noexec 'n' => true;
+      #   # "-c" runs the command => false; a non-global (attacker) word => false
+      def noexec_shell_argv?(argv)
+        opt = global_str_content(argv[1])
+        !opt.nil? && opt.match?(/\A-[a-zA-Z]*n[a-zA-Z]*\z/)
+      end
+
+      # Handle the case where +argv_ptr+ is not a plain stack pointer (e.g. a register or global variable).
+      # @param [String] argv_ptr The pointer to the argv array. See {#check_argv}.
+      def check_nonstack_argv(argv_ptr, allow_null)
+        if allow_null
+          "[#{argv_ptr}] == NULL || #{argv_ptr} == NULL || #{argv_ptr} is a valid argv"
+        else
+          "[#{argv_ptr}] == NULL || #{argv_ptr} is a valid argv"
+        end
+      end
+
+      # If +ptr+ is a single dereference of a tracked stack slot, resolve it to
+      # that slot's own tracked value so the rest of argv/envp resolution can
+      # treat it like a bare register instead of an opaque pointer.
+      # @param [OneGadget::Emulators::Processor] processor
+      # @param [OneGadget::Emulators::Lambda, Integer] ptr An argv_ptr/envp_ptr.
+      # @return [OneGadget::Emulators::Lambda, Integer] +ptr+, or the value it
+      #   resolves to when it simplifies.
+      # @example a tracked slot resolves to its source register
+      #   # mov [ebp-0x30], ecx   (earlier in the same candidate)
+      #   resolve_stack_deref(processor, Lambda.parse('[ebp-0x30]')) #=> the ecx lambda
+      # @example an untracked slot is a no-op
+      #   resolve_stack_deref(processor, Lambda.parse('[ebp-0x40]')) #=> that same lambda
+      def resolve_stack_deref(processor, ptr)
+        return ptr unless ptr.is_a?(OneGadget::Emulators::Lambda) && ptr.deref_count == 1 &&
+                          OneGadget::ABI.stack_register?(ptr.obj)
+
+        stack, offset = processor.resolve_address(ptr.dup.ref!)
+        tracked = stack && stack[offset]
+        return ptr unless tracked.is_a?(OneGadget::Emulators::Lambda) && tracked.deref_count.zero?
+
+        tracked
+      end
+
+      # Generate the +envp+-related constraint for an +exec*+ call.
+      #
+      # Mirrors the +argv+ terminology from {#check_argv}: +envp_ptr+ is the *pointer to* the envp array
+      # ({OneGadget::Emulators::Processor#argument}), while +envp+ is the array of dereferenced entries
+      # it points to.
+      #
+      # @param [OneGadget::Emulators::Processor] processor The processor state at the call site.
+      # @param [OneGadget::Emulators::Lambda, Integer] envp_ptr The pointer to the envp array.
+      # @yieldparam [String] cons The +envp+ constraint, yielded only when one is required.
+      # @return [Object, nil] Truthy when +envp+ is acceptable, +nil+ to reject the gadget.
+      def check_envp(processor, envp_ptr)
+        # A doubly-dereferenced pointer that names a global variable is believed to
+        # be environ; one that doesn't drops the gadget. The two dereferences are
+        # the slot the address is read from and the variable itself, so an
+        # architecture that resolves the first of them lands one earlier -- naming
+        # the variable, which it then has to be able to recognise.
+        if envp_ptr.is_a?(OneGadget::Emulators::Lambda)
+          return global_var?(envp_ptr.to_s) if envp_ptr.deref_count >= 2
+          return true if envp_ptr.deref_count == 1 && environ?(envp_ptr.to_s)
+        end
+
+        envp_ptr = resolve_stack_deref(processor, envp_ptr)
+        # A concrete integer, or a register with nothing useful tracked for it,
+        # falls through to the opaque-pointer case (see {#resolvable_stack}).
+        stack = envp_ptr.is_a?(OneGadget::Emulators::Lambda) && envp_ptr.deref_count.zero? &&
+                resolvable_stack(processor, envp_ptr)
+        if stack
+          # I haven't see this case after some tests, but just in case :)
+          envp = (0..3).map { |i| stack[envp_ptr.immi + processor.class.bits / 8 * i].to_s }
+          cons = global_var?(envp[0]) ? nil : "#{envp_ptr} == NULL || {#{envp.join(', ')}, ...} is a valid envp"
+        else
+          cons = "[#{envp_ptr}] == NULL || #{envp_ptr} == NULL || #{envp_ptr} is a valid envp"
+        end
+        # What the gadget itself put in the array is the caller's to arrange too,
+        # whichever element it landed in (see {#written_into}).
+        processor.writes_through(envp_ptr.to_s).each do |value|
+          yield "#{value} == NULL || readable: #{value}"
+        end
+        return nil if cons.nil?
+
+        yield cons
+      end
+
+      # Resolve +call execl+ cases.
+      def resolve_execl(processor)
+        return unless str_bin_sh?(processor.argument(0).to_s)
+
+        args = []
+        arg = processor.argument(1).to_s
+        if str_sh?(arg)
+          arg = processor.argument(2).to_s
+          args << '"sh"'
+        end
+        return nil if global_var?(arg) # we don't want base-related constraints
+
+        args << arg
+        cons = processor.constraints + ["#{arg} == NULL"]
+        { constraints: cons, effect: %(execl("/bin/sh", #{args.join(', ')})) }
+      end
+
+      # posix_spawn (*pid, *path, *file_actions, *attrp, argv[], envp[])
+      # Constraints are
+      # * pid == NULL || *pid is writable
+      # * file_actions == NULL || (int) (file_actions->__used) <= 0
+      # * attrp == NULL || attrp->flags == 0
+      # Meet all constraints then posix_spawn eventually calls execve(path, argv, envp)
+      def resolve_posix_spawn(processor)
+        args = Array.new(6) { |i| processor.argument(i) }
+        # pid/file_actions/attrp are reasoned about as pointers (Lambdas); a
+        # concrete non-zero integer there is a fixed address we can't constrain.
+        return nil if [args[0], args[2], args[3]].any? { |a| a.is_a?(Integer) && !a.zero? }
+
+        res = resolve_execve_args(processor, args[1], args[4], args[5], allow_null_argv: false)
+        return nil if res.nil?
+
+        cons = res[:constraints]
+        arg0 = args[0]
+        if arg0.to_s != '0'
+          if arg0.deref_count.zero? && arg0.to_s.include?(processor.sp)
+            # Assume stack is always writable, no additional constraints.
+          else
+            cons << "#{arg0} == NULL || writable: #{arg0}"
+          end
+        end
+        arg2 = args[2]
+        cons << "#{arg2} == NULL || (s32)#{(arg2 + 4).deref} <= 0x0" if arg2.to_s != '0'
+        arg3 = args[3]
+        cons << "#{arg3} == NULL || (u16)#{arg3.deref} == 0x0" if arg3.to_s != '0'
+
+        { constraints: cons, effect: %(posix_spawn(#{arg0}, "/bin/sh", #{arg2}, #{arg3}, #{args[4]}, #{res[:envp]})) }
+      end
+
+      # Render one argv/envp entry for a constraint. A libc global that points to a
+      # fixed string is shown as that string (its true content); a controllable
+      # operand, or a global that isn't a plain string, is shown unchanged.
+      # @param [String] element A single argv entry.
+      # @example +$base+0x16b250+ -> +"--"+ (the do_system separator); +x21+ -> +x21+.
+      # @return [String]
+      def resolve_argv_element(element)
+        content = global_str_content(element)
+        content ? content.inspect : element
+      end
+    end
+  end
+end

data/lib/one_gadget/fetchers/arm.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require 'elftools'
+
+require 'one_gadget/emulators/arm'
+require 'one_gadget/fetchers/base'
+
+module OneGadget
+  module Fetchers
+    # Fetcher for 32-bit ARM (A32 / Thumb-2).
+    class Arm < Base
+      # Condition codes as branch suffixes (+bne+, +bcs+, ...).
+      CONDS = %w[eq ne cs hs cc lo mi pl vs vc hi ls ge lt gt le].freeze
+
+      private
+
+      # Read as Thumb rather than A32, which objdump assumes for these bytes.
+      THUMB = %w[-M force-thumb].freeze
+      private_constant :THUMB
+
+      # An ARM function's symbol value carries the Thumb bit; the address is what
+      # is left of it.
+      def symbol_address(value)
+        value & ~1
+      end
+
+      # ARM states its two instruction sets in one file, and objdump switches
+      # between them on the mapping symbols an ELF carries -- which a file read as
+      # bytes has none of. The dynamic symbol table says the same thing in the low
+      # bit of every function's value, so each stretch is disassembled as what it
+      # says it is.
+      # @param [ELFTools::ELFFile] elf
+      # @return [void]
+      def record_instruction_sets(elf)
+        entries = elf.dynamic.symbols.filter_map do |symbol|
+          value = symbol.value
+          next if value.zero? || symbol.type != ELFTools::Constants::STT_FUNC
+
+          [symbol_address(value), value.odd?]
+        end
+        # Only where it changes: a boundary between two functions encoded the same
+        # way is one objdump call more for nothing.
+        @instruction_sets = entries.sort_by(&:first).chunk_while { |a, b| a[1] == b[1] }.map(&:first)
+      end
+
+      # Split +lo+ to +hi+ where the instruction set changes (see
+      # {#record_instruction_sets}), each piece told which one it is.
+      # @param [Integer] lo
+      # @param [Integer] hi
+      # @return [Array<(Integer, Integer, Array<String>)>]
+      def decode_ranges(lo, hi)
+        return super if @instruction_sets.nil?
+
+        bounds = @instruction_sets.map(&:first).select { |addr| addr > lo && addr < hi }
+        [lo, *bounds, hi].each_cons(2).map { |from, to| [from, to, thumb_at?(from) ? THUMB : []] }
+      end
+
+      # Which instruction set the code at +addr+ is in: the one the last function
+      # starting at or before it declared. Thumb is the answer for an address no
+      # symbol precedes, being what the rest of the file overwhelmingly is.
+      # @param [Integer] addr
+      # @return [Boolean]
+      def thumb_at?(addr)
+        idx = (@instruction_sets.bsearch_index { |entry| entry.first > addr } || @instruction_sets.size) - 1
+        idx.negative? || @instruction_sets[idx][1]
+      end
+
+      # A32 and Thumb both spell a direct call +BL+, in different encodings, and a
+      # Thumb one is not word-aligned, so every halfword has to be considered.
+      def scan_calls(base, data, targets)
+        halves = data.unpack('v*') # 16-bit little-endian halfwords
+        sites = []
+        # A whole .text is hundreds of thousands of halfwords, and all but a few
+        # open neither encoding, so each is asked what it could be before
+        # anything is read or decoded on its behalf.
+        halves.each_with_index do |high, i|
+          if THUMB_BL_LEAD.cover?(high) && (low = halves[i + 1]) && thumb_bl_tail?(low)
+            addr = base + (i * 2)
+            sites << addr if targets.key?(thumb_bl_target(addr, high, low) & ~1)
+          end
+          next unless i.even?
+
+          low = halves[i + 1] or next
+          next unless a32_bl?(low)
+
+          addr = base + (i * 2)
+          sites << addr if targets.key?(a32_bl_target(addr, high | (low << 16)))
+        end
+        sites.uniq
+      end
+
+      # What a Thumb +BL+'s first halfword names the encoding as.
+      THUMB_BL_LEAD = (0xf000..0xf7ff)
+      private_constant :THUMB_BL_LEAD
+
+      # Whether the second halfword of a Thumb +BL+ says it is the long form
+      # rather than +BLX+.
+      # @param [Integer] low
+      # @return [Boolean]
+      def thumb_bl_tail?(low)
+        low.allbits?(0xd000)
+      end
+
+      # The +cond|101|1+ of an A32 BL, read off the word's top byte -- which is the
+      # top byte of its second halfword.
+      def a32_bl?(low)
+        ((low >> 8) & 0x0f) == 0x0b
+      end
+
+      # Where a Thumb +BL+ goes. Its offset is scattered across both halfwords,
+      # with the two middle bits stored inverted against the sign bit, and is
+      # taken from the address two instructions on.
+      def thumb_bl_target(addr, high, low)
+        s = (high >> 10) & 1
+        i1 = (~(((low >> 13) & 1) ^ s)) & 1
+        i2 = (~(((low >> 11) & 1) ^ s)) & 1
+        imm = (s << 24) | (i1 << 23) | (i2 << 22) | ((high & 0x3ff) << 12) | ((low & 0x7ff) << 1)
+        imm -= (1 << 25) if s == 1
+        (addr + 4 + imm) & 0xffffffff
+      end
+
+      def a32_bl_target(addr, word)
+        imm = (word & 0xffffff) << 2
+        imm -= (1 << 26) if imm.anybits?(1 << 25)
+        (addr + 8 + imm) & 0xffffffff
+      end
+
+      def emulator
+        OneGadget::Emulators::Arm.new(file)
+      end
+
+      # In ARM PIC, +environ+ is reached through the GOT base register (e.g. +r8+),
+      # which glibc loads in the function prologue -- outside the candidate window.
+      # Before emulating a candidate, detect that register and replay its
+      # +ldr rX, [pc]; add rX, pc+ setup so it resolves to +$base + got+.
+      def emulate(cmds)
+        emu = emulator
+        emu.note_instruction_set(cmds)
+        @got_base_regs = seed_got_registers(emu, cmds)
+        cmds.each_with_object(emu) { |cmd, obj| break obj unless obj.process(cmd) }
+      end
+
+      # A GOT base register seeded from the prologue is a runtime precondition,
+      # independent of what its load is *for*: the +[rB, rX]+ dereference itself
+      # faults on a wrong base, whether the value it fetches is +environ+ or
+      # something unrelated to the effect entirely (e.g. a stack-protector guard
+      # read). Surface it as a constraint (mirroring i386's +<reg> is the GOT
+      # address of libc+) whenever the candidate actually walked past such a
+      # dereference. Seeding only ever primes registers set up *before* the
+      # window, so a gadget that establishes the base itself carries no such
+      # constraint.
+      def resolve(processor)
+        res = super
+        return res if res.nil? || @got_base_regs.empty?
+
+        gots = @got_base_regs.to_h { |reg| [reg, got_base_constraint(processor, reg)] }
+        return nil unless gots.values.all?
+
+        gots.each do |reg, got|
+          res[:constraints].unshift(got)
+          res[:constraints].delete_if { |c| c.start_with?("writable: #{reg}") }
+        end
+        res
+      end
+
+      # A general-purpose register, by number or by the role name objdump prints.
+      REG = /r\d+|sl|fp|ip|lr/
+      private_constant :REG
+
+      # A register-offset load, +[rB, rX]+.
+      REG_OFFSET_LOAD = /\[(#{REG}),\s*(?:#{REG})\]/
+      private_constant :REG_OFFSET_LOAD
+
+      # Collect the registers used as a base in a register-offset load (+[rB, rX]+);
+      # in glibc's PIC these +rB+ are the GOT base holding +$base + got+.
+      # @example
+      #   got_base_registers(['88ab2: ldr r2, [r1, r2]'])
+      #   #=> ['r1']
+      def got_base_registers(cmds)
+        cmds.flat_map { |c| c.scan(REG_OFFSET_LOAD) }
+            .flatten.uniq
+      end
+
+      # The patterns naming one register: what uses it as a load base, and the
+      # +ldr+/+add+ pair that establishes it. Built once per register -- they are
+      # asked of every line of every window a candidate yields.
+      # @param [String] reg
+      # @return [Hash{Symbol => Regexp}]
+      def reg_patterns(reg)
+        (@reg_patterns ||= {})[reg] ||= {
+          use: /\[#{reg},\s*(?:#{REG})\]/,
+          add: /:\s*add(?:\.w)?\s+#{reg}, pc$/,
+          ldr: /:\s*ldr(?:\.w)?\s+#{reg}, \[pc[,\]]/
+        }
+      end
+
+      # Whether the candidate builds +reg+'s base itself, before the +[reg, rX]+
+      # that relies on it. Replaying a prologue setup for such a register would
+      # apply it twice -- once as the seed, once by emulating the window that
+      # contains it -- leaving a value no caller can supply, described by a
+      # constraint naming the register's *entry* value.
+      # @example arm-2.27's +0x73f2a+, whose first instruction is +add r3, pc+
+      def window_establishes?(reg, cmds)
+        pattern = reg_patterns(reg)
+        use = cmds.index { |c| c.match?(pattern[:use]) } or return false
+
+        cmds[0...use].any? { |c| c.match?(pattern[:add]) }
+      end
+
+      # Prime +emu+ with every GOT base register the candidate relies on, by
+      # replaying the +ldr rX, [pc]; add rX, pc+ pair (found via {#got_setup_lines})
+      # that established it earlier in the function, so +[rX, ...]+ loads inside the
+      # candidate resolve against +$base+.
+      # @return [Array<String>] the registers actually seeded (their setup was
+      #   found before the window), i.e. the GOT-base runtime preconditions.
+      def seed_got_registers(emu, cmds)
+        start = cmds.first[/\A\s*([0-9a-f]+):/, 1]&.to_i(16)
+        return [] if start.nil?
+
+        got_base_registers(cmds).select do |reg|
+          next false if window_establishes?(reg, cmds)
+
+          lines = got_setup_lines(reg, start) or next false
+
+          lines.each { |line| emu.process(line) }
+          true
+        end
+      end
+
+      # Locate the +ldr reg, [pc, ...]; add reg, pc+ pair that establishes +reg+
+      # before address +before+. Returns the two objdump lines, or +nil+.
+      def got_setup_lines(reg, before)
+        (@got_setup ||= {})[[reg, before]] ||= find_got_setup_lines(reg, before)
+      end
+
+      # {#got_setup_lines} without the memo: overlapping candidates ask the same
+      # register at the same address again and again, and the answer only depends
+      # on the disassembly.
+      def find_got_setup_lines(reg, before)
+        pos = disasm_index[before]
+        return if pos.nil?
+
+        lines = disasm_lines
+        pattern = reg_patterns(reg)
+        add_at = pos.downto(reachable_from(pos, SETUP_REACH)).find { |i| lines[i].match?(pattern[:add]) }
+        return if add_at.nil?
+
+        ldr_at = add_at.downto(reachable_from(add_at, LOAD_REACH)).find { |i| lines[i].match?(pattern[:ldr]) }
+        return if ldr_at.nil?
+
+        [lines[ldr_at], lines[add_at]]
+      end
+
+      # How far back to look for each half of the pair, in lines.
+      SETUP_REACH = 400
+      LOAD_REACH = 4
+      private_constant :SETUP_REACH, :LOAD_REACH
+
+      # The earliest line back from +pos+ that the line at +pos+ follows on from.
+      # {#disasm_lines} holds a window per terminal call, so a window's first line
+      # is where the code around it starts.
+      # @param [Integer] pos
+      # @param [Integer] reach
+      # @return [Integer]
+      # @example Where line 10 opens a window, line 12 can see back only that far.
+      #   window_starts           #=> { 10 => true }
+      #   reachable_from(12, 400) #=> 10
+      #   reachable_from(9, 400)  #=> 0
+      def reachable_from(pos, reach)
+        floor = [0, pos - reach].max
+        (floor..pos).reverse_each.find { |i| window_starts.key?(i) } || floor
+      end
+
+      def branch_lead_chars
+        'bct'
+      end
+
+      # Which kind of transfer +line+ is, or +nil+ for one that is neither -- a
+      # call among them.
+      # @example Thumb +cbz+/+cbnz+ count as conditional, while +bx+, a table
+      #   branch and any return through +pc+ end the path.
+      #   branch_kind('4a1c0: b 4a200')      #=> :unconditional
+      #   branch_kind('4a1c0: bne 4a200')    #=> :conditional
+      #   branch_kind('4a1c0: bl 73ba0')     #=> nil
+      #   branch_kind('4a1c0: pop {r4, pc}') #=> :terminator
+      def branch_kind(line)
+        m = branch_mnemonic(line)
+        return :conditional if conditional_mnemonic?(m)
+        return :unconditional if m == 'b'
+        return :terminator if m.start_with?('bx') || %w[tbb tbh].include?(m)
+        return :terminator if %w[pop ldm ldmia ldmfd ldmdb].include?(m) && line.match?(/\bpc\b/)
+
+        :terminator if line.match?(/:\s*(mov|ldr)(\.[wn])?\s+pc\b/)
+      end
+
+      def conditional_mnemonic?(mnem)
+        return true if %w[cbz cbnz].include?(mnem)
+
+        !mnem.start_with?('bl') && mnem.start_with?('b') && CONDS.include?(mnem[1..])
+      end
+
+      def branch_mnemonic(line)
+        mnemonic(line).sub(/\.[wn]\z/, '')
+      end
+
+      def call_str
+        'bl'
+      end
+    end
+  end
+end