one_gadget 2.0.0 → 2.1.0

data/lib/one_gadget/fetchers/mips.rb

@@ -0,0 +1,478 @@
+# frozen_string_literal: true
+
+require 'elftools'
+
+require 'one_gadget/emulators/mips'
+require 'one_gadget/fetchers/base'
+
+module OneGadget
+  module Fetchers
+    # Fetcher for MIPS (32-bit, o32).
+    #
+    # Two things about this architecture are unlike every other one supported, and
+    # both are answered here so that nothing about them reaches the engine:
+    #
+    # * a call states no target -- it goes through a register loaded from the GOT,
+    #   so the callee's name has to be resolved and written where every other arch
+    #   has one already ({#name_got_calls});
+    # * a branch or call has a *delay slot*: the instruction after it runs before
+    #   it takes effect. {OneGadget::Emulators::Mips#process!} holds the transfer
+    #   back so both run in that order, which leaves the disassembly in the order
+    #   objdump wrote it and every address meaning what it says. Two seams follow
+    #   from it, and they are the only ones: the instruction after a call belongs
+    #   to the window that ends at the call ({#emulate}), and the edge into a
+    #   branch's target leaves from the delay slot rather than the branch
+    #   ({#branch_pred_map}).
+    class Mips < Base
+      # Everything this arch reaches -- its calls and its globals alike -- goes
+      # through the GOT base in +gp+, which is a precondition the caller arranges
+      # by setting that register. Say so, and drop the read/write requirements
+      # rooted there: the GOT is a fixed, mapped libc address, so reaching through
+      # it asks nothing further of the caller (as i386 does for its own GOT
+      # register).
+      # @param [OneGadget::Emulators::Processor] processor
+      # @return [Hash, nil]
+      def resolve(processor)
+        res = super
+        return if res.nil?
+
+        got = got_base_constraint(processor, GOT_BASE) or return nil
+
+        res[:constraints].unshift(*got_preconditions(processor, got))
+        res[:constraints].reject! { |con| con.match?(/\A(?:writable|readable): \[*#{GOT_BASE}\b/) }
+        res
+      end
+
+      # This arch reads a global through the GOT and resolves the slot to the
+      # address it holds, so what reaches a call is one dereference of the variable
+      # rather than two of the slot naming it. Which variable that is comes from
+      # the symbols already read for the table.
+      # @param [String] str A rendered value.
+      # @return [Boolean]
+      def environ?(str)
+        got = mips_got or return false
+        offset = string_file_offset(str.delete('[]')) or return false
+
+        ENVIRON.match?(got[:names][offset].to_s)
+      end
+
+      # What the caller must arrange for this window to reach the GOT. Normally
+      # just the register itself -- but o32 has the *caller* restore it after
+      # every call, because the callee establishes its own, so a window that runs
+      # past a call reads the table through whatever it restored from. Every call
+      # it makes after that point was named on the assumption that this is the
+      # GOT, so say so rather than leaving it unsaid.
+      # @param [OneGadget::Emulators::Processor] processor
+      # @param [String] got The constraint naming the register itself.
+      # @return [Array<String>]
+      # @example a window that restores gp from its frame
+      #   got_preconditions(processor, 'gp is the GOT address of libc')
+      #   #=> ['gp is the GOT address of libc', '[sp+0x18] is the GOT address of libc']
+      def got_preconditions(processor, got)
+        held = processor.registers[GOT_BASE].to_s
+        return [got] if held == GOT_BASE
+
+        [got, "#{held} is the GOT address of libc"]
+      end
+
+      # A candidate may begin at a delay slot -- entering there runs it and falls
+      # past the transfer it belongs to -- but it may not then *follow* that
+      # transfer, which never executed. Such a window shows it by its second line
+      # not being the next instruction along; entering one instruction earlier, at
+      # the transfer itself, is the separate and valid window that does follow it.
+      # @param [Array<String>] lines One candidate, as a line list.
+      # @yieldparam [Array<String>] window
+      # @return [void]
+      def executed_windows(lines)
+        super do |window|
+          next if follows_a_transfer_it_skipped?(window) || enters_at_an_unset_call?(window)
+          next if calls_without_the_callee_in_t9?(window)
+
+          yield(window)
+        end
+      end
+
+      private
+
+      # This arch spells every instruction in one word.
+      INSTRUCTION_SIZE = 4
+      private_constant :INSTRUCTION_SIZE
+
+      # Whether the window opens on a call through a register it never set, so that
+      # where it goes is whatever the caller happened to leave there. Refusing
+      # costs nothing: the window one instruction earlier loads it itself.
+      # @param [Array<String>] window
+      # @return [Boolean]
+      # @example The load that names the call is behind the window's first line.
+      #   enters_at_an_unset_call?(['4b3e0: jalr t9 <posix_spawnattr_init>']) #=> true
+      #   enters_at_an_unset_call?(['4b3dc: lw t9,-31652(gp)', '4b3e0: jalr t9']) #=> false
+      def enters_at_an_unset_call?(window)
+        mnemonic(window.first) == 'jalr'
+      end
+
+      # Whether the window reaches a call whose callee derives its own GOT base
+      # from +t9+, without the window having aimed +t9+ at it.
+      # @param [Array<String>] window
+      # @return [Boolean]
+      # @example The same call, with and without the load that aims at it.
+      #   aimed = ['66860: lw t9,-30292(gp)', '66864: bal 6653c <posix_spawnattr_init>']
+      #   calls_without_the_callee_in_t9?(aimed)      #=> false
+      #   calls_without_the_callee_in_t9?(aimed[1..]) #=> true
+      def calls_without_the_callee_in_t9?(window)
+        held = nil
+        window.each do |line|
+          if (load = line.match(GOT_LOAD))
+            held = got_address(load[1].to_i)
+          elsif (call = line.match(DIRECT_CALL))
+            target = call[1].to_i(16)
+            return true if held != target && derives_got_base?(target)
+          elsif line.match?(TARGET_WRITE)
+            held = nil
+          end
+        end
+        false
+      end
+
+      # A call that states its destination, as opposed to one through a register.
+      DIRECT_CALL = /:\s*(?:bal|jal)\s+([0-9a-f]+)/
+      private_constant :DIRECT_CALL
+
+      # Whether the function at +address+ derives its own GOT base, which o32 asks
+      # a callee to do from the address the caller leaves in +t9+ -- so a caller
+      # that has not put it there is calling a function that cannot find anything.
+      # @param [Integer] address
+      # @return [Boolean]
+      # @example The prologue this recognises, and a leaf that has none.
+      #   derives_got_base?(0x6653c) #=> true  (lui gp / addiu gp / addu gp,gp,t9)
+      #   derives_got_base?(0x66594) #=> false (sltiu v0,a1,256 / ...)
+      def derives_got_base?(address)
+        code = loaded_code or return false
+
+        index = (address - code[:base]) / INSTRUCTION_SIZE
+        return false if index.negative?
+
+        PROLOGUE_WORDS.times.any? { |i| code[:words][index + i] == GOT_BASE_FROM_TARGET }
+      end
+
+      # How far into a function to look for that prologue: it is the first thing a
+      # function does, ahead of anything that could need what it computes.
+      PROLOGUE_WORDS = 4
+      private_constant :PROLOGUE_WORDS
+
+      # +addu gp,gp,t9+, the instruction the prologue ends with.
+      GOT_BASE_FROM_TARGET = 0x0399e021
+      private_constant :GOT_BASE_FROM_TARGET
+
+      # The code the file loads, so that an instruction can be read at an address
+      # without disassembling anything around it.
+      # @return [Hash{Symbol => Integer, Array<Integer>}, nil]
+      # @example The word posix_spawnattr_init opens with, +lui gp,0x6+.
+      #   code = loaded_code
+      #   code[:words][(0x6653c - code[:base]) / 4] #=> 0x3c1c0006
+      def loaded_code
+        return @loaded_code if defined?(@loaded_code)
+
+        @loaded_code = File.open(file) do |fd|
+          elf = ELFTools::ELFFile.new(fd)
+          segment = executable_segment(elf)
+          segment && { base: segment.mem_head,
+                       words: segment.data.unpack(elf.endian == :big ? 'N*' : 'V*') }
+        end
+      end
+
+      # @param [Array<String>] window
+      # @return [Boolean] Whether it starts at a delay slot and then takes the
+      #   branch that delay slot belongs to.
+      def follows_a_transfer_it_skipped?(window)
+        return false if window.size < 2
+
+        offset_of(window[1]) != offset_of(window.first) + INSTRUCTION_SIZE
+      end
+
+      # The register o32 states the GOT base in.
+      GOT_BASE = 'gp'
+      private_constant :GOT_BASE
+
+      # Every instruction is one word here and word-aligned, so the whole scan is
+      # a masked compare per word. A call spells its destination two ways: a
+      # direct one carries it, and the indirect one PIC code reaches everything
+      # through names the GOT slot it is taken from.
+      def scan_calls(base, data, targets)
+        got = mips_got or return nil
+
+        sites = []
+        data.unpack(got[:big] ? 'N*' : 'V*').each_with_index do |word, i|
+          next unless CALL_OPCODES.key?(word >> OPCODE_SHIFT)
+
+          address = base + (i * INSTRUCTION_SIZE)
+          destination = call_destination(word, address)
+          sites << address if destination && targets.key?(destination)
+        end
+        sites
+      end
+
+      # How far the opcode sits from the bottom of a word.
+      OPCODE_SHIFT = 26
+      private_constant :OPCODE_SHIFT
+
+      # The opcodes a call can be spelled in -- the load, the branch-and-link and
+      # the jump-and-link below -- so that a word which is none of them is passed
+      # over without being decoded. Most of a .text is.
+      CALL_OPCODES = { 0x23 => true, 0x01 => true, 0x03 => true }.freeze
+      private_constant :CALL_OPCODES
+
+      # Where a call at +address+ goes.
+      # @param [Integer] word The instruction word.
+      # @param [Integer] address
+      # @return [Integer, nil] +nil+ when the word is not a call, or is one whose
+      #   destination these bytes alone do not say.
+      # @example
+      #   # lw t9,-32744(gp), whose GOT slot holds _setjmp
+      #   call_destination(0x8f998018, 0x4b3dc) #=> 0x39190
+      #   # bal 4b3f0
+      #   call_destination(0x04110004, 0x4b3dc) #=> 0x4b3f0
+      def call_destination(word, address)
+        following = address + INSTRUCTION_SIZE
+        case word & OPCODE_AND_TARGET_REGISTERS
+        when GOT_CALL_LOAD then got_address(immediate(word))
+        when BAL then following + (immediate(word) * INSTRUCTION_SIZE)
+        else ((following & JAL_REGION) | ((word & JAL_TARGET) << 2) if (word >> OPCODE_SHIFT) == JAL_OPCODE)
+        end
+      end
+
+      # The high half of a word, which is opcode plus whichever registers an
+      # instruction of that opcode names there.
+      OPCODE_AND_TARGET_REGISTERS = 0xffff0000
+      private_constant :OPCODE_AND_TARGET_REGISTERS
+
+      # +lw t9,<imm>(gp)+ -- the load of a call's destination out of the GOT.
+      GOT_CALL_LOAD = 0x8f990000
+      private_constant :GOT_CALL_LOAD
+
+      # +bal <imm>+, the pc-relative direct call, spelled +bgezal zero,<imm>+.
+      BAL = 0x04110000
+      private_constant :BAL
+
+      # +jal <target>+, the direct call that states an absolute address, which it
+      # can only do within the 256MB region it is itself in.
+      JAL_OPCODE = 3
+      JAL_TARGET = 0x03ffffff
+      JAL_REGION = 0xf0000000
+      private_constant :JAL_OPCODE, :JAL_TARGET, :JAL_REGION
+
+      # The signed offset an instruction states in its low half.
+      # @param [Integer] word The instruction word.
+      # @return [Integer]
+      def immediate(word)
+        half = word & 0xffff
+        half >= 0x8000 ? half - 0x10000 : half
+      end
+
+      # A call, however it is spelled: through a register (which is how PIC code
+      # reaches everything) or directly.
+      def call_str = '(?:jalr|jal|bal)'
+
+      def branch_lead_chars = 'bj'
+
+      # +b+ is the unconditional branch, the compare-and-branch family is
+      # conditional, and +jr+ (which is how a return is written) ends the path.
+      # Calls are not branches: the walk stitches the window they target.
+      def branch_kind(line)
+        mnem = mnemonic(line)
+        return :conditional if OneGadget::Emulators::Mips::COND.key?(mnem)
+        return :unconditional if mnem == 'b'
+
+        :terminator if %w[jr j].include?(mnem)
+      end
+
+      def emulator = OneGadget::Emulators::Mips.new
+
+      # Rewrite the disassembly into what the engine reads everywhere else: every
+      # call named.
+      def objdump_lines(start: nil, stop: nil, extra: [])
+        state_got_values(name_got_calls(super))
+      end
+
+      # A window ends at the call that ends the gadget, but that call's delay slot
+      # runs before control leaves -- it is where an argument is often set -- so it
+      # is part of what the window executes.
+      # @param [Array<String>] cmds
+      # @return [OneGadget::Emulators::Processor]
+      def emulate(cmds)
+        super(terminal_call_line?(cmds.last) ? cmds + delay_slot_after(cmds.last) : cmds)
+      end
+
+      # The instruction a transfer delays behind, as a one-element list, or none
+      # when the disassembly does not carry it (it starts another window).
+      # @param [String] line
+      # @return [Array<String>]
+      def delay_slot_after(line)
+        index = disasm_index[offset_of(line)]
+        return [] if index.nil? || window_starts.key?(index + 1)
+
+        [disasm_lines[index + 1]].compact
+      end
+
+      # A branch takes effect only after its delay slot, so the edge is recorded as
+      # leaving the instruction *after* the branch -- a path through it then reads
+      # in the order it executes.
+      # @return [Hash{Integer => Array<Integer>}]
+      def branch_pred_map
+        @branch_pred_map ||= delayed_edges(super)
+      end
+
+      # Move each edge on by one instruction, dropping any whose delay slot the
+      # disassembly does not carry because another window starts there.
+      # @param [Hash{Integer => Array<Integer>}] map
+      # @return [Hash{Integer => Array<Integer>}]
+      def delayed_edges(map)
+        map.to_h { |target, indexes| [target, indexes.filter_map { |i| i + 1 unless window_starts.key?(i + 1) }] }
+      end
+
+      # The call this arch actually uses names no target: the callee is loaded out
+      # of the GOT into +t9+ and jumped to. Resolve the slot and write the name
+      # beside the call, which is where the engine reads one.
+      # @param [Array<String>] lines
+      # @return [Array<String>]
+      # @example
+      #   name_got_calls(['4b3dc: lw t9,-31652(gp)', '4b3e0: jalr t9'])
+      #   #=> ['4b3dc: lw t9,-31652(gp)', '4b3e0: jalr t9 <posix_spawnattr_init>']
+      def name_got_calls(lines)
+        loaded = nil
+        lines.map do |line|
+          if (m = line.match(GOT_LOAD))
+            loaded = m[1].to_i
+          elsif line.match?(INDIRECT_CALL)
+            name = loaded && got_symbol(loaded)
+            loaded = nil
+            next name ? "#{line} <#{name}>" : line
+          elsif line.match?(TARGET_WRITE)
+            # the call no longer goes where that offset said
+            loaded = nil
+          end
+          line
+        end
+      end
+
+      # A libc global is reached through the GOT as well: the slot holds the
+      # address, and an +addiu+ applies the offset within it. What the slot holds
+      # is in the file, so state it beside the load -- which is what lets the
+      # value read as +$base+<off>+, the form every other architecture produces
+      # for a global.
+      # @param [Array<String>] lines
+      # @return [Array<String>]
+      # @example
+      #   state_got_values(['77b44: lw a0,-32496(gp)'])
+      #   #=> ['77b44: lw a0,-32496(gp)  # b0000']
+      def state_got_values(lines)
+        lines.map do |line|
+          m = line.match(GOT_GLOBAL_LOAD) or next line
+
+          address = got_address(m[1].to_i)
+          address.nil? || address.zero? ? line : "#{line}  # #{format('%x', address)}"
+        end
+      end
+
+      # Loading anything but the call target out of the GOT.
+      GOT_GLOBAL_LOAD = /:\s*lw\s+(?!t9,)\w+,(-?\d+)\(gp\)/
+      private_constant :GOT_GLOBAL_LOAD
+
+      # Loading the call target out of the GOT, which is +gp+-relative.
+      GOT_LOAD = /:\s*lw\s+t9,(-?\d+)\(gp\)/
+      private_constant :GOT_LOAD
+
+      # The call through it. o32 requires the callee's address in +t9+ -- that is
+      # how the callee computes its own +gp+ -- so a call always reads that
+      # register, optionally naming the one the return address goes to.
+      INDIRECT_CALL = /:\s*jalr\s+(?:\w+,)?t9\s*\z/
+      private_constant :INDIRECT_CALL
+
+      # Anything else that writes the call register. Only the load that last wrote
+      # +t9+ says where the call goes: most calls reach it another way (out of a
+      # struct, or from a register), and carrying a GOT offset over one of those
+      # would name the call after a function it never reaches. A store reads the
+      # register rather than writing it.
+      TARGET_WRITE = /:\s*(?!s[whb]\b)\S+\s+t9,/
+      private_constant :TARGET_WRITE
+
+      # What a +gp+-relative GOT slot holds, as +[address, name]+, or +nil+ for one
+      # this cannot read. Kept, since a libc reaches the same slot from every call
+      # site that goes through it.
+      # @param [Integer] gp_offset The offset as the instruction writes it.
+      # @return [(Integer, String), nil]
+      def got_entry(gp_offset)
+        return @got_entries[gp_offset] if @got_entries&.key?(gp_offset)
+
+        (@got_entries ||= {})[gp_offset] = read_got_entry(gp_offset)
+      end
+
+      # The slot itself, out of the file. This arch states its GOT in the dynamic
+      # segment, so the answer is there even for a file with no sections at all.
+      # @param [Integer] gp_offset The offset as the instruction writes it.
+      # @return [(Integer, String), nil]
+      # @example An entry below +DT_MIPS_LOCAL_GOTNO+ holds an address outright;
+      #   the rest correspond one for one with the dynamic symbols.
+      #   read_got_entry(-32744) #=> [0x39190, '_setjmp']
+      #   read_got_entry(-32752) #=> [0, nil]
+      def read_got_entry(gp_offset)
+        got = mips_got or return nil
+
+        index = (GP_BIAS + gp_offset) / 4
+        if index < got[:local]
+          address = local_got_entry(got, index)
+          return address && [address, got[:names][address]]
+        end
+        got[:symbols][got[:gotsym] + index - got[:local]]
+      end
+
+      # @param [Integer] gp_offset
+      # @return [String, nil] The symbol the slot names.
+      def got_symbol(gp_offset) = got_entry(gp_offset)&.last
+
+      # @param [Integer] gp_offset
+      # @return [Integer, nil] The address the slot holds.
+      def got_address(gp_offset) = got_entry(gp_offset)&.first
+
+      # +gp+ points this far into the GOT, so that one signed 16-bit offset reaches
+      # the most of it. Every +gp+-relative offset is read against it.
+      GP_BIAS = 0x7ff0
+      private_constant :GP_BIAS
+
+      # What a local GOT entry holds: the address itself, written in the file.
+      # @param [Hash] got
+      # @param [Integer] index
+      # @return [Integer, nil]
+      def local_got_entry(got, index)
+        file_bytes[got[:offset] + (index * 4), 4]&.unpack1(got[:big] ? 'N' : 'V')
+      end
+
+      # Where this file's GOT is and how to read it. The entries below
+      # +DT_MIPS_LOCAL_GOTNO+ hold an address outright; the rest correspond one for
+      # one with the dynamic symbols, starting at +DT_MIPS_GOTSYM+.
+      # @return [Hash, nil] +nil+ when the file states no GOT.
+      def mips_got
+        return @mips_got if defined?(@mips_got)
+
+        @mips_got = File.open(file) { |fd| read_mips_got(ELFTools::ELFFile.new(fd)) }
+      end
+
+      # @param [ELFTools::ELFFile] elf
+      # @return [Hash, nil]
+      def read_mips_got(elf)
+        dynamic = elf.segment_by_type(:dynamic) or return nil
+        address = dynamic.tag_by_type(:pltgot)&.value or return nil
+        local = dynamic.tag_by_type(:mips_local_gotno)&.value or return nil
+        gotsym = dynamic.tag_by_type(:mips_gotsym)&.value or return nil
+        segment = elf.segments_by_type(:load).find { |seg| seg.vma_in?(address) } or return nil
+
+        # Read out of the symbols now, rather than holding them: they are lazy, and
+        # the file they would read from is closed as soon as this returns.
+        symbols = dynamic.symbols.map { |symbol| [symbol.value, symbol.name] }
+        names = symbols.to_h { |value, name| [value, name] }
+                       .reject { |value, name| value.zero? || name.empty? }
+        { local:, gotsym:, symbols:, names:, big: elf.endian == :big,
+          offset: segment.vma_to_offset(address) }
+      end
+    end
+  end
+end

data/lib/one_gadget/fetchers/objdump.rb

@@ -19,22 +19,35 @@ module OneGadget
         @options = []
       end
 
+      # Read the file as a raw blob at +vma+ instead of as an ELF, for one whose
+      # section headers are gone: objdump disassembles sections, and a file with
+      # none disassembles to nothing at all.
+      # @param [String] machine The objdump architecture name, as {OneGadget::Helper.objdump_arch} gives it.
+      # @param [Symbol] endian +:little+ or +:big+.
+      # @param [Integer] vma What the first byte of the file is loaded at.
+      # @return [void]
+      def read_raw(machine:, endian:, vma:)
+        @raw = { machine:, endian:, vma: }
+      end
+
       # Set the extra options to be passed to objdump.
       # @param [Array<String>] options The options.
       # @example
       #   objdump.extra_options = %w[-M intel]
+      # @return [void]
       def extra_options=(options)
         @options = options
       end
 
       # @param [Integer] start The start address to be dumpped from.
       # @param [Integer] stop The end address.
+      # @param [Array<String>] extra Options for this range alone, on top of {#extra_options=}.
       # @return [String] The CLI command to be executed.
-      def command(start: nil, stop: nil)
+      def command(start: nil, stop: nil, extra: [])
         # --dwarf-start=0 is to make sure `suppress_bfd_header` is true to eliminate the file path in the output, see
         # issue #204 for more details.
         # Note: We might need to update this when the objdump act differently in the future.
-        cmd = [bin, '--dwarf-start=0', '--no-show-raw-insn', '-w', '-d', *@options, @file]
+        cmd = [bin, '--dwarf-start=0', '--no-show-raw-insn', '-w', *disassemble_options, *@options, *extra, @file]
         cmd.push('--start-address', start) if start
         cmd.push('--stop-address', stop) if stop
         ::Shellwords.join(cmd)
@@ -42,6 +55,15 @@ module OneGadget
 
       private
 
+      # +-d+ walks the sections; a file read as a blob has none, so everything in
+      # it is disassembled (+-D+) and told what it is and where it lives.
+      def disassemble_options
+        return ['-d'] if @raw.nil?
+
+        ['-D', '-b', 'binary', '-m', @raw[:machine], @raw[:endian] == :big ? '-EB' : '-EL',
+         "--adjust-vma=#{@raw[:vma]}"]
+      end
+
       def bin
         OneGadget::Helper.find_objdump(@arch).tap do |bin|
           install_objdump_guide! if bin.nil?

data/lib/one_gadget/fetchers/riscv64.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'one_gadget/emulators/riscv64'
+require 'one_gadget/fetchers/base'
+
+module OneGadget
+  module Fetchers
+    # Fetcher for RISC-V (RV64).
+    class Riscv64 < Base
+      private
+
+      # +jal+ is the only direct call and is four bytes wide, carrying its target as
+      # a signed offset from itself. Instructions are two-byte aligned, since a
+      # compressed one is half a word, so every two-byte position is read as a
+      # possible +jal+ rather than every fourth: a false positive only adds a
+      # window nothing is found in, while a missed call costs the gadgets around it.
+      def scan_calls(base, data, targets)
+        halves = data.unpack('v*')
+        sites = []
+        halves.each_with_index do |low, i|
+          next unless (low & 0x7f) == JAL_OPCODE
+
+          high = halves[i + 1]
+          break if high.nil?
+
+          addr = base + (i * 2)
+          sites << addr if targets.key?(addr + jal_offset(low | (high << 16)))
+        end
+        sites
+      end
+
+      # The J-type opcode, which lives in the low half of the instruction word.
+      JAL_OPCODE = 0x6f
+      private_constant :JAL_OPCODE
+
+      # The signed offset a +jal+ carries. The encoding scatters its bits --
+      # +[20|10:1|11|19:12]+, with bit 0 always zero since a target is two-byte
+      # aligned -- so they are put back in order before the sign is applied.
+      # @param [Integer] word The instruction word.
+      # @return [Integer]
+      def jal_offset(word)
+        imm = (((word >> 31) & 0x1) << 20) |
+              (((word >> 12) & 0xff) << 12) |
+              (((word >> 20) & 0x1) << 11) |
+              (((word >> 21) & 0x3ff) << 1)
+        imm.anybits?(1 << 20) ? imm - (1 << 21) : imm
+      end
+
+      def emulator
+        OneGadget::Emulators::Riscv64.new
+      end
+
+      def branch_lead_chars
+        'bj'
+      end
+
+      # Every conditional branch compares two registers directly -- there is no
+      # flag register and no compare instruction -- so the whole family, including
+      # the pseudo-instructions the assembler spells against +zero+, starts with
+      # +b+. +jalr+ ends a path: it is an indirect jump, and where it goes is not
+      # something the disassembly says.
+      def branch_kind(line)
+        m = mnemonic(line)
+        return :conditional if m.start_with?('b')
+        return :unconditional if m == 'j'
+
+        :terminator if %w[ret jr jalr].include?(m)
+      end
+
+      # +jal+ is the direct call. A tail +j+ into an +exec*+ entry reaches one too,
+      # but it is a jump, not a call, and is left out for the same reason x86 counts
+      # only +call+: the walker stitches such a jump into the window it targets.
+      def call_str
+        'jal'
+      end
+    end
+  end
+end

data/lib/one_gadget/fetchers/x86.rb

@@ -12,6 +12,25 @@ module OneGadget
 
       private
 
+      # 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

data/lib/one_gadget/fetchers.rb

@@ -5,6 +5,8 @@ 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'
 
@@ -15,6 +17,17 @@ module OneGadget
     # 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.
@@ -42,17 +55,20 @@ module OneGadget
       #   Array of all found gadgets is returned.
       def from_file(file, level: 0)
         arch = OneGadget::Helper.architecture(file)
-        klass = {
-          aarch64: OneGadget::Fetchers::AArch64,
-          amd64: OneGadget::Fetchers::Amd64,
-          arm: OneGadget::Fetchers::Arm,
-          i386: OneGadget::Fetchers::I386
-        }[arch]
+        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.