one_gadget 2.0.0 → 2.1.0

data/lib/one_gadget/fetchers/base.rb

@@ -4,6 +4,10 @@ require 'elftools'
 
 require 'one_gadget/emulators/processor'
 require 'one_gadget/error'
+require 'one_gadget/fetchers/argument_resolution'
+require 'one_gadget/fetchers/candidate_walk'
+require 'one_gadget/fetchers/disassembly'
+require 'one_gadget/fetchers/dynamic_symbols'
 require 'one_gadget/fetchers/objdump'
 
 module OneGadget
@@ -12,54 +16,31 @@ module OneGadget
     # 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).
+    # pieces (call mnemonic, string/global recognition, branch classification),
+    # every one of which is declared here whatever module implements the engine
+    # that calls it: {CandidateWalk} for the control-flow walk, {Disassembly} for
+    # reading the file, and {ArgumentResolution} for describing a reached call.
     #
     # To add an architecture, see +docs/adding-an-architecture.md+; +AArch64+ is
     # the simplest example.
     class Base
+      include ArgumentResolution
+      include CandidateWalk
+      include Disassembly
+      include DynamicSymbols
+
       # 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.
+      # @param [Symbol] kind What is being cached, so two kinds may share a command.
+      # @param [String] command The objdump command the value is a function of.
+      # @yieldreturn [Object] The value, computed only on a miss.
+      # @return [Object] The cached value.
       def self.cached(kind, command)
         @cached ||= Hash.new { |h, k| h[k] = {} }
         @cached[kind][command] ||= yield
@@ -78,38 +59,25 @@ module OneGadget
       # @return [Array<OneGadget::Gadget::Gadget>] Gadgets found.
       def find
         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
-        end
-        gadgets
+        # Reading the disassembly first settles the command the answer is a
+        # function of: how a file with no section headers is read is decided
+        # there. Each gadget is handed out as a copy, since a caller may write to
+        # one (see {OneGadget::Gadget::Gadget#base}).
+        disassembly
+        Base.cached(:gadgets, @objdump.command) { search }.map(&:dup)
       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.
+      # Every suffix of +lines+, longest last, cut at the terminal call it reaches
+      # -- emulation ends there, so anything past one never executes.
       # @param [Array<String>] lines One candidate, as a line list.
       # @yieldparam [Array<String>] window
       # @return [void]
+      # @example A candidate holding two terminal calls; no window runs past the
+      #   one it reaches.
+      #   lines = ['1000: mov r0, r1', '1004: bl <execve>',
+      #            '1008: mov r1, r2', '100c: bl <execl>']
+      #   [].tap { |a| executed_windows(lines) { |w| a << w.map { |l| l[/\A\w+/] } } }
+      #   #=> [['1008', '100c'], ['1004'], ['1000', '1004']]
       def executed_windows(lines)
         stop = lines.size - 1 if terminal_call_line?(lines.last)
         (lines.size - 2).downto(0) do |i|
@@ -122,10 +90,10 @@ module OneGadget
       # 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.
+      # @param [String] line One disassembled line.
+      # @return [Boolean]
       def terminal_call_line?(line)
-        return false unless line[/\A\s*[0-9a-f]+:\s*(\S+)/, 1]&.match?(/\A#{call_str}x?(?:\.[wn])?\z/)
+        return false unless call_line?(line)
 
         name = line[/<([^@>]+)/, 1]
         !name.nil? && OneGadget::Emulators::Processor::TERMINAL_CALL_RE.match?(name)
@@ -146,6 +114,8 @@ module OneGadget
       end
 
       # Emulate a candidate suffix and turn it into a gadget, or +nil+ if it isn't one.
+      # @param [Array<String>] lines The suffix, ending at the terminal call.
+      # @return [OneGadget::Gadget::Gadget, nil]
       def resolve_suffix(lines)
         processor = emulate(lines)
         (@refused ||= {})[processor.refused_line] = true if processor.refused_line
@@ -166,323 +136,86 @@ module OneGadget
         OneGadget::Gadget::Gadget.new(offset_of(lines.first), **options)
       end
 
-      # Fetch candidates that end with call exec*.
-      #
-      # Provide a block to filter gadget candidates.
-      # @yieldparam [String] cand
-      #   Is this candidate valid?
-      # @yieldreturn [Boolean]
-      #   True for valid.
-      # @return [Array<String>]
-      #   Each +String+ returned is multi-lines of assembly code.
-      def candidates(&)
-        branch_aware_candidates(&)
-      end
-
       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
+      # Every gadget in the disassembly: each candidate walked back from a
+      # terminal call, cut into the windows that reach it, emulated one apiece.
+      # @return [Array<OneGadget::Gadget::Gadget>]
+      def search
+        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)
 
-      # 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
-
-      def argv_already_valid?(argv)
-        argv[0] == '0' || (global_var?(argv[0]) && argv[1] == '0')
-      end
-
-      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
+            seen[key] = true
+            next if refused_before_call?(suffix)
 
-      # @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]}"
+            gadget = resolve_suffix(suffix)
+            gadgets << gadget unless gadget.nil?
           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
+        gadgets
       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}.
+      # Whether +line+ is a call, whatever it calls. The mnemonic must be the call
+      # itself, so a branch to a symbol whose name merely looks like one is not
+      # counted.
+      # @param [String] line One disassembled line.
       # @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.
-        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 :)
-          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 : "#{envp_ptr} == NULL || {#{envp.join(', ')}, ...} is a valid envp"
-        else
-          cons = "[#{envp_ptr}] == NULL || #{envp_ptr} == NULL || #{envp_ptr} is a valid envp"
-        end
-        return nil if cons.nil?
-
-        yield cons
+      # @example A call, and a branch into the middle of the same function.
+      #   call_line?('e6570: call   94180 <execve>')          #=> true
+      #   call_line?('a34d0: b      a3210 <execlp+0x1a8>')    #=> false
+      def call_line?(line)
+        line[/\A\s*[0-9a-f]+:\s*(\S+)/, 1]&.match?(call_mnemonic) || false
+      end
+
+      # The mnemonics {#call_str} names, as the whole of one. Built once: it comes
+      # out of a constant, and a search asks it of every line of a libc.
+      # @return [Regexp]
+      # @example On arm, where a call carries an +x+ and a width suffix.
+      #   call_mnemonic.match?('blx')  #=> true
+      #   call_mnemonic.match?('bl.w') #=> true
+      #   call_mnemonic.match?('b')    #=> false
+      def call_mnemonic
+        @call_mnemonic ||= /\A#{call_str}x?(?:\.[wn])?\z/
+      end
+
+      # Whether +line+ transfers control, so the address it names is a place in
+      # the file rather than a value it works with.
+      # @param [String] line One disassembled line.
+      # @return [Boolean]
+      def control_transfer?(line)
+        !branch_kind(line).nil? || call_line?(line)
       end
 
-      # Resolve +call execl+ cases.
-      def resolve_execl(processor)
-        return unless str_bin_sh?(processor.argument(0).to_s)
+      # What a libc calls the variable holding the environment a process started
+      # with, allowing for the aliases exported beside it (+_environ+, +__environ+).
+      ENVIRON = /\A_*environ\z/
+      private_constant :ENVIRON
 
-        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
+      # Whether +str+ names the address of that variable. An architecture that can
+      # say which symbol an address belongs to answers this; the rest cannot, and
+      # recognise the environment by the shape of the pointer instead (see
+      # {ArgumentResolution#check_envp}).
+      # @param [String] _str A rendered value.
+      # @return [Boolean]
+      def environ?(_str) = false
 
-      def global_var?(_str); raise NotImplementedError
+      # Whether +str+ references a libc global, i.e. an address the caller does not
+      # choose. An arch reaching its globals through a register (i386's GOT)
+      # overrides this against that register instead.
+      # @param [String] str A rendered value.
+      # @return [Boolean]
+      # @example The +$base+-relative form an arch produces once it concretizes a
+      #   pc-relative operand.
+      #   global_var?('$base+0x3ed8e0') #=> true
+      #   global_var?('[$base+0x10]')   #=> true
+      #   global_var?('rax')            #=> false
+      def global_var?(str)
+        base_relative?(str, '$base')
       end
 
       # Whether +str+ names a value at a fixed offset from +base+, i.e. an address
@@ -518,10 +251,38 @@ module OneGadget
         "#{holder} is the GOT address of libc"
       end
 
-      def str_bin_sh?(_str); raise NotImplementedError
+      # Whether +str+ references the +"/bin/sh"+ string. The default recognises the
+      # +$base+-relative form (see {#global_var?}); an arch that renders the address
+      # differently overrides it.
+      # @param [String] str A rendered value.
+      # @return [Boolean]
+      def str_bin_sh?(str)
+        str.include?('$base') && str.include?(bin_sh_offset.to_s(16))
+      end
+
+      # Whether +str+ references the standalone +"sh"+ string glibc passes as
+      # argv[0] in +execl("/bin/sh", "sh", ...)+. False for a libc that has none.
+      # @param [String] str A rendered value.
+      # @return [Boolean]
+      def str_sh?(str)
+        !sh_offset.nil? && str.include?('$base') && str.include?(sh_offset.to_s(16))
       end
 
-      def str_sh?(_str); raise NotImplementedError
+      # File offset of the +"/bin/sh"+ string.
+      # @return [Integer]
+      def bin_sh_offset
+        @bin_sh_offset ||= str_offset('/bin/sh')
+      end
+
+      # File offset of the standalone +"sh"+ string (\0-preceded and
+      # \0-terminated). Its distance from +"/bin/sh"+ is build-specific, so locate
+      # it directly instead of guessing.
+      # @return [Integer?] +nil+ when the libc has no such string.
+      def sh_offset
+        return @sh_offset if defined?(@sh_offset)
+
+        idx = file_bytes.index("\x00sh\x00")
+        @sh_offset = idx && idx + 1
       end
 
       def call_str; raise NotImplementedError
@@ -556,17 +317,6 @@ module OneGadget
         @file_bytes ||= File.binread(file)
       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
-
       # 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
@@ -619,13 +369,10 @@ module OneGadget
       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.
+      # without the caller arranging anything.
+      # @example Offsets from one base compare; the slots they address do not.
+      #   comparable_values('r1', 'r1+0x4')     #=> [0, 4]
+      #   comparable_values('[r1]', '[r1+0x4]') #=> nil
       # @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
@@ -654,118 +401,6 @@ module OneGadget
         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
@@ -785,102 +420,13 @@ module OneGadget
       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+.
+      # The addresses in +data+ (loaded at +base+) of 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.
+      #
+      # How an instruction is spelled in those bytes is the architecture's to say,
+      # not the file's: ARM and AArch64 keep theirs little-endian in a big-endian
+      # file, so both read words little-endian whatever the file says.
       # @param [Integer] _base
       # @param [String] _data
       # @param [Hash{Integer => true}] _targets
@@ -888,44 +434,6 @@ module OneGadget
       #   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
@@ -933,12 +441,6 @@ module OneGadget
       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
 end