one_gadget 2.0.0 → 2.1.0

data/lib/one_gadget/fetchers/candidate_walk.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module OneGadget
+  module Fetchers
+    # Where a gadget could start: a backward control-flow walk from each terminal
+    # call, yielding every instruction sequence that reaches it. A conditional
+    # branch on the way is explored both ways and its decision becomes a constraint
+    # on the candidate, bounded so a loop-heavy region cannot fork forever. Mixed
+    # into {Base}.
+    module CandidateWalk
+      # 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
+
+      # 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
+
+      # 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)
+        # Out of budget is a place to stop walking, not a reason to throw away
+        # what has been walked: the lines already on the path reach the call
+        # whether or not anything before them is ever looked at.
+        return blk.call(path.dup) 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
+
+      # 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
+    end
+  end
+end

data/lib/one_gadget/fetchers/disassembly.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'elftools'
+
+module OneGadget
+  module Fetchers
+    # Reading the target file: where its terminal calls are, and the disassembly
+    # around them. Disassembling a whole libc is the dominant cost of a search, so
+    # an architecture that can find its call sites cheaply gets windows around them
+    # instead (see {Base#scan_calls}), and everything derived from one objdump
+    # command is cached. Mixed into {Base}.
+    module Disassembly
+      # What a terminal function's name starts with. Read by {DynamicSymbols} too,
+      # which finds the same functions by another route.
+      TERMINAL_PREFIXES = %w[exec posix_spawn].freeze
+
+      # A call to +posix_spawn+ itself, not one of the setup helpers that share its
+      # prefix. The name ends at the version marker, or at the closing bracket when
+      # there is none -- glibc's symbols are versioned, musl's are not, and neither
+      # is one recovered from a file with no symbol table (see {DynamicSymbols}).
+      TERMINAL_SPAWN = /posix_spawn[@>]/
+
+      # 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_PREFIX_BYTES = 12
+      private_constant :TERMINAL_PREFIX_BYTES
+
+      # How much to disassemble around each terminal call when an architecture can
+      # locate the calls cheaply (see {#terminal_call_sites} / {#windowed_disasm}).
+      #
+      # Measured against a full disassembly of every fixture: 0x368 back and 0x350
+      # forward is the least that reports the same gadgets. Both must stay a
+      # multiple of four -- objdump decodes from wherever it is told to start, so
+      # an offset landing mid-instruction turns the whole window into rubble
+      # rather than shifting it.
+      WINDOW_BACK = 0x1000
+
+      # As far past the call, for a predecessor that branches back into the region.
+      WINDOW_FWD = 0x1000
+
+      private
+
+      # 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
+
+      # The target's objdump disassembly as stripped +"ADDR: insn"+ lines.
+      def disasm_lines
+        disassembly[:lines]
+      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 ||= begin
+          # Before the command is read: it is what says how to disassemble, and
+          # what the cache is keyed on.
+          prepare_raw_disassembly if sectionless?
+          Base.cached(:disasm, @objdump.command) do
+            sites = terminal_call_sites
+            sites.nil? || sites.empty? ? full_disasm : windowed_disasm(sites)
+          end
+        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 range, 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)
+                       .flat_map { |lo, hi| decode_ranges(lo, hi) }
+                       .map { |lo, hi, extra| Thread.new { objdump_lines(start: lo, stop: hi, extra:) } }
+                       .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
+
+      # Whether this file ships without section headers, which is what makes the
+      # ordinary route to its code and symbols unavailable (see {DynamicSymbols}).
+      # @return [Boolean]
+      def sectionless?
+        return @sectionless unless @sectionless.nil?
+
+        @sectionless = File.open(file) { |fd| ELFTools::ELFFile.new(fd).num_sections.zero? }
+      end
+
+      # Point objdump at the bytes rather than the ELF, once, when there is no
+      # other way to read the file.
+      # @return [void]
+      def prepare_raw_disassembly
+        File.open(file) do |fd|
+          elf = ELFTools::ELFFile.new(fd)
+          seg = executable_segment(elf)
+          next if seg.nil?
+
+          @raw_symbols = dynamic_symbols(elf)
+          record_instruction_sets(elf)
+          @objdump.read_raw(machine: OneGadget::Helper.objdump_arch(OneGadget::Helper.architecture(file)),
+                            endian: elf.endian,
+                            vma: seg.mem_head - seg.file_head)
+        end
+      end
+
+      # How +lo+ to +hi+ must be disassembled: as one range by default. An
+      # architecture that encodes different parts of its code differently splits
+      # it where the encoding changes, since objdump reads a whole range one way.
+      # @param [Integer] lo
+      # @param [Integer] hi
+      # @return [Array<(Integer, Integer, Array<String>)>]
+      #   Each range, with the objdump options that read it correctly.
+      def decode_ranges(lo, hi)
+        [[lo, hi, []]]
+      end
+
+      # Note how the file says its code is encoded, for {#decode_ranges} to split
+      # on. Nothing to note for an architecture with one encoding.
+      # @param [ELFTools::ELFFile] elf
+      # @return [void]
+      def record_instruction_sets(elf); end
+
+      def objdump_lines(start: nil, stop: nil, extra: [])
+        # One pass, one string per line: a whole libc is hundreds of thousands of
+        # them, and only the instructions are wanted.
+        symbols = @raw_symbols
+        `#{@objdump.command(start:, stop:, extra:)}`.each_line.filter_map do |line|
+          line = line.strip
+          next unless DISASSEMBLED.match?(line)
+
+          symbols ? symbolize(line, symbols) : 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 the segment holding the code 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)
+          targets = terminal_symbol_addresses(elf)
+          return [] if targets.empty?
+
+          seg = executable_segment(elf)
+          return nil if seg.nil?
+
+          scan_calls(seg.mem_head, seg.data, targets)
+        end
+      rescue ELFTools::ELFError
+        nil # not something we can scan; disassemble everything
+      end
+
+      # The loadable segment holding the code, which is where a call scan runs and
+      # what raw disassembly is taken from. It holds a little besides the code, and
+      # is used in place of a section because a stripped file has none.
+      # @param [ELFTools::ELFFile] elf
+      # @return [ELFTools::Segments::LoadSegment, nil]
+      def executable_segment(elf)
+        elf.segments_by_type(:load).find(&:executable?)
+      end
+
+      # 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)
+        return sectionless_terminal_addresses(elf) if elf.num_sections.zero?
+
+        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. The table is the file's own data, so
+      # it is read in the byte order the file states.
+      # @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
+        big = elf.endian == :big
+        section.data.unpack(big ? 'N*' : 'V*').each_slice(wide ? 6 : 4) do |words|
+          value = wide ? wide_value(words, big) : words[1]
+          next if value.nil? || value.zero?
+
+          yield(words[0], value)
+        end
+      end
+
+      # A 64-bit value stated as two words, the more significant of which comes
+      # first in a big-endian file.
+      # @param [Array<Integer>] words One symbol table entry.
+      # @param [Boolean] big
+      # @return [Integer, nil] +nil+ for a truncated entry.
+      def wide_value(words, big)
+        low, high = big ? [words[3], words[2]] : [words[2], words[3]]
+        low && high && (low | (high << 32))
+      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

data/lib/one_gadget/fetchers/dynamic_symbols.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'elftools'
+
+require 'one_gadget/emulators/processor'
+require 'one_gadget/emulators/safe_calls'
+
+module OneGadget
+  module Fetchers
+    # Reading a shared object that ships without section headers, as an embedded
+    # libc commonly does: OpenWrt strips them from musl to save flash, and a
+    # vendor firmware may do the same to glibc.
+    #
+    # Nothing is actually missing from such a file -- the loader still has to find
+    # the symbols, so they are reachable through +PT_DYNAMIC+ -- but the usual
+    # route to them is not. objdump disassembles sections and so produces nothing
+    # at all, and the engine recognises a terminal call by the symbol objdump
+    # prints beside it. Both are answered here: the symbols are read out of the
+    # dynamic segment, and the raw disassembly is rewritten to name them, so
+    # everything downstream reads what it always reads.
+    module DynamicSymbols
+      # Where a line that transfers control says it goes. Raw disassembly writes
+      # every destination as +0x<addr>+, and the rest of the line is whatever the
+      # architecture puts around it: the destination may be separated by a comma,
+      # and followed by the note objdump appends to name the mnemonic's alias.
+      # @example
+      #   'call   0x94180'
+      #   'beqz   a5,0x43060'
+      #   'b.ls   0x47dcc  // b.plast'
+      CONTROL_TARGET = %r{\A(.*[\s,])0x([0-9a-f]+)(?:\s+//.*)?\z}
+
+      # An address any other line names, which it states last and alone -- so a
+      # value the line merely operates on is left as it is written.
+      # @example An architecture may resolve a pc-relative operand from this.
+      #   'lea    rcx,[rip+0x19dabe]        # 0x1eb960'
+      TRAILING_ADDRESS = /\A(.*\s)0x([0-9a-f]+)\z/
+
+      private
+
+      # Where the terminal +exec*+/+posix_spawn*+ entry points live, read through
+      # the dynamic segment. Keyed for lookup, as {#terminal_symbol_addresses} is.
+      # @param [ELFTools::ELFFile] elf
+      # @return [Hash{Integer => true}]
+      def sectionless_terminal_addresses(elf)
+        dynamic_symbols(elf).each_with_object({}) do |(addr, name), addrs|
+          addrs[symbol_address(addr)] = true if name.start_with?(*Disassembly::TERMINAL_PREFIXES)
+        end
+      end
+
+      # Every function the dynamic symbol table names, as +{address => name}+ --
+      # where a file stripped of its sections still records them.
+      # @param [ELFTools::ELFFile] elf
+      # @return [Hash{Integer => String}]
+      # @example Several names may share an address; the one the engine can act on
+      #   wins (see {#name_rank}).
+      #   dynamic_symbols(elf)[0x43470] #=> '__sigsuspend'
+      def dynamic_symbols(elf)
+        @dynamic_symbols ||= (elf.dynamic&.symbols || []).each_with_object({}) do |symbol, symbols|
+          value = symbol.value
+          name = symbol.name.to_s
+          next if value.zero? || name.empty?
+
+          addr = symbol_address(value)
+          symbols[addr] = name if !symbols.key?(addr) || name_rank(name) >= name_rank(symbols[addr])
+        end
+      end
+
+      # How much the engine can do with +name+: it recognises a terminal entry
+      # point by naming it exactly, a call it can step over by containing one of
+      # the catalog's names, and nothing else by name at all. Higher is more.
+      # @param [String] name One symbol name.
+      # @return [Integer]
+      # @example Two names for one address, of which only the second is read.
+      #   name_rank('sigaction')   #=> 0
+      #   name_rank('__sigaction') #=> 1
+      def name_rank(name)
+        return 2 if OneGadget::Emulators::Processor::TERMINAL_CALL_RE.match?(name)
+        return 1 if OneGadget::Emulators::SafeCalls::COMMON.keys.any? { |known| name.include?(known) }
+
+        0
+      end
+
+      # Rewrite a raw-disassembly line into what reading the ELF would have
+      # produced: an address objdump wrote as +0x<addr>+ becomes the bare address,
+      # named when a symbol is there. The engine recognises a terminal call, reads
+      # a branch target, and matches a safe call by name, from exactly that.
+      #
+      # @param [String] line One disassembled line.
+      # @param [Hash{Integer => String}] symbols
+      # @return [String]
+      # @example A destination is rewritten and named; an operand that merely looks
+      #   like one is left alone ({CONTROL_TARGET} against {TRAILING_ADDRESS}).
+      #   symbolize('e6570: call   0x94180', symbols)     #=> 'e6570: call   94180 <execve>'
+      #   symbolize('e6570: mov    rax,0x94180', symbols) #=> 'e6570: mov    rax,0x94180'
+      def symbolize(line, symbols)
+        m = line.match(control_transfer?(line) ? CONTROL_TARGET : TRAILING_ADDRESS) or return line
+
+        name = symbols[m[2].to_i(16)]
+        named = name ? " <#{name}>" : ''
+        "#{m[1]}#{m[2]}#{named}"
+      end
+    end
+  end
+end

data/lib/one_gadget/fetchers/i386.rb

@@ -11,14 +11,9 @@ module OneGadget
     class I386 < OneGadget::Fetchers::X86
       private
 
-      def candidates
-        rel_sh_hex = rel_sh.to_s(16)
-        super do |candidate|
-          next false unless candidate.include?(rel_sh_hex)
-
-          true
-        end
-      end
+      # PIC reaches the string through the GOT, so what a window holds is the
+      # distance between them rather than the string's own offset.
+      def bin_sh_reference = rel_sh
 
       def emulator
         OneGadget::Emulators::I386.new
@@ -82,6 +77,8 @@ module OneGadget
         end
       end
 
+      # How far +"/bin/sh"+ sits before the GOT, which is how PIC code names it:
+      # a window reaches the string as an offset from the register holding the base.
       def rel_sh
         @rel_sh ||= got_offset - str_offset('/bin/sh')
       end