one_gadget 1.10.0 → 2.1.0

data/lib/one_gadget/fetchers/x86.rb

@@ -1,16 +1,72 @@
 # frozen_string_literal: true
 
+require 'one_gadget/emulators/x86'
 require 'one_gadget/fetchers/base'
 
 module OneGadget
-  module Fetcher
+  module Fetchers
     # Define common methods for gadget fetchers.
     class X86 < Base
+      # Conditional-jump mnemonics (shared with the emulator).
+      JCC = OneGadget::Emulators::X86::JCC
+
       private
 
-      # If str contains a branch instruction.
-      def branch?(str)
-        %w[jmp je jne jl jb ja jg].any? { |f| str.include?(f) }
+      # Emulate only the candidates that could still become a gadget. x86 writes
+      # the address of a string as a displacement, so a window that reaches
+      # +"/bin/sh"+ names it outright -- except through +posix_spawn+, which takes
+      # the path as an argument a window need not have materialised itself.
+      #
+      # This lives here rather than in {Base} because an architecture building such
+      # an address in pieces (+adrp+ then +add+) can state no such rule: filtering
+      # aarch64 on the same test drops all but one of its gadgets.
+      def candidates
+        reference = bin_sh_reference.to_s(16)
+        super do |candidate|
+          candidate.match?(TERMINAL_SPAWN) || candidate.include?(reference)
+        end
+      end
+
+      # The number a window holds when it points at the +"/bin/sh"+ string.
+      # @return [Integer]
+      def bin_sh_reference = bin_sh_offset
+
+      # A direct near call, +E8+ then a 32-bit displacement from the instruction
+      # after it.
+      CALL_REL32 = "\xe8".b.freeze
+      private_constant :CALL_REL32
+      CALL_REL32_SIZE = 5
+      private_constant :CALL_REL32_SIZE
+
+      # x86 instructions are variable length, so a byte in the middle of one can
+      # read as a call; that costs a window nothing is found in, where missing a
+      # real call would cost the gadgets around it.
+      def scan_calls(base, data, targets)
+        sites = []
+        pos = 0
+        while (pos = data.index(CALL_REL32, pos))
+          displacement = data.byteslice(pos + 1, 4)
+          break if displacement.nil? || displacement.bytesize < 4
+
+          addr = base + pos
+          sites << addr if targets.key?(addr + CALL_REL32_SIZE + displacement.unpack1('l<'))
+          pos += 1
+        end
+        sites
+      end
+
+      def branch_lead_chars
+        'j'
+      end
+
+      # +jcc+/+jcxz+ are conditional; a direct +jmp+ is unconditional while an
+      # indirect one (+jmp rax+, +jmp QWORD PTR [..]+) and +ret+/+leave+ terminate.
+      def branch_kind(line)
+        m = mnemonic(line)
+        return :conditional if JCC.key?(m) || %w[jcxz jecxz jrcxz].include?(m)
+        return branch_target(line).nil? ? :terminator : :unconditional if m == 'jmp'
+
+        :terminator if m.start_with?('ret') || m == 'leave'
       end
 
       def objdump_options

data/lib/one_gadget/fetchers.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'one_gadget/error'
+require 'one_gadget/fetchers/aarch64'
+require 'one_gadget/fetchers/amd64'
+require 'one_gadget/fetchers/arm'
+require 'one_gadget/fetchers/i386'
+require 'one_gadget/fetchers/mips'
+require 'one_gadget/fetchers/riscv64'
+require 'one_gadget/gadget'
+require 'one_gadget/helper'
+
+module OneGadget
+  # To find gadgets.
+  module Fetchers
+    # At and above this level, keep every distinct gadget instead of trimming
+    # down to the easiest-to-reach set (see {ClassMethods#from_file}).
+    RAW_LEVEL = 2
+
+    # The fetcher each architecture is searched with, and so the set of
+    # architectures this tool supports (see {ClassMethods#supported_architecture?}).
+    FETCHERS = {
+      aarch64: OneGadget::Fetchers::AArch64,
+      amd64: OneGadget::Fetchers::Amd64,
+      arm: OneGadget::Fetchers::Arm,
+      i386: OneGadget::Fetchers::I386,
+      mips: OneGadget::Fetchers::Mips,
+      riscv64: OneGadget::Fetchers::Riscv64
+    }.freeze
+
+    # Define class methods here.
+    module ClassMethods
+      # Fetch one-gadget offsets of this build id.
+      # @param [String] build_id The targets' BuildID.
+      # @param [Boolean] remote
+      #   When local not found, try search in latest version?
+      # @param [Integer] level
+      #   Output level, interpreted as in {#from_file}.
+      # @return [Array<OneGadget::Gadget::Gadget>?]
+      #   +nil+ is returned if cannot find target id in database.
+      def from_build_id(build_id, remote: true, level: 0)
+        OneGadget::Helper.verify_build_id!(build_id)
+        gadgets = OneGadget::Gadget.builds(build_id, remote:)
+        gadgets && for_level(gadgets, level)
+      end
+
+      # Fetch one-gadget offsets from file.
+      # @param [String] file The absolute path of libc file.
+      # @param [Integer] level
+      #   Output level. Below {RAW_LEVEL} the result is trimmed to the
+      #   easiest-to-reach gadgets ({#trim_gadgets}); at {RAW_LEVEL} and above
+      #   every distinct gadget is kept ({#all_gadgets}), including ones a lower
+      #   level drops as duplicate or harder-to-satisfy.
+      # @return [Array<OneGadget::Gadget::Gadget>]
+      #   Array of all found gadgets is returned.
+      def from_file(file, level: 0)
+        arch = OneGadget::Helper.architecture(file)
+        klass = FETCHERS[arch]
+        raise Error::UnsupportedArchitectureError, arch if klass.nil?
+
+        for_level(klass.new(file).find, level)
+      end
+
+      # Whether gadgets can be searched for in +arch+. The ELF reader recognises
+      # plenty this tool cannot emulate.
+      # @param [Symbol] arch As {OneGadget::Helper.architecture} names it.
+      # @return [Boolean]
+      def supported_architecture?(arch)
+        FETCHERS.key?(arch)
+      end
+
+      private
+
+      # Narrow a complete gadget set down to what an output level asks for.
+      # @param [Array<OneGadget::Gadget::Gadget>] gadgets
+      # @param [Integer] level
+      # @return [Array<OneGadget::Gadget::Gadget>]
+      def for_level(gadgets, level)
+        level >= RAW_LEVEL ? all_gadgets(gadgets) : trim_gadgets(gadgets)
+      end
+
+      # Keep every distinct gadget, dropping only exact +(offset, constraints)+
+      # repeats (the same suffix reached by more than one candidate path). Unlike
+      # {#trim_gadgets} this keeps duplicate-constraint and dominated gadgets, and
+      # lists an offset once per constraint set it can be reached under.
+      def all_gadgets(gadgets)
+        gadgets.uniq { |g| [g.offset, g.constraints] }
+               .sort_by { |g| [g.offset, g.constraints.size] }
+      end
+
+      # Unique, remove gadgets whose constraints already meet an easier gadget's
+      # (see {OneGadget::Gadget::Gadget#met_by?}): that one is the better answer,
+      # and this one asks the reader for strictly more.
+      def trim_gadgets(gadgets)
+        # Order totally before anything is dropped: each step below keeps
+        # whichever of several equally good gadgets it meets first, so without a
+        # tie-break the answer depends on the order gadgets were discovered in
+        # rather than on the libc alone. Gadgets sharing a constraint set are
+        # interchangeable -- whoever satisfies one satisfies them all -- so the
+        # last of them represents the set: it is the one that reaches the call
+        # with the least code in between.
+        gadgets = gadgets.sort_by { |g| [g.constraints.size, -g.offset, g.constraints] }
+                         .uniq(&:constraints)
+        res = []
+        gadgets.each_with_index do |g, i|
+          res << g unless i.times.any? { |j| gadgets[j].met_by?(g) }
+        end
+        # The same offset can reach the call via more than one branch direction;
+        # list it once, keeping the easiest (fewest-constraint) variant.
+        res.group_by(&:offset).map { |_, gs| gs.min_by { |g| g.constraints.size } }.sort_by(&:offset)
+      end
+    end
+    extend ClassMethods
+  end
+end

data/lib/one_gadget/gadget.rb

@@ -10,6 +10,23 @@ module OneGadget
   # Module for define gadgets.
   module Gadget
     # Information of a gadget.
+    #
+    # Its {Gadget#constraints} are written in this language:
+    #   REG: OneGadget::ABI.all
+    #   IMM: [+-]0x[\da-f]+
+    #   BITS: 8, 16, 32, 64
+    #   CAST: (<s|u><BITS>)
+    #   Identity: <REG><IMM>?
+    #   Identity: [<Identity>]
+    #   Expr: <REG> is the GOT address of libc
+    #   Expr: writable: <Identity>
+    #   Expr: readable: <Identity>
+    #   Expr: <CAST>?<Identity> == NULL
+    #   Expr: <REG> & 0xf == <IMM>
+    #   Expr: (s32)[<Identity>] <= 0
+    #   Expr: .+ is a valid argv
+    #   Expr: .+ is a valid envp
+    #   Expr: <Expr> || <Expr>
     class Gadget
       # @return [Integer] Base address of libc. Default: 0.
       attr_accessor :base
@@ -19,6 +36,9 @@ module OneGadget
       attr_reader :constraints
       # @return [String] The final result of this gadget.
       attr_reader :effect
+      # @return [Array<String>] Where each descriptor this gadget closes before the
+      #   exec is read from, in the order it closes them (see {#caveats}).
+      attr_reader :closed_fds
 
       # Initialize method of {Gadget} instance.
       # @param [Integer] offset The relative address offset of this gadget.
@@ -29,17 +49,39 @@ module OneGadget
       def initialize(offset, **options)
         @base = 0
         @offset = offset
-        @constraints = options[:constraints] || []
+        @constraints = prune_settled(options[:constraints] || [])
         @effect = options[:effect] || ''
+        @closed_fds = options[:closed_fds] || []
       end
 
-      # Show gadget in a pretty way.
+      # What the gadget costs the caller beyond its constraints: a descriptor it
+      # closes on the way to the exec. Each line names the close itself, so it
+      # reads as the code does and can be matched exactly, and says what the value
+      # must avoid for the spawned shell to keep its I/O.
+      # @return [Array<String>]
+      # @example
+      #   ['close([rsp+0x44]): prevent it from being 0 (stdin) or 1 (stdout) ...']
+      def caveats
+        closed_fds.map do |fd|
+          "close(#{fd}): prevent it from being 0 (stdin) or 1 (stdout) to sound " \
+            'an interactive shell.'
+        end
+      end
+
+      # Returns a human-readable, colorized representation of this gadget,
+      # showing its address followed by the effect and constraints.
+      # @return [String] The multi-line pretty-printed gadget.
       def inspect
         str = "#{OneGadget::Helper.hex(value)} #{effect}\n"
         unless constraints.empty?
           str += "#{OneGadget::Helper.colorize('constraints')}:\n  "
           str += merge_constraints.join("\n  ")
         end
+        unless caveats.empty?
+          str += "\n" unless constraints.empty?
+          str += "#{OneGadget::Helper.colorize('caveats')}:\n  "
+          str += caveats.join("\n  ")
+        end
         str.gsub!(/0x[\da-f]+/) { |s| OneGadget::Helper.colorize(s, sev: :integer) }
         OneGadget::ABI.all.each do |reg|
           str.gsub!(/([^\w])(#{reg})([^\w])/, "\\1#{OneGadget::Helper.colorize('\2', sev: :reg)}\\3")
@@ -47,17 +89,21 @@ module OneGadget
         "#{str}\n"
       end
 
-      # @return [Hash]
+      # Converts this gadget into a plain hash, suitable for serialization.
+      # @return [Hash{Symbol => Integer, String, Array<String>, Array<Integer>}]
+      #   A hash with keys +:value+ (the absolute address), +:effect+ (the
+      #   resulting function call), +:constraints+ (the required constraints) and,
+      #   when the gadget closes a descriptor, +:closed_fds+ with the {#caveats}
+      #   they carry.
       def to_obj
-        {
-          value:,
-          effect:,
-          constraints:
-        }
+        obj = { value:, effect:, constraints: }
+        return obj if caveats.empty?
+
+        obj.merge(closed_fds:, caveats:)
       end
 
-      # To have this class can be serialized in JSON.
-      # @return [String]
+      # Serializes this gadget into a JSON string.
+      # @return [String] The gadget in JSON format. See {#to_obj} for the keys.
       def to_json(*)
         to_obj.to_json
       end
@@ -74,62 +120,308 @@ module OneGadget
         @score ||= constraints.reduce(1.0) { |s, c| s * calculate_score(c) }
       end
 
+      # Whether +other+ asks for everything this gadget asks for, so listing this
+      # one beside it tells the reader nothing new. Each constraint here has to be
+      # met by +other+'s list: named there, or -- for one that offers several
+      # options -- an option of it required there outright.
+      # @param [Gadget] other
+      # @return [Boolean]
+      # @example An option required outright meets the constraint offering it.
+      #   met_by?(other) # where this asks "r8 == NULL || (u16)[r8] == 0x0"
+      #                  # and +other+ asks "(u16)[r8] == 0x0"
+      def met_by?(other)
+        constraints.all? do |con|
+          other.constraints.include?(con) ||
+            con.split(DISJUNCTION).any? { |option| other.constraints.include?(option) }
+        end
+      end
+
+      # Every architecture's register names, for {#base_register} to recognise one
+      # by. Keyed for lookup: it is asked once per token of every constraint scored.
+      REGISTER_NAMES = OneGadget::ABI.all.to_h { |reg| [reg, true] }.freeze
+      private_constant :REGISTER_NAMES
+
+      # What separates the options of a constraint that can be met in more than
+      # one way.
+      DISJUNCTION = ' || '
+      private_constant :DISJUNCTION
+
+      # How far from an address a dereference can sit and still say the address
+      # is not NULL: within the smallest page, which a NULL base cannot reach out
+      # of.
+      PAGE_SIZE = 0x1000
+      private_constant :PAGE_SIZE
+
       private
 
-      # REG: OneGadget::ABI.all
-      # IMM: [+-]0x[\da-f]+
-      # BITS: 8, 16, 32, 64
-      # CAST: (<s|u><BITS>)
-      # Identity: <REG><IMM>?
-      # Identity: [<Identity>]
-      # Expr: <REG> is the GOT address of libc
-      # Expr: writable: <Identity>
-      # Expr: <CAST>?<Identity> == NULL
-      # Expr: <REG> & 0xf == <IMM>
-      # Expr: (s32)[<Identity>] <= 0
-      # Expr: .+ is a valid argv
-      # Expr: .+ is a valid envp
-      # Expr: <Expr> || <Expr>
+      # Drops what the rest of the list already settles, so a gadget asks for each
+      # thing once and never offers an option it rules out itself. Only a
+      # constraint holding outright settles anything, since one inside a +||+ is an
+      # option among several; the rules run until the list stops changing.
+      # @param [Array<String>] cons
+      # @return [Array<String>]
+      # @example An option the same list rules out.
+      #   prune_settled(['writable: r8', 'r8 == NULL || (u16)[r8] == 0x0'])
+      #   #=> ['writable: r8', '(u16)[r8] == 0x0']
+      # @example A readability the dereference beside it already states.
+      #   prune_settled(['readable: x1', '[x1] == 0x0']) #=> ['[x1] == 0x0']
+      # @example A non-NULL the dereference beside it already states.
+      #   prune_settled(['[$base+0x10] != 0x0', '[[$base+0x10]+0xa4] == 0x0'])
+      #   #=> ['[[$base+0x10]+0xa4] == 0x0']
+      # @example A bound the pinned value already satisfies.
+      #   prune_settled(['r0 == NULL', '(u32)r0 <= 0xfffff000']) #=> ['r0 == NULL']
+      def prune_settled(cons)
+        loop do
+          settled = drop_stated_readable(
+            drop_settled_comparison(drop_settled_non_null(drop_ruled_out_null(cons)))
+          )
+          return cons if settled == cons
+
+          cons = settled
+        end
+      end
+
+      # The constraints that hold outright, as opposed to naming several options.
+      # @param [Array<String>] cons
+      # @return [Array<String>]
+      def unconditional(cons)
+        cons.reject { |c| c.include?(DISJUNCTION) }
+      end
+
+      # Whether the list requires +identity+ to be mapped memory: a constraint
+      # holding outright either names it as one, or accesses it -- at the address
+      # itself, or near enough that a NULL one could not be what is accessed.
+      # @param [Array<String>] cons
+      # @param [String] identity
+      # @return [Boolean]
+      def mapped?(cons, identity)
+        deref = "[#{identity}]"
+        near = /\[#{Regexp.escape(identity)}([+-]0x[0-9a-f]+)\]/
+        unconditional(cons).any? do |con|
+          con == "readable: #{identity}" || con == "writable: #{identity}" || con.include?(deref) ||
+            (off = con[near, 1]) && off.to_i(16).abs < PAGE_SIZE
+        end
+      end
+
+      # Drops every option that asks an address the list requires to be mapped
+      # memory to be NULL. A constraint whose every option goes is left alone: it
+      # says the gadget is impossible, which is not this pass's call to make.
+      # @param [Array<String>] cons
+      # @return [Array<String>]
+      def drop_ruled_out_null(cons)
+        cons.map do |con|
+          options = con.split(DISJUNCTION)
+          next con if options.size == 1
+
+          kept = options.reject do |opt|
+            identity = opt[/\A(.+) == NULL\z/, 1]
+            !identity.nil? && mapped?(cons, identity)
+          end
+          kept.empty? ? con : kept.join(DISJUNCTION)
+        end
+      end
+
+      # Drops every requirement that an address the list requires to be mapped
+      # memory be non-NULL, which mapped memory never is.
+      # @param [Array<String>] cons
+      # @return [Array<String>]
+      def drop_settled_non_null(cons)
+        cons.reject do |con|
+          identity = con[/\A(.+) != (?:NULL|0x0)\z/, 1]
+          !identity.nil? && !identity.match?(/\A\([su]\d+\)/) && mapped?(cons, identity)
+        end
+      end
+
+      # A comparison against a literal: the cast that says how much of the value is
+      # compared and whether those bits read as signed, what is compared, and what
+      # it is compared with.
+      # @example +(u32)r0 <= 0xfffff000+, +[rbp-0x50] == 0x1+, +x2 == NULL+
+      COMPARISON = /\A(?:\(([su])(\d+)\))?(.+?) (==|!=|<=|>=|<|>) (NULL|-?(?:0x[0-9a-f]+|\d+))\z/
+      private_constant :COMPARISON
+
+      # Drops every comparison a value pinned elsewhere in the list already
+      # answers. Only an uncast equality pins a whole value -- +(u16)X == 0x0+
+      # leaves the rest of it unsaid -- and a comparison the pinned value does not
+      # satisfy is left alone: it says the gadget is impossible, which is not this
+      # pass's call to make.
+      # @param [Array<String>] cons
+      # @return [Array<String>]
+      def drop_settled_comparison(cons)
+        pinned = pinned_values(unconditional(cons))
+        return cons if pinned.empty?
+
+        cons.reject do |con|
+          parts = COMPARISON.match(con)
+          next false if parts.nil? || (parts[1].nil? && parts[4] == '==')
+
+          value = pinned[parts[3]]
+          !value.nil? && comparison_holds?(value, parts)
+        end
+      end
+
+      # What the list pins outright, by what is pinned.
+      # @param [Array<String>] held
+      # @return [Hash{String => Integer}]
+      def pinned_values(held)
+        held.each_with_object({}) do |con, pinned|
+          parts = COMPARISON.match(con)
+          next unless parts && parts[1].nil? && parts[4] == '=='
+
+          pinned[parts[3]] = literal_value(parts[5])
+        end
+      end
+
+      # Whether a comparison already holds for a value pinned to +value+.
+      # @param [Integer] value
+      # @param [MatchData] parts A {COMPARISON} match.
+      # @return [Boolean]
+      def comparison_holds?(value, parts)
+        value = as_cast(value, parts[1], parts[2]) if parts[1]
+        value.public_send(parts[4], literal_value(parts[5]))
+      end
+
+      # +value+ as a cast reads it: the low +bits+ of it, negative when those bits
+      # are read as signed and the top one is set.
+      def as_cast(value, sign, bits)
+        bits = Integer(bits)
+        low = value & ((1 << bits) - 1)
+        sign == 's' && low >= (1 << (bits - 1)) ? low - (1 << bits) : low
+      end
+
+      # @param [String] literal +NULL+ or a number, as a constraint writes it.
+      # @return [Integer]
+      def literal_value(literal)
+        literal == 'NULL' ? 0 : Integer(literal)
+      end
+
+      # Drops every +readable:+ whose address another constraint dereferences
+      # outright, which asks for that readability already. Unlike {#mapped?} this
+      # takes only the address itself: a dereference nearby says the page it lands
+      # on is mapped, not the one +identity+ sits on.
+      # @param [Array<String>] cons
+      # @return [Array<String>]
+      def drop_stated_readable(cons)
+        cons.reject do |con|
+          identity = con[/\Areadable: (.+)\z/, 1]
+          next false if identity.nil?
+
+          unconditional(cons).any? { |other| other.include?("[#{identity}]") }
+        end
+      end
+
       def calculate_score(expr)
         return expr.split(' || ').map(&method(:calculate_score)).max if expr.include?(' || ')
 
+        return 0.95 if stack_alignment?(expr)
+        # Zero is the easy value to arrange and every other one is hard, so a mask
+        # tells them apart rather than making them easier: some of a value's bits
+        # zeroed is a little easier than all of them, while a mask asking for any
+        # other value is as hard as asking for it anywhere.
+        return 0.92 if MASKED_ZERO.match?(expr)
+        # Any other mask asks for a particular value, which the mask does nothing
+        # to make easier, so it is the relation it looks like.
+        return calculate_relation_score(expr) if MASKED.match?(expr)
+
         case expr
-        when / & 0xf/ then 0.95
         when /GOT address/ then 0.9
         when /^writable/ then calculate_writable_score(expr.sub('writable: ', ''))
-        when / == NULL$/ then calculate_null_score(expr.sub(' == NULL', ''))
-        when / <= 0$/ then calculate_null_score(expr.sub(' <= 0', ''))
-        when / is a valid (argv|envp)$/ then 0.2 # This usually means the register has to be a readable pointer.
+        # However a "must be zero" is spelled -- NULL where the value is a pointer,
+        # 0x0 where it is not, with or without a size cast, and <= for a signed
+        # field -- it asks for the same thing, and asking for zero is easier than a
+        # relation that names some other value.
+        when / == NULL$/, / == 0x0$/, / <= 0x0$/
+          calculate_null_score(expr.sub(/ (?:==|<=) (?:NULL|0x0)\z/, ''))
+        # A register that just has to be a readable pointer -- a "readable: <reg>"
+        # (a dereferenced call arg) or a valid argv/envp element -- is easy.
+        when /^readable/, / is a valid (argv|envp)$/ then 0.2
+        when / (==|!=|<=|>=|<|>) / then calculate_relation_score(expr) # a branch condition
         end
       end
 
+      # Some of a value's bits required to be zero: +(eax & 0xf000) == 0x0+, or the
+      # unparenthesised +eax & 0xf == 0x0+ an alignment renders as. A mask against
+      # any other value is not one of these -- that is as hard as asking for that
+      # value anywhere. Nor is a mask by a register (+(x0 & x1) == 0x0+), which
+      # pins no bit anyone knows, nor one inside what is compared
+      # (+[(rsi & 0xf0)] == NULL+), where the whole word still has to be zero.
+      MASKED_ZERO = /\A\(?[^()]+? & ~?(?:0x[0-9a-f]+|\d+)\)? == (?:NULL|0x0+)\z/
+      private_constant :MASKED_ZERO
+
+      # A comparison whose left side is masked, whatever it is compared with.
+      MASKED = /\A\(?[^()]+? & [^()]+?\)? (?:==|!=|<=|>=|<|>) /
+      private_constant :MASKED
+
+      # Whether +expr+ is the alignment an aligned store imposes (see
+      # {OneGadget::Emulators::X86#inst_movaps}): the stack pointer's low bits
+      # must hold a fixed value, which is free -- the caller picks where the
+      # stack sits. Matched exactly, so a masked value the caller has to arrange
+      # stays what it is.
+      # @example matches +rsp & 0xf == 0x0+; not +(eax & 0xf000) == 0x2000+
+      def stack_alignment?(expr)
+        reg = expr[/\A(\S+) & 0xf == 0x[0-9a-f]+\z/, 1]
+        !reg.nil? && OneGadget::ABI.stack_register?(reg)
+      end
+
+      # Score a branch-derived relational constraint such as +x2 == 0x1+ or
+      # +(u64)x0 >= 0x400+: an equality on one specific value is harder than an
+      # inequality/range, and a dereferenced left-hand side is harder still.
+      def calculate_relation_score(expr)
+        op = expr[/ (==|!=|<=|>=|<|>) /, 1]
+        lhs = expr.split(/ #{Regexp.escape(op)} /, 2).first.sub(/\A\([su]\d+\)/, '')
+        base = op == '==' ? 0.4 : 0.6
+        base * 0.9**deref_depth(lhs)
+      end
+
+      # How many dereferences +identity+ is behind, read off the rendering that
+      # produced it -- a lambda emits one +[+ per dereference.
+      # @example deref_depth('[[ebp+0x10]]') #=> 2
+      def deref_depth(identity)
+        identity[/\A\[*/].size
+      end
+
+      # The register +identity+ is derived from: the first one it names, since a
+      # rendering puts its base ahead of whatever is applied to it. +nil+ when it
+      # names none, e.g. a libc-relative +$base+0x10+.
+      # @example base_register('[(rsi & 0xfffffffffffffff0)+0x10]') #=> 'rsi'
+      def base_register(identity)
+        identity.scan(/\w+/).find { |token| REGISTER_NAMES.key?(token) }
+      end
+
+      # Whether +identity+ is a register itself rather than a value derived from
+      # one. Asked of an undereferenced identity, where being the register is
+      # what makes a requirement on it cheap to meet.
+      # @example bare_register?('rax') #=> true
+      # @example bare_register?('rax+0x10'), bare_register?('(rax & 0xf0)') #=> false
+      def bare_register?(identity)
+        identity == base_register(identity)
+      end
+
       def calculate_writable_score(identity)
-        lmda = OneGadget::Emulators::Lambda.parse(identity)
-        return 0.81 if lmda.deref_count != 0
+        return 0.81 unless deref_depth(identity).zero?
 
-        OneGadget::ABI.stack_register?(lmda.obj) ? 0.95 : 0.81
+        OneGadget::ABI.stack_register?(base_register(identity)) ? 0.95 : 0.81
       end
 
       def calculate_null_score(identity)
-        # remove <CAST>
-        identity.sub!(/^\([s|u]\d+\)/, '')
-        # Thank God we are already able to parse this
-        lmda = OneGadget::Emulators::Lambda.parse(identity)
+        identity = identity.sub(/\A\([su]\d+\)/, '') # remove <CAST>
+        depth = deref_depth(identity)
         # rax == 0 is easy; rax + 0x10 == 0 is damn hard.
-        return lmda.immi.zero? ? 0.9 : 0.1 if lmda.deref_count.zero?
+        return bare_register?(identity) ? 0.9 : 0.1 if depth.zero?
 
         # [sp+xx] == NULL is easy.
-        base = OneGadget::ABI.stack_register?(lmda.obj) ? 0 : 1
-        0.9**(lmda.deref_count + base)
+        base = OneGadget::ABI.stack_register?(base_register(identity)) ? 0 : 1
+        0.9**(depth + base)
       end
 
+      # The constraints as a reader wants them: every +writable:+ folded into one
+      # sentence naming all of the addresses, the rest left alone.
       def merge_constraints
         key = 'writable: '
         w_cons, normal = constraints.partition { |c| c.start_with?(key) }
         return normal if w_cons.empty?
 
         w_cons.map! { |c| c[key.size..] }
-        ["address#{w_cons.size > 1 ? 'es' : ''} #{w_cons.join(', ')} #{w_cons.size > 1 ? 'are' : 'is'} writable"] +
+        ["address#{'es' if w_cons.size > 1} #{w_cons.join(', ')} #{w_cons.size > 1 ? 'are' : 'is'} writable"] +
           normal
       end
     end
@@ -192,12 +484,13 @@ module OneGadget
       end
 
       # Add a gadget, for scripts in builds/ to use.
+      #
+      # Keyword arguments are forwarded to {Gadget#initialize}.
       # @param [String] build_id The target's build id.
       # @param [Integer] offset The relative address offset of this gadget.
-      # @param [Hash] options See {Gadget::Gadget#initialize} for more information.
       # @return [void]
-      def add(build_id, offset, **options)
-        BUILDS[build_id] << OneGadget::Gadget::Gadget.new(offset, **options)
+      def add(build_id, offset, **)
+        BUILDS[build_id] << OneGadget::Gadget::Gadget.new(offset, **)
       end
 
       private