one_gadget 1.10.0 → 2.1.0

data/lib/one_gadget/fetchers/base.rb

@@ -1,16 +1,51 @@
 # frozen_string_literal: true
 
+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
-  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),
+    # 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
 
+      # 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
+      end
+
       # Instantiate a fetcher object.
       # @param [String] file Absolute path to the target libc.
       def initialize(file)
@@ -23,282 +58,388 @@ 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..])
-            options = resolve(processor)
-            next if options.nil? # impossible to be a gadget
-
-            offset = offset_of(lines[i])
-            gadgets << OneGadget::Gadget::Gadget.new(offset, **options)
-          end
-          gadgets
-        end.flatten
+        str_offset('/bin/sh') # ensure it's glibc-like; raises "not glibc?" if not found
+        # 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
 
-      # 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(&)
-        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
+      # 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|
+          stop = i if terminal_call_line?(lines[i])
+          yield(stop ? lines[i..stop] : lines[i..])
         end
-        # remove all jmps
-        cands = slice_prefix(cands, &method(:branch?))
-        cands.select!(&) if block_given?
-        cands
       end
 
-      private
+      # 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.
+      # @param [String] line One disassembled line.
+      # @return [Boolean]
+      def terminal_call_line?(line)
+        return false unless call_line?(line)
+
+        name = line[/<([^@>]+)/, 1]
+        !name.nil? && OneGadget::Emulators::Processor::TERMINAL_CALL_RE.match?(name)
+      end
 
-      # 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 = processor.argument(0).to_s
-        arg1 = processor.argument(1).to_s
-        arg2 = processor.argument(2).to_s
-        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)
-
-        # 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
+      # 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
 
-        { constraints: cons, envp: }
+      # 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
+        # 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
 
-      def check_argv(processor, arg, allow_null)
-        lmda = OneGadget::Emulators::Lambda.parse(arg)
+      private
 
-        if lmda.deref_count.zero? && OneGadget::ABI.stack_register?(lmda.obj)
-          return check_stack_argv(processor, lmda, allow_null)
+      # 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)
+
+            seen[key] = true
+            next if refused_before_call?(suffix)
+
+            gadget = resolve_suffix(suffix)
+            gadgets << gadget unless gadget.nil?
+          end
         end
+        gadgets
+      end
 
-        check_nonstack_argv(arg, allow_null)
+      # 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 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
 
-      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 }
+      # 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
 
-        # if argv is already valid, no constraints are needed! (but probably won't happen :p)
-        return if argv_already_valid?(argv)
+      # 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
 
-        return generate_argv_with_sh(argv) if global_var?(argv[0])
+      # 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
+
+      # 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
+
+      # 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
 
-        generate_argv_without_sh(argv, allow_null)
+      # 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
 
-      def argv_already_valid?(argv)
-        argv[0] == '0' || (global_var?(argv[0]) && argv[1] == '0')
+      # 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 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])
-            "{\"sh\", \"-c\", #{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
+      # 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
 
-      def generate_argv_without_sh(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"'
-          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, arg cannot be NULL.
-          # TODO: Find a better way to check can arg be NULL
-          "#{arg} == NULL || #{argv[0]} == NULL || #{argv_cons}"
-        else
-          "#{argv[0]} == NULL || #{argv_cons}"
-        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 check_nonstack_argv(arg, allow_null)
-        if allow_null
-          "[#{arg}] == NULL || #{arg} == NULL || #{arg} is a valid argv"
-        else
-          "[#{arg}] == NULL || #{arg} is a valid argv"
-        end
+      # File offset of the +"/bin/sh"+ string.
+      # @return [Integer]
+      def bin_sh_offset
+        @bin_sh_offset ||= str_offset('/bin/sh')
       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?('[[')
-
-        lmda = OneGadget::Emulators::Lambda.parse(arg)
-        if lmda.deref_count.zero? && OneGadget::ABI.stack_register?(lmda.obj)
-          # 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 }
-          # 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"
-        else
-          cons = "[#{arg}] == NULL || #{arg} == NULL || #{arg} is a valid envp"
-        end
-        return nil if cons.nil?
+      # 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)
 
-        yield cons
+        idx = file_bytes.index("\x00sh\x00")
+        @sh_offset = idx && idx + 1
       end
 
-      # Resolve +call execl+ cases.
-      def resolve_execl(processor)
-        return unless str_bin_sh?(processor.argument(0).to_s)
+      def call_str; raise NotImplementedError
+      end
 
-        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) }
-        res = resolve_execve_args(processor, args[1].to_s, args[4].to_s, args[5].to_s, 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} <= 0" if arg2.to_s != '0'
-        arg3 = args[3]
-        cons << "#{arg3} == NULL || (u16)#{arg3.deref} == NULL" if arg3.to_s != '0'
+      # 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
 
-        { constraints: cons, effect: %(posix_spawn(#{arg0}, "/bin/sh", #{arg2}, #{arg3}, #{args[4]}, #{res[:envp]})) }
+      def emulator; raise NotImplementedError
       end
 
-      def global_var?(_str); raise NotImplementedError
+      def objdump_options
+        []
       end
 
-      def str_bin_sh?(_str); raise NotImplementedError
+      def str_offset(str)
+        file_bytes.index("#{str}\x00") ||
+          raise(Error::ArgumentError, "File #{file.inspect} doesn't contain string #{str.inspect}, not glibc?")
       end
 
-      def str_sh?(_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 call_str; raise NotImplementedError
+      # 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
 
-      def emulate(cmds)
-        cmds.each_with_object(emulator) { |cmd, obj| break obj unless obj.process(cmd) }
+      # 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 emulator; raise NotImplementedError
+      def offset_of(assembly)
+        assembly[/\A([\da-f]+):/, 1].to_i(16)
       end
 
-      def objdump_options
-        []
+      # 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
 
-      def slice_prefix(cands, &block)
-        cands.map do |cand|
-          lines = cand.lines
-          to_rm = lines[0...-1].rindex(&block)
-          lines = lines[to_rm + 1..] unless to_rm.nil?
-          lines.join
+      # The two sides of a relation as plain numbers, when they can be compared
+      # 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
+      #   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
 
-      # If str contains a branch instruction.
-      def branch?(_str); raise NotImplementedError
+      def tautology?(con)
+        trivial_relation(con) == true
       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?")
+      def contradiction?(con)
+        trivial_relation(con) == false
       end
 
-      def offset_of(assembly)
-        assembly.scan(/^([\da-f]+):/)[0][0].to_i(16)
+      # 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 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
+      # @return [Array<Integer>, nil] +nil+ from an arch with no cheap call finder,
+      #   which disassembles everything instead.
+      def scan_calls(_base, _data, _targets) = nil
+
+      # 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
     end
   end