one_gadget 1.9.0 → 2.0.0

data/lib/one_gadget/gadget.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 require 'one_gadget/abi'
 require 'one_gadget/emulators/lambda'
 require 'one_gadget/error'
@@ -17,6 +19,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.
@@ -27,18 +32,39 @@ module OneGadget
       def initialize(offset, **options)
         @base = 0
         @offset = offset
-        @constraints = options[:constraints] || []
-        @effect = options[:effect]
+        @constraints = prune_settled(options[:constraints] || [])
+        @effect = options[:effect] || ''
+        @closed_fds = options[:closed_fds] || []
+      end
+
+      # 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
 
-      # Show gadget in a pretty way.
+      # 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)
-        str += effect ? " #{effect}\n" : "\n"
+        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")
@@ -46,6 +72,25 @@ module OneGadget
         "#{str}\n"
       end
 
+      # 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
+        obj = { value:, effect:, constraints: }
+        return obj if caveats.empty?
+
+        obj.merge(closed_fds:, caveats:)
+      end
+
+      # 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
+
       # @return [Integer]
       #   Returns +base+ plus +offset+.
       def value
@@ -58,8 +103,208 @@ 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
 
+      # 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.
+      #
+      # Most of it follows from one reading: a constraint that accesses an address
+      # says that address is mapped memory (see {#mapped?}), which in turn says it
+      # is readable and not NULL. So:
+      # * A +readable:+ on an address a dereference already reaches repeats it.
+      # * A +== NULL+ option for a mapped address can never be taken.
+      # * A +!= NULL+ requirement on one is already met.
+      # The last rule reads a value rather than an address: one the list pins to a
+      # literal answers every other comparison against it, so a bound that literal
+      # already satisfies asks for nothing.
+      #
+      # Each needs the constraint doing the settling to hold outright: one inside a
+      # +||+ is an option among several and settles nothing. They run until the
+      # list stops changing, because dropping an option can leave a constraint
+      # holding outright and settle the next thing.
+      # @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
+
       # REG: OneGadget::ABI.all
       # IMM: [+-]0x[\da-f]+
       # BITS: 8, 16, 32, 64
@@ -68,6 +313,7 @@ module OneGadget
       # 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
@@ -77,34 +323,105 @@ module OneGadget
       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: asking for zero in some
+        # of a value's bits is a little easier than zeroing all of it, while asking
+        # a mask for any other value is as hard as asking for that value 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
 
       def merge_constraints
@@ -112,8 +429,8 @@ module OneGadget
         w_cons, normal = constraints.partition { |c| c.start_with?(key) }
         return normal if w_cons.empty?
 
-        w_cons.map! { |c| c[key.size..-1] }
-        ["address#{w_cons.size > 1 ? 'es' : ''} #{w_cons.join(', ')} #{w_cons.size > 1 ? 'are' : 'is'} writable"] +
+        w_cons.map! { |c| c[key.size..] }
+        ["address#{'es' if w_cons.size > 1} #{w_cons.join(', ')} #{w_cons.size > 1 ? 'are' : 'is'} writable"] +
           normal
       end
     end
@@ -161,7 +478,7 @@ module OneGadget
       def builds_info(build_id)
         raise Error::ArgumentError, "Invalid BuildID #{build_id.inspect}" if build_id =~ /[^0-9a-f]/
 
-        files = Dir.glob(File.join(BUILDS_PATH, "*-#{build_id}*.rb")).sort
+        files = Dir.glob(File.join(BUILDS_PATH, "*-#{build_id}*.rb"))
         return OneGadget::Logger.not_found(build_id) && nil if files.empty?
 
         if files.size > 1
@@ -176,12 +493,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
@@ -189,7 +507,7 @@ module OneGadget
       def find_build(id)
         return BUILDS[id] if BUILDS.key?(id)
 
-        Dir.glob(File.join(BUILDS_PATH, "*-#{id}.rb")).sort.each do |dic|
+        Dir.glob(File.join(BUILDS_PATH, "*-#{id}.rb")).each do |dic|
           require dic
         end
         BUILDS[id] if BUILDS.key?(id)

data/lib/one_gadget/helper.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'net/http'
-require 'openssl'
 require 'pathname'
 require 'tempfile'
 
@@ -13,7 +11,7 @@ module OneGadget
   # Define some helpful methods here.
   module Helper
     # Format of build-id, 40 hex numbers.
-    BUILD_ID_FORMAT = /[0-9a-f]{40}/.freeze
+    BUILD_ID_FORMAT = /[0-9a-f]{40}/
 
     module_function
 
@@ -35,7 +33,7 @@ module OneGadget
     # @return [Array<String>]
     #   Lines of comments.
     def comments_of_file(file)
-      File.readlines(file).map { |s| s[2..-1].rstrip if s.start_with?('# ') }.compact
+      File.readlines(file).map { |s| s[2..].rstrip if s.start_with?('# ') }.compact
     end
 
     # Get absolute path from relative path. Support symlink.
@@ -128,8 +126,8 @@ module OneGadget
     end
 
     # Returns the hexified and colorized integer.
-    # @param [Integer] val
-    # @return [String]
+    # @param [Integer] val The number to be formatted.
+    # @return [String] The value in hex format, wrapped with integer color codes.
     def colored_hex(val)
       colorize(hex(val), sev: :integer)
     end
@@ -142,8 +140,8 @@ module OneGadget
     end
 
     # Get the url which can fetch +filename+ from remote repo.
-    # @param [String] filename
-    # @return [String] The url.
+    # @param [String] filename The path of the file relative to the repository root.
+    # @return [String] The raw-content url of +filename+ at the latest release tag.
     def url_of_file(filename)
       raw_file_url = 'https://raw.githubusercontent.com/david942j/one_gadget/@tag/@file'
       raw_file_url.sub('@tag', latest_tag).sub('@file', filename)
@@ -171,10 +169,15 @@ module OneGadget
     #   The request response body.
     #   If the response is +302 Found+, returns the location in header.
     def url_request(url)
+      # Asked for here rather than with the file: only reaching the build database
+      # over the network needs them, and together they are a quarter of what it
+      # takes to load one_gadget at all.
+      require 'net/http'
+      require 'openssl'
+
       uri = URI.parse(url)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
-      http.verify_mode = ::OpenSSL::SSL::VERIFY_NONE
 
       request = Net::HTTP::Get.new(uri.request_uri)
 
@@ -188,24 +191,30 @@ module OneGadget
     end
 
     # Fetch the ELF architecture of +file+.
+    # What this tool calls each architecture it can search. Keyed by the
+    # header's own value, which is fixed by the ELF ABI, rather than by the name a
+    # reader library prints for it -- that is the library's wording and does
+    # change, as elftools 2.0.0 renamed "AArch64" to "ARM 64-bit architecture".
+    MACHINES = {
+      ELFTools::Constants::EM::EM_386 => :i386,
+      ELFTools::Constants::EM::EM_ARM => :arm,
+      ELFTools::Constants::EM::EM_X86_64 => :amd64,
+      ELFTools::Constants::EM::EM_AARCH64 => :aarch64
+    }.freeze
+
     # @param [String] file The target ELF filename.
     # @return [Symbol]
-    #   Currently supports amd64, i386, arm, aarch64, and mips.
+    #   One of +:amd64+, +:i386+, +:arm+ or +:aarch64+, +:unknown+ for a valid ELF
+    #   this tool cannot search, or +:invalid+ when +file+ does not exist or is
+    #   not a valid ELF.
     # @example
     #   Helper.architecture('/bin/cat')
     #   #=> :amd64
     def architecture(file)
       return :invalid unless File.exist?(file)
 
-      f = File.open(file)
-      str = ELFTools::ELFFile.new(f).machine
-      {
-        'Advanced Micro Devices X86-64' => :amd64,
-        'Intel 80386' => :i386,
-        'ARM' => :arm,
-        'AArch64' => :aarch64,
-        'MIPS R3000' => :mips
-      }[str] || :unknown
+      f = File.open(file) # rubocop:disable Style/FileOpen
+      MACHINES[ELFTools::ELFFile.new(f).header.e_machine.to_i] || :unknown
     rescue ELFTools::ELFError # not a valid ELF
       :invalid
     ensure
@@ -226,7 +235,7 @@ module OneGadget
     #   Helper.hex(0) #=> '0x0'
     #   Helper.hex(0, psign: true) #=> '+0x0'
     def hex(val, psign: false)
-      return format("#{psign ? '+' : ''}0x%x", val) if val >= 0
+      return format("#{'+' if psign}0x%x", val) if val >= 0
 
       format('-0x%x', -val)
     end
@@ -244,15 +253,13 @@ module OneGadget
     #   Helper.integer? '0xheapoverflow'
     #   #=> false
     def integer?(str)
-      true if Integer(str)
-    rescue ArgumentError, TypeError
-      false
+      !Integer(str, exception: false).nil?
     end
 
     # Cross-platform way of finding an executable in +$PATH+.
     #
-    # @param [String] cmd
-    # @return [String?]
+    # @param [String] cmd The executable name to look for.
+    # @return [String?] The absolute path of the executable, or +nil+ if not found in +$PATH+.
     # @example
     #   Helper.which('ruby')
     #   #=> "/usr/bin/ruby"
@@ -268,8 +275,11 @@ module OneGadget
     end
 
     # Find objdump that supports architecture +arch+.
-    # @param [String] arch
-    # @return [String?]
+    #
+    # Prefers the generic +objdump+ if it supports +arch+, otherwise falls back to
+    # the architecture-specific binary (see {.arch_specific_objdump}).
+    # @param [Symbol] arch The target architecture, e.g. +:amd64+.
+    # @return [String?] The path of a suitable objdump, or +nil+ if none supports +arch+.
     # @example
     #   Helper.find_objdump(:amd64)
     #   #=> '/usr/bin/objdump'
@@ -283,9 +293,9 @@ module OneGadget
     end
 
     # Checks if the given objdump supports certain architecture.
-    # @param [String] bin
-    # @param [Symbol] arch
-    # @return [Boolean]
+    # @param [String?] bin Path to the objdump binary, or +nil+.
+    # @param [Symbol] arch The target architecture, e.g. +:i386+.
+    # @return [Boolean] +true+ if +bin+ exists and lists +arch+ among its supported targets.
     # @example
     #   Helper.objdump_arch_supported?('/usr/bin/objdump', :i386)
     #   #=> true
@@ -297,8 +307,8 @@ module OneGadget
     end
 
     # Converts to the architecture name shown in objdump's +--help+ command.
-    # @param [Symbol] arch
-    # @return [String]
+    # @param [Symbol] arch The internal architecture symbol, e.g. +:amd64+.
+    # @return [String] The corresponding target name as reported by objdump.
     # @example
     #   Helper.objdump_arch(:i386)
     #   #=> 'i386'
@@ -311,20 +321,23 @@ module OneGadget
       end
     end
 
-    # Returns the binary name of objdump.
-    # @param [Symbol] arch
-    # @return [String]
+    # Returns the architecture-specific objdump binary name for +arch+.
+    # @param [Symbol] arch The target architecture, e.g. +:aarch64+.
+    # @return [String?]
+    #   The cross-objdump binary name (e.g. +aarch64-linux-gnu-objdump+),
+    #   or +nil+ if +arch+ has no dedicated binary.
     def arch_specific_objdump(arch)
       {
         aarch64: 'aarch64-linux-gnu-objdump',
         amd64: 'x86_64-linux-gnu-objdump',
+        arm: 'arm-linux-gnueabihf-objdump',
         i386: 'i686-linux-gnu-objdump'
       }[arch]
     end
 
     # Returns the names of functions from the file's global offset table.
-    # @param [String] file
-    # @return [Array<String>]
+    # @param [String] file Path to the target ELF file.
+    # @return [Array<String>] The names of the GLIBC dynamic symbols found in +file+.
     def got_functions(file)
       arch = architecture(file)
       objdump_bin = find_objdump(arch)
@@ -332,9 +345,10 @@ module OneGadget
     end
 
     # Returns a dictionary that maps functions to their offsets.
-    # @param [String] file
-    # @param [Array<String>] functions
+    # @param [String] file Path to the target ELF file.
+    # @param [Array<String>] functions The function names to look up.
     # @return [Hash{String => Integer}]
+    #   Maps each matched function name to its offset within +file+.
     def function_offsets(file, functions)
       arch = architecture(file)
       objdump_bin = find_objdump(arch)