one_gadget 1.9.0 → 2.0.0

data/lib/one_gadget/fetchers/base.rb

@@ -1,16 +1,70 @@
 # frozen_string_literal: true
 
+require 'elftools'
+
+require 'one_gadget/emulators/processor'
 require 'one_gadget/error'
 require 'one_gadget/fetchers/objdump'
 
 module OneGadget
-  module Fetcher
-    # Define common methods for gadget fetchers.
+  module Fetchers
+    # Base of the per-architecture gadget fetchers. It discovers candidate
+    # instruction sequences - a backward control-flow walk from each
+    # +exec+/+posix_spawn+ call - and turns a solved candidate into a
+    # {OneGadget::Gadget::Gadget}. A subclass supplies only the arch-specific
+    # pieces (call mnemonic, string/global recognition, branch classification).
+    #
+    # To add an architecture, see +docs/adding-an-architecture.md+; +AArch64+ is
+    # the simplest example.
     class Base
       # The absolute path to glibc.
       # @return [String] The filename.
       attr_reader :file
 
+      # What a terminal function's name starts with, and enough bytes of a name to
+      # tell: a symbol table's string table is read as one blob, so a name is a
+      # slice of it.
+      TERMINAL_PREFIXES = %w[exec posix_spawn].freeze
+      TERMINAL_PREFIX_BYTES = 12
+      private_constant :TERMINAL_PREFIXES, :TERMINAL_PREFIX_BYTES
+
+      # Give up on a control-flow path once it has crossed this many conditional branches.
+      MAX_FORKS = 4
+      # Hard cap on a single path's length (loop/runaway guard).
+      PATH_BUDGET = 80
+
+      # How much to disassemble around each terminal call when an architecture can
+      # locate the calls cheaply (see {#terminal_call_sites} / {#windowed_disasm}).
+      #
+      # The walk runs backwards from the call, but what it reaches does not: a
+      # branch predecessor can sit *after* the call, so the window has to hold the
+      # loop or later block that jumps back into the region.
+      #
+      # Both directions were measured by windowing every architecture against its
+      # own full disassembly across the spec corpus. Gadgets start being lost below
+      # 0x400 either way, and a window too small to hold a predecessor invents them
+      # as well: the line before the first of a window is the last of another, and
+      # nothing about it follows. These leave 16x that, and still disassemble about
+      # a fifth of a libc -- terminal calls cluster into a handful of merged
+      # windows, so a wider one costs little.
+      #
+      # A gadget whose code and branch-predecessors exceed the window is missed,
+      # which is why windowing is opt-in per arch (fast disassembly arches keep the
+      # full, exhaustive scan) and falls back to full disassembly if the call scan
+      # comes up empty.
+      WINDOW_BACK = 0x4000
+      # As far past the call, for a predecessor that branches back into the region.
+      WINDOW_FWD = 0x4000
+
+      # Cache values that are a deterministic function of an objdump command
+      # (its output and everything derived from it), so re-analysing the same
+      # file - common in the specs, harmless for the CLI which reads a file once -
+      # doesn't redo the disassembly or the whole-binary scans.
+      def self.cached(kind, command)
+        @cached ||= Hash.new { |h, k| h[k] = {} }
+        @cached[kind][command] ||= yield
+      end
+
       # Instantiate a fetcher object.
       # @param [String] file Absolute path to the target libc.
       def initialize(file)
@@ -23,20 +77,93 @@ module OneGadget
       # Do find gadgets in glibc.
       # @return [Array<OneGadget::Gadget::Gadget>] Gadgets found.
       def find
-        candidates.map do |cand|
-          lines = cand.lines
-          # use processor to find which can lead to a valid one-gadget call.
-          gadgets = []
-          (lines.size - 2).downto(0) do |i|
-            processor = emulate(lines[i..-1])
-            options = resolve(processor)
-            next if options.nil? # impossible to be a gadget
-
-            offset = offset_of(lines[i])
-            gadgets << OneGadget::Gadget::Gadget.new(offset, **options)
+        str_offset('/bin/sh') # ensure it's glibc-like; raises "not glibc?" if not found
+        gadgets = []
+        # Overlapping candidate paths share tails, so the same suffix (a start line
+        # and everything after it) recurs across candidates; emulate each once.
+        seen = {}
+        candidates.each do |cand|
+          executed_windows(cand.lines) do |suffix|
+            next if seen.key?(key = suffix.join)
+
+            seen[key] = true
+            next if refused_before_call?(suffix)
+
+            gadget = resolve_suffix(suffix)
+            gadgets << gadget unless gadget.nil?
           end
-          gadgets
-        end.flatten
+        end
+        gadgets
+      end
+
+      # Every suffix of +lines+ -- a start line and everything after it, longest
+      # last -- cut down to the part that runs: emulation ends at the terminal
+      # call, so anything past one never executes. A suffix reaches beyond a
+      # terminal call when the function holds several and the candidate was walked
+      # back from a later one. Bounding each window here lets everything
+      # downstream -- {#emulate} and its overrides, the dedup key in {#find} --
+      # read a window as executed code.
+      #
+      # Each line is classified once per candidate rather than once per suffix
+      # containing it: walking the start backwards, the first terminal call at or
+      # after it only moves when the start is itself one.
+      # @param [Array<String>] lines One candidate, as a line list.
+      # @yieldparam [Array<String>] window
+      # @return [void]
+      def executed_windows(lines)
+        stop = lines.size - 1 if terminal_call_line?(lines.last)
+        (lines.size - 2).downto(0) do |i|
+          stop = i if terminal_call_line?(lines[i])
+          yield(stop ? lines[i..stop] : lines[i..])
+        end
+      end
+
+      # Whether +line+ is the call that ends a gadget, by the same rule the emulator
+      # stops on ({OneGadget::Emulators::Processor#terminal_call?}). Not
+      # {#terminal_call_regexp}, which is looser so it can locate call sites: it
+      # also matches the +posix_spawn+ setup helpers, which emulation runs through.
+      # The mnemonic must be a call, so a branch whose target symbol merely looks
+      # similar (+<execlp@@GLIBC_2.4+0x136>+) doesn't end the window.
+      def terminal_call_line?(line)
+        return false unless line[/\A\s*[0-9a-f]+:\s*(\S+)/, 1]&.match?(/\A#{call_str}x?(?:\.[wn])?\z/)
+
+        name = line[/<([^@>]+)/, 1]
+        !name.nil? && OneGadget::Emulators::Processor::TERMINAL_CALL_RE.match?(name)
+      end
+
+      # Whether emulating +window+ can only stop short of its terminal call: it
+      # runs a line the emulator has already refused (see
+      # {OneGadget::Emulators::Processor#refused_line}), and a window that never
+      # reaches the call is not a gadget. Refusal belongs to the line, so one
+      # learnt anywhere settles every window carrying it -- and overlapping
+      # candidates carry the same lines over and over.
+      # @param [Array<String>] window
+      # @return [Boolean]
+      def refused_before_call?(window)
+        return false if @refused.nil?
+
+        (window.size - 1).times.any? { |i| @refused.key?(window[i]) }
+      end
+
+      # Emulate a candidate suffix and turn it into a gadget, or +nil+ if it isn't one.
+      def resolve_suffix(lines)
+        processor = emulate(lines)
+        (@refused ||= {})[processor.refused_line] = true if processor.refused_line
+        # resolve reads argument registers, which may not be evaluable on an
+        # exotic path; such a candidate simply isn't a gadget.
+        options = begin
+          resolve(processor)
+        rescue OneGadget::Error::Error
+          nil
+        end
+        return if options.nil?
+        # A branch that compares a value with itself yields a trivial condition:
+        # drop the gadget if it's unsatisfiable, else strip the always-true one.
+        return if options[:constraints].any? { |c| contradiction?(c) }
+
+        options[:constraints] = options[:constraints].reject { |c| tautology?(c) }
+        options[:closed_fds] = processor.closed_fds
+        OneGadget::Gadget::Gadget.new(offset_of(lines.first), **options)
       end
 
       # Fetch candidates that end with call exec*.
@@ -48,23 +175,8 @@ module OneGadget
       #   True for valid.
       # @return [Array<String>]
       #   Each +String+ returned is multi-lines of assembly code.
-      def candidates(&block)
-        call_regexp = "#{call_str}.*<(exec[^+]*|posix_spawn[^+]*)>$"
-        cands = []
-        `#{@objdump.command}|grep -E '#{call_regexp}' -B 30`.split('--').each do |cand|
-          lines = cand.lines.map(&:strip).reject(&:empty?)
-          # split with call_regexp
-          loop do
-            idx = lines.index { |l| l =~ /#{call_regexp}/ }
-            break if idx.nil?
-
-            cands << lines.shift(idx + 1).join("\n")
-          end
-        end
-        # remove all jmps
-        cands = slice_prefix(cands, &method(:branch?))
-        cands.select!(&block) if block_given?
-        cands
+      def candidates(&)
+        branch_aware_candidates(&)
       end
 
       private
@@ -81,13 +193,12 @@ module OneGadget
         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')
-        return resolve_execl(processor) if call.include?('execl')
+
+        resolve_execl(processor) if call.include?('execl')
       end
 
       def resolve_execve(processor)
-        arg0 = processor.argument(0).to_s
-        arg1 = processor.argument(1).to_s
-        arg2 = processor.argument(2).to_s
+        arg0, arg1, arg2 = (0..2).map { |i| processor.argument(i) }
         res = resolve_execve_args(processor, arg0, arg1, arg2)
         return nil if res.nil?
 
@@ -95,7 +206,7 @@ module OneGadget
       end
 
       def resolve_execve_args(processor, arg0, arg1, arg2, allow_null_argv: true)
-        return unless str_bin_sh?(arg0)
+        return unless str_bin_sh?(arg0.to_s)
 
         # arg1 == NULL || [arg1] == NULL
         # arg2 == NULL || [arg2] == NULL || arg[2] == envp
@@ -110,29 +221,83 @@ module OneGadget
           envp = arg2
         end
 
-        { constraints: cons, envp: envp }
+        { constraints: cons, envp: }
       end
 
-      def check_argv(processor, arg, allow_null)
-        lmda = OneGadget::Emulators::Lambda.parse(arg)
-
-        if lmda.deref_count.zero? && OneGadget::ABI.stack_register?(lmda.obj)
-          return check_stack_argv(processor, lmda, allow_null)
-        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
 
-        check_nonstack_argv(arg, allow_null)
+      # 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
 
-      def check_stack_argv(processor, lmda, allow_null)
-        stack = processor.get_corresponding_stack(lmda.obj)
-        argv = (0..3).map { |i| stack[lmda.immi + processor.class.bits / 8 * i].to_s }
+      # 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, allow_null)
+        generate_argv_without_sh(argv_ptr, argv, allow_null)
       end
 
       def argv_already_valid?(argv)
@@ -149,22 +314,27 @@ module OneGadget
         else
           argv_gte3 = argv[3] == '0' ? 'NULL' : "#{argv[3]}, ..."
           if global_var?(argv[1])
-            "{\"sh\", \"-c\", #{argv[2]}, #{argv_gte3}} is a valid argv"
+            # 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
 
-      def generate_argv_without_sh(argv, allow_null)
+      # @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 i == 1 && global_var?(argv[i])
-            # TODO: We probably need to get the true content of the global variable for a more accurate result
-            argv_cons += ', "-c"'
+          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
@@ -173,37 +343,90 @@ module OneGadget
         argv_cons += '} is a valid argv'
 
         if allow_null && argv.all? { |a| OneGadget::ABI.stack_register?(a) }
-          # If libc writes something into the stack, arg cannot be NULL.
-          # TODO: Find a better way to check can arg be NULL
-          "#{arg} == NULL || #{argv[0]} == NULL || #{argv_cons}"
+          # 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
 
-      def check_nonstack_argv(arg, allow_null)
+      # 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
-          "[#{arg}] == NULL || #{arg} == NULL || #{arg} is a valid argv"
+          "[#{argv_ptr}] == NULL || #{argv_ptr} == NULL || #{argv_ptr} is a valid argv"
         else
-          "[#{arg}] == NULL || #{arg} is a valid argv"
+          "[#{argv_ptr}] == NULL || #{argv_ptr} is a valid argv"
         end
       end
 
-      def check_envp(processor, arg)
-        # If str starts with [[ and is a global variable,
-        # believe it is environ.
-        # If it starts with [[ but not a global var, drop it.
-        return global_var?(arg) if arg.start_with?('[[')
+      # 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
 
-        lmda = OneGadget::Emulators::Lambda.parse(arg)
-        if lmda.deref_count.zero? && OneGadget::ABI.stack_register?(lmda.obj)
+      # 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.
+        return global_var?(envp_ptr.to_s) if envp_ptr.is_a?(OneGadget::Emulators::Lambda) &&
+                                             envp_ptr.deref_count >= 2
+
+        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 :)
-          stack = processor.get_corresponding_stack(lmda.obj)
-          envp = (0..3).map { |i| stack[lmda.immi + processor.class.bits / 8 * i].to_s }
+          envp = (0..3).map { |i| stack[envp_ptr.immi + processor.class.bits / 8 * i].to_s }
           # TODO: Handle the case when libc will write something into envp
-          cons = global_var?(envp[0]) ? nil : "#{arg} == NULL || {#{envp.join(', ')}, ...} is a valid envp"
+          cons = global_var?(envp[0]) ? nil : "#{envp_ptr} == NULL || {#{envp.join(', ')}, ...} is a valid envp"
         else
-          cons = "[#{arg}] == NULL || #{arg} == NULL || #{arg} is a valid envp"
+          cons = "[#{envp_ptr}] == NULL || #{envp_ptr} == NULL || #{envp_ptr} is a valid envp"
         end
         return nil if cons.nil?
 
@@ -235,7 +458,11 @@ module OneGadget
       # 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) }
-        res = resolve_execve_args(processor, args[1].to_s, args[4].to_s, args[5].to_s, allow_null_argv: false)
+        # 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]
@@ -248,9 +475,9 @@ module OneGadget
           end
         end
         arg2 = args[2]
-        cons << "#{arg2} == NULL || (s32)#{(arg2 + 4).deref} <= 0" if arg2.to_s != '0'
+        cons << "#{arg2} == NULL || (s32)#{(arg2 + 4).deref} <= 0x0" if arg2.to_s != '0'
         arg3 = args[3]
-        cons << "#{arg3} == NULL || (u16)#{arg3.deref} == NULL" if arg3.to_s != '0'
+        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
@@ -258,6 +485,39 @@ module OneGadget
       def global_var?(_str); raise NotImplementedError
       end
 
+      # Whether +str+ names a value at a fixed offset from +base+, i.e. an address
+      # whose content can be read out of the file. An operation applied to such an
+      # address (see {OneGadget::Emulators::Lambda.operation}) is that address plus
+      # whatever the caller supplies, so it names no particular byte and must not be
+      # resolved as though it did.
+      # @param [String] str A rendered value.
+      # @param [String] base The token a libc-relative address renders against.
+      # @return [Boolean]
+      # @example A fixed global, and the same global offset by a register.
+      #   base_relative?('$base+0x10', '$base')        #=> true
+      #   base_relative?('(r3 + $base+0x10)', '$base') #=> false
+      def base_relative?(str, base)
+        str.match?(/\A\[*#{Regexp.escape(base)}(?:[+-]0x[0-9a-f]+)?\]*\z/)
+      end
+
+      # The requirement that a value be libc's GOT base, when a register holds it.
+      # That is a precondition a caller can arrange and a reader can check: set
+      # the register before jumping. A candidate whose window loads the base out
+      # of memory instead names a location nobody sets up -- there is no register
+      # to point anywhere -- so it is refused rather than stated as a constraint
+      # nothing can meet.
+      # @param [OneGadget::Emulators::Processor] processor
+      # @param [String] holder Where the candidate found the GOT base.
+      # @return [String?] The constraint, or +nil+ if the candidate must be refused.
+      # @example
+      #   got_base_constraint(processor, 'ecx')        #=> "ecx is the GOT address of libc"
+      #   got_base_constraint(processor, '[ebp-0x2c]') #=> nil
+      def got_base_constraint(processor, holder)
+        return nil unless processor.registers.key?(holder)
+
+        "#{holder} is the GOT address of libc"
+      end
+
       def str_bin_sh?(_str); raise NotImplementedError
       end
 
@@ -267,6 +527,12 @@ module OneGadget
       def call_str; raise NotImplementedError
       end
 
+      # Run a window through a fresh emulator, stopping at the first line it can't
+      # process (an unsupported instruction, or the terminal call that ends the
+      # gadget). +cmds+ is an executed window (see {#executed_windows}): every line
+      # in it runs, so an override may read it as evidence of what the path does.
+      # @param [Array<String>] cmds
+      # @return [OneGadget::Emulators::Processor]
       def emulate(cmds)
         cmds.each_with_object(emulator) { |cmd, obj| break obj unless obj.process(cmd) }
       end
@@ -278,26 +544,400 @@ module OneGadget
         []
       end
 
-      def slice_prefix(cands, &block)
-        cands.map do |cand|
-          lines = cand.lines
-          to_rm = lines[0...-1].rindex(&block)
-          lines = lines[to_rm + 1..-1] unless to_rm.nil?
-          lines.join
-        end
+      def str_offset(str)
+        file_bytes.index("#{str}\x00") ||
+          raise(Error::ArgumentError, "File #{file.inspect} doesn't contain string #{str.inspect}, not glibc?")
       end
 
-      # If str contains a branch instruction.
-      def branch?(_str); raise NotImplementedError
+      # The target's bytes, read once: a gadget names fixed strings by file offset,
+      # and every argv entry of every candidate asks for them again.
+      # @return [String]
+      def file_bytes
+        @file_bytes ||= File.binread(file)
       end
 
-      def str_offset(str)
-        File.binread(file).index("#{str}\x00") ||
-          raise(Error::ArgumentError, "File #{file.inspect} doesn't contain string #{str.inspect}, not glibc?")
+      # 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
+
+      # The NUL-terminated printable string a resolved-offset global (+$base+<off>+)
+      # points to, or +nil+ when +element+ isn't such a global or the bytes aren't a
+      # short printable string. Architectures whose globals aren't yet
+      # file-offset-relative simply fall through.
+      # @param [String] element
+      # @return [String, nil]
+      def global_str_content(element)
+        off = string_file_offset(element) or return nil
+
+        bytes = file_bytes
+        return nil unless off.between?(0, bytes.size - 1)
+
+        stop = bytes.index("\x00", off) or return nil
+        str = bytes[off...stop]
+        str if str.length.between?(1, 16) && str.each_byte.all? { |c| c.between?(0x20, 0x7e) }
+      end
+
+      # The file offset a fixed address names, or +nil+ when +element+ isn't one.
+      # Here that is the resolved-offset form an arch produces once it concretizes
+      # a pc-relative operand; an arch that reaches its globals through a register
+      # instead overrides this (see +I386#string_file_offset+).
+      # @param [String] element
+      # @return [Integer, nil]
+      def string_file_offset(element)
+        m = /\A\$base\+(0x[0-9a-f]+)\z/.match(element) or return nil
+
+        m[1].to_i(16)
       end
 
       def offset_of(assembly)
-        assembly.scan(/^([\da-f]+):/)[0][0].to_i(16)
+        assembly[/\A([\da-f]+):/, 1].to_i(16)
+      end
+
+      # Whether a single (non-disjunctive) branch condition already settles itself,
+      # asking nothing of the caller: +X == X+ is always true, +X != X+ never is,
+      # and so on for any two sides {#comparable_values} can put a number to.
+      # @param [String] con One constraint.
+      # @return [Boolean, nil] Whether the relation holds, or nil when it depends
+      #   on something the caller arranges -- i.e. it is a real constraint.
+      def trivial_relation(con)
+        return nil if con.include?(' || ')
+
+        m = con.match(/\A(?:\([su]\d+\))?(.+?) (==|!=|<=|>=|<|>) (.+)\z/)
+        return nil unless m
+
+        lhs, rhs = comparable_values(m[1], m[3])
+        return nil if lhs.nil?
+
+        lhs.public_send(m[2] == '!=' ? :!= : m[2].to_sym, rhs)
+      end
+
+      # The two sides of a relation as plain numbers, when they can be compared
+      # without the caller arranging anything: the same expression twice, two
+      # concrete values, or two offsets from one base (+r1+ against +r1+0x4+ can
+      # never be equal). +nil+ leaves the relation a real constraint.
+      #
+      # Offsets are only comparable undereferenced. +[r1]+ and +[r1+0x4]+ address
+      # different slots, but the values in them are unrelated -- nothing says they
+      # differ.
+      # @param [String] lhs The relation's left side, cast already stripped.
+      # @param [String] rhs The relation's right side.
+      # @return [(Numeric, Numeric), nil] Both sides as numbers, or nil when they
+      #   cannot be compared without knowing what the caller supplies.
+      def comparable_values(lhs, rhs)
+        return [0, 0] if lhs == rhs
+
+        left = OneGadget::Emulators::Lambda.parse(lhs)
+        right = OneGadget::Emulators::Lambda.parse(rhs)
+        return [left, right] if left.is_a?(Integer) && right.is_a?(Integer)
+        return nil unless [left, right].all? do |l|
+          l.is_a?(OneGadget::Emulators::Lambda) && l.deref_count.zero? && !l.operation?
+        end
+        return nil unless left.obj.to_s == right.obj.to_s
+
+        [left.immi, right.immi]
+      rescue OneGadget::Error::Error
+        nil
+      end
+
+      def tautology?(con)
+        trivial_relation(con) == true
+      end
+
+      def contradiction?(con)
+        trivial_relation(con) == false
+      end
+
+      # Regexp (as a String) matching an objdump line that calls a terminal
+      # function (+exec*+ / +posix_spawn*+) we can turn into a gadget.
+      def terminal_call_regexp
+        "#{call_str}.*<(exec[^+]*|posix_spawn[^+]*)>$"
+      end
+
+      # Enumerate gadget candidates by walking the control-flow graph *backward*
+      # from each terminal call along its predecessors (the instruction that falls
+      # through to it, plus any branch that targets it), forking at conditional
+      # edges up to {MAX_FORKS} times. Each emitted candidate is a flat,
+      # address-preserving line-list ending at the terminal call, consumed
+      # unchanged by {#find}; the emulator turns each crossed conditional edge into
+      # a constraint (see {OneGadget::Emulators::Conditional}).
+      def branch_aware_candidates(&)
+        cands = []
+        re = /#{terminal_call_regexp}/
+        disasm_lines.each_with_index do |line, idx|
+          next unless line.match?(re)
+
+          back_walk(idx, 0, Set.new, []) { |lines| cands << lines.join("\n") }
+        end
+        cands.uniq!
+        cands.select!(&) if block_given?
+        cands
+      end
+
+      # Depth-first backward walk. +visited+ (a Set) and +path+ are mutated with
+      # backtracking so a fork explores independently without per-step copies;
+      # +path+ is built in forward order (the terminal call stays last). Emits a
+      # candidate at each leaf - {#find} then tries every start line within it.
+      def back_walk(idx, forks, visited, path, &blk)
+        addr = addr_at(idx)
+        return if path.size >= PATH_BUDGET
+
+        visited.add(addr)
+        path.unshift(disasm_lines[idx])
+        edges = predecessors(idx).reject do |pidx, cond|
+          visited.include?(addr_at(pidx)) || (cond && forks >= MAX_FORKS)
+        end
+        if edges.empty?
+          blk.call(path.dup)
+        else
+          edges.each { |pidx, cond| back_walk(pidx, forks + (cond ? 1 : 0), visited, path, &blk) }
+        end
+        path.shift
+        visited.delete(addr)
+      end
+
+      # The address of the instruction at +idx+, remembered as it is asked for.
+      # Only the lines the backward walk reaches ever need one, a small part of a
+      # whole libc's disassembly.
+      def addr_at(idx)
+        (@addr_at ||= {})[idx] ||= offset_of(disasm_lines[idx])
+      end
+
+      # Predecessors of +disasm_lines[idx]+ as +[pred_index, conditional_edge?]+:
+      # the instruction that falls through to it, plus any branch that targets it.
+      # Computed lazily (the walk only touches lines near terminal calls) and cached.
+      def predecessors(idx)
+        (@predecessors ||= {})[idx] ||= begin
+          preds = []
+          # Nothing falls through into the first line of a window: the line before
+          # it is the last of another window, a different part of the binary.
+          if idx.positive? && !window_starts.key?(idx)
+            kind = branch_kind(disasm_lines[idx - 1])
+            preds << [idx - 1, kind == :conditional] unless %i[unconditional terminator].include?(kind)
+          end
+          (branch_pred_map[addr_at(idx)] || []).each do |b|
+            preds << [b, branch_kind(disasm_lines[b]) == :conditional]
+          end
+          preds
+        end
+      end
+
+      # Map of target-address => indexes of (conditional or unconditional) direct
+      # branches that jump there. Scans the whole disassembly once (a branch can
+      # target a call region from anywhere), so keep the per-line test cheap.
+      def branch_pred_map
+        @branch_pred_map ||= Base.cached(:branch_pred, @objdump.command) do
+          lead = branch_lead_regex
+          disasm_lines.each_with_index.with_object(Hash.new { |h, k| h[k] = [] }) do |(line, i), map|
+            # Cheap precompiled reject (no per-line allocation) before the full test.
+            next unless line.match?(lead)
+            next unless %i[conditional unconditional].include?(branch_kind(line))
+
+            tgt = branch_target(line)
+            map[tgt] << i if tgt
+          end
+        end
+      end
+
+      # Precompiled over-approximation of a branch line, built from the arch's
+      # {#branch_lead_chars}, to skip the full test for the (majority) non-branch
+      # lines during the whole-binary scan.
+      def branch_lead_regex
+        @branch_lead_regex ||= /\A[0-9a-f]+:\s+[#{branch_lead_chars}]/
+      end
+
+      # Parse the (direct) target address of a branch line, or +nil+ if indirect.
+      def branch_target(line)
+        line.sub(/\A[0-9a-f]+:\s*\S+\s*/, '')[/\b([0-9a-f]+)\b\s*(?:<|\z)/, 1]&.to_i(16)
+      end
+
+      # The mnemonic of an objdump line, memoized because each line is tested by
+      # several branch predicates during the CFG scan.
+      # @example
+      #   mnemonic('4a1d0: b.ne 4a200 <foo>') #=> 'b.ne'
+      #   mnemonic('4a1c0: cbz  x0, 4a200')   #=> 'cbz'
+      def mnemonic(line)
+        (@mnemonic ||= {})[line] ||= line[/\A[0-9a-f]+:\s*(\S+)/, 1] || ''
+      end
+
+      # Classify a disassembly +line+ for the control-flow walk (arch-specific):
+      #   :conditional   - may or may not be taken; the walk explores both edges
+      #                    and turns the decision into a gadget constraint
+      #   :unconditional - always taken, to a determined (direct) target
+      #   :terminator    - ends the path with no determined successor (a return or
+      #                    an indirect/computed jump)
+      #   nil            - not a branch; execution falls through to the next line
+      def branch_kind(_line); raise NotImplementedError
+      end
+
+      # The leading character(s) of this arch's branch mnemonics, used to build
+      # {#branch_lead_regex}. Must be plain regex-safe literals: they are spliced
+      # into a character class, so no +]+, +\+, +-+ or +^+.
+      # @example
+      #   'bct'  # aarch64/arm: b, cbz/cbnz, tbz/tbnz
+      #   'j'    # x86: jmp, jcc
+      def branch_lead_chars; raise NotImplementedError
+      end
+
+      # The target's objdump disassembly as stripped +"ADDR: insn"+ lines.
+      def disasm_lines
+        disassembly[:lines]
+      end
+
+      # Where in {#disasm_lines} each window begins, keyed for lookup. Empty when
+      # the whole file was disassembled, since then every line does follow the one
+      # before it.
+      # @return [Hash{Integer => true}]
+      def window_starts
+        disassembly[:starts]
+      end
+
+      # The disassembly and the shape it was taken in, cached (per objdump command)
+      # for the lifetime of the fetcher.
+      # @return [Hash{Symbol => Array<String>, Hash}]
+      def disassembly
+        @disassembly ||= Base.cached(:disasm, @objdump.command) do
+          sites = terminal_call_sites
+          sites.nil? || sites.empty? ? full_disasm : windowed_disasm(sites)
+        end
+      end
+
+      # Disassemble the whole file (the exhaustive default).
+      def full_disasm
+        { lines: objdump_lines, starts: {} }
+      end
+
+      # Disassemble only [call-WINDOW_BACK, call+WINDOW_FWD] around each call site,
+      # merging overlaps. Used when {#terminal_call_sites} located the calls without
+      # a full disassembly (the win on the slow-to-objdump Thumb-2 arm libcs).
+      def windowed_disasm(sites)
+        windows = sites.sort.map { |a| [[a - WINDOW_BACK, 0].max, a + WINDOW_FWD] }
+        # One objdump per window, all at once: they are separate processes that
+        # wait on each other for nothing, and a libc comes to a handful of windows.
+        disassembled = merge_ranges(windows)
+                       .map { |lo, hi| Thread.new { objdump_lines(start: lo, stop: hi) } }
+                       .map(&:value)
+        starts = {}
+        lines = disassembled.each_with_object([]) do |window, acc|
+          starts[acc.size] = true
+          acc.concat(window)
+        end
+        { lines:, starts: }
+      end
+
+      # Merge a list of sorted [lo, hi] ranges, coalescing any that overlap.
+      def merge_ranges(ranges)
+        ranges.each_with_object([]) do |(lo, hi), merged|
+          if merged.last && lo <= merged.last[1]
+            merged.last[1] = hi if hi > merged.last[1]
+          else
+            merged << [lo, hi]
+          end
+        end
+      end
+
+      # An objdump line carries an instruction when it opens with its address.
+      DISASSEMBLED = /\A[0-9a-f]+:/
+      private_constant :DISASSEMBLED
+
+      def objdump_lines(start: nil, stop: nil)
+        # One pass, one string per line: a whole libc is hundreds of thousands of
+        # them, and only the instructions are wanted.
+        `#{@objdump.command(start:, stop:)}`.each_line.filter_map do |line|
+          line = line.strip
+          line if DISASSEMBLED.match?(line)
+        end
+      end
+
+      # Addresses of the calls reaching a terminal function, found without
+      # disassembling anything: the +exec*+/+posix_spawn*+ symbols are read out of
+      # the ELF and +.text+ is scanned for direct calls into them (see
+      # {#scan_calls}). +nil+ when the file cannot be read that way, so the caller
+      # disassembles everything instead.
+      # @return [Array<Integer>, nil]
+      def terminal_call_sites
+        File.open(file) do |fd|
+          elf = ELFTools::ELFFile.new(fd)
+          return nil unless elf.endian == :little
+
+          targets = terminal_symbol_addresses(elf)
+          return [] if targets.empty?
+
+          text = elf.section_by_name('.text')
+          return nil if text.nil?
+
+          scan_calls(text.header.sh_addr.to_i, text.data, targets)
+        end
+      rescue ELFTools::ELFError
+        nil # not something we can scan; disassemble everything
+      end
+
+      # The addresses in +data+ (loaded at +base+) of direct calls into +targets+.
+      # Over-approximating is fine -- a false positive only adds a window nothing
+      # is found in -- while a missed call costs every gadget around it.
+      # @param [Integer] _base
+      # @param [String] _data
+      # @param [Hash{Integer => true}] _targets
+      # @return [Array<Integer>, nil] +nil+ from an arch with no cheap call finder,
+      #   which disassembles everything instead.
+      def scan_calls(_base, _data, _targets) = nil
+
+      # Where the +exec*+/+posix_spawn*+ symbols live, keyed for lookup. Read
+      # straight out of the tables rather than built into an object per symbol: a
+      # libc has thousands, and only two fields of each are wanted.
+      # @param [ELFTools::ELFFile] elf
+      # @return [Hash{Integer => true}]
+      def terminal_symbol_addresses(elf)
+        addrs = {}
+        %w[.dynsym .symtab].each do |name|
+          sec = elf.section_by_name(name)
+          next if sec.nil?
+
+          strtab = elf.sections[sec.header.sh_link.to_i].data
+          each_symbol(elf, sec) do |name_offset, value|
+            symbol = strtab.byteslice(name_offset, TERMINAL_PREFIX_BYTES)
+            addrs[symbol_address(value)] = true if symbol&.start_with?(*TERMINAL_PREFIXES)
+          end
+        end
+        addrs
+      end
+
+      # Each symbol's name offset and value, unpacked from the table's bytes. A
+      # 32-bit entry is four words with the value second; a 64-bit one is six, the
+      # value being the pair from the third.
+      # @param [ELFTools::ELFFile] elf
+      # @param [ELFTools::Sections::Section] section
+      # @yieldparam [Integer] name_offset
+      # @yieldparam [Integer] value
+      # @return [void]
+      def each_symbol(elf, section)
+        wide = elf.elf_class == 64
+        section.data.unpack('V*').each_slice(wide ? 6 : 4) do |words|
+          value = wide ? words[2] && words[3] && (words[2] | (words[3] << 32)) : words[1]
+          next if value.nil? || value.zero?
+
+          yield(words[0], value)
+        end
+      end
+
+      # The address a symbol's value names. Overridden where the value carries
+      # something besides the address (ARM keeps the Thumb bit in it).
+      # @param [Integer] value
+      # @return [Integer]
+      def symbol_address(value)
+        value
+      end
+
+      # Map from an instruction's address to its index in {#disasm_lines}, so a
+      # given address can be located in the disassembly in O(1).
+      def disasm_index
+        @disasm_index ||= disasm_lines.each_with_index.to_h { |line, i| [line[/\A([0-9a-f]+):/, 1].to_i(16), i] }
       end
     end
   end