one_gadget 1.3.4.1 → 1.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c69447e16b79866cfd608d5b714e65cfa16d2492
-  data.tar.gz: 2a4ce21e7fb1070845a8fde268e8477b23f2e8da
+  metadata.gz: 769666a5afd3ce890eea834682b010137958e50a
+  data.tar.gz: 303399584d0b4163058ad74c0e9f80a8fea13694
 SHA512:
-  metadata.gz: 3768aa0cd2c00128fe75e232a115ed81b9783efed4de71cdbc28322843c534b25d7da93b731b85f0c22d6b1b5cd592984cd002dce099c05c6ff020060e503f66
-  data.tar.gz: 72a5b04cc4cfa3dfcaa99c248260bb3e0040a45166fe566405158917ad11a3ed65c943902099a3471fb224a18dd726404650892ca7b239d6699a0dcfd2775cb1
+  metadata.gz: bb098f44596a0bd6f9a51ae533fbb2456c66c65a64a11bd7c8bc031bdd08684ccee0a549a7d833d26cfe3314a1caf34bfbd294ed67960d9843ea21b72927c931
+  data.tar.gz: 743e95a1efac018fc6e887348b234bd08da77776494bfcd8f793a2b8612e2ccd69fecab26d948ae55525de15fc298179d04c4ff772b7c6c02b3e19120c98d03b

data/README.md

@@ -8,9 +8,10 @@
 
 ## One Gadget
 
-When playing ctf pwn challenges we usually need the one-gadget of `execve('/bin/sh', NULL, NULL)`.
+When playing ctf pwn challenges we usually need the one-gadget RCE (remote code execution),
+which leads to call `execve('/bin/sh', NULL, NULL)`.
 
-This gem provides such gadget finder, no need to use IDA-pro every time like a fool.
+This gem provides such gadgets finder, no need to use IDA-pro every time like a fool.
 
 This work provides the command-line tool `one_gadget` for easy usage.
 

data/lib/one_gadget.rb

@@ -26,8 +26,8 @@ module OneGadget
         OneGadget::Fetcher.from_build_id(build_id, details: details)
       elsif file
         file = OneGadget::Helper.abspath(file)
-        unless force_file
-          build_id = OneGadget::Helper.build_id_of(file)
+        build_id = OneGadget::Helper.build_id_of(file)
+        if !force_file && build_id
           gadgets = OneGadget::Fetcher.from_build_id(build_id, details: details)
           return gadgets unless gadgets.empty?
         end

data/lib/one_gadget/abi.rb

@@ -3,7 +3,9 @@ module OneGadget
   module ABI
     # Define class methods here.
     module ClassMethods
+      # Registers in i386.
       LINUX_X86_32 = %w(eax ebx ecx edx edi esi ebp esp).freeze
+      # Registers in x86_64/
       LINUX_X86_64 = LINUX_X86_32 + %w(rax rbx rcx rdx rdi rsi rbp rsp) + 7.upto(15).map { |i| "r#{i}" }
       # Registers' name in amd64.
       # @return [Array<String>] List of registers.

data/lib/one_gadget/emulators/i386.rb

@@ -6,6 +6,7 @@ module OneGadget
     # Emulator of amd64 instruction set.
     class I386 < X86
       class << self
+        # Yap, bits.
         def bits
           32
         end

data/lib/one_gadget/emulators/lambda.rb

@@ -3,10 +3,10 @@ require 'one_gadget/helper'
 module OneGadget
   module Emulators
     # A {Lambda} object can be:
-    # 1. {String} # variable name
-    # 2. {Numeric}
-    # 3. {Lambda} + {Numeric}
-    # 4. dereference {Lambda}
+    # 1. +String+ (variable name)
+    # 2. +Numeric+
+    # 3. {Lambda} + +Numeric+
+    # 4. dereferenced {Lambda}
     class Lambda
       attr_accessor :obj # @return [String, Lambda] The object currently related to.
       attr_accessor :immi # @return [Integer] The immidiate value currently added.
@@ -49,6 +49,7 @@ module OneGadget
 
       # Decrease dreference count with 1.
       # @return [void]
+      # @raise [ArgumentError] When this object cannot be referenced anymore.
       def ref!
         raise ArgumentError, 'Cannot reference anymore!' if @deref_count <= 0
         @deref_count -= 1
@@ -86,14 +87,18 @@ module OneGadget
       end
 
       class << self
-        # Target: parse something like +[rsp+0x50]+ into a {Lambda} object.
+        # Target: parse things like <tt>[rsp+0x50]</tt> into a {Lambda} object.
         # @param [String] arg
         # @param [Hash{String => Lambda}] predefined
+        #   Predfined values.
         # @return [OneGadget::Emulators::Lambda, Integer]
         #   If +arg+ contains number only, return it.
         #   Otherwise, return a {Lambda} object.
         # @example
-        #   parse('[rsp+0x50]') #=> #<Lambda @obj='rsp', @immi=80, @deref_count=1>
+        #   obj = parse('[rsp+0x50]')
+        #   #=> #<Lambda @obj='rsp', @immi=80, @deref_count=1>
+        #   parse('obj+0x30', predefined: { 'obj' => obj }).to_s
+        #   #=> '[rsp+0x50]+0x30'
         def parse(arg, predefined: {})
           deref_count = 0
           if arg[0] == '[' # a little hack because there should nerver something like +[[rsp+1]+2]+ to parse.

data/lib/one_gadget/fetcher.rb

@@ -34,12 +34,12 @@ module OneGadget
       #   contains offset only.
       #   Otherwise, array of gadgets is returned.
       def from_file(file, details: false)
-        gadgets = {
+        klass = {
           amd64: OneGadget::Fetcher::Amd64,
-          i386: OneGadget::Fetcher::I386,
-          unknown: OneGadget::Fetcher::Base
-        }[OneGadget::Helper.architecture(file)].new(file).find
-        gadgets = trim_gadgets(gadgets)
+          i386: OneGadget::Fetcher::I386
+        }[OneGadget::Helper.architecture(file)]
+        raise ArgumentError, 'Unsupported architecture!' if klass.nil?
+        gadgets = trim_gadgets(klass.new(file).find)
         return gadgets if details
         gadgets.map(&:offset)
       end

data/lib/one_gadget/fetchers/base.rb

@@ -2,7 +2,7 @@ require 'shellwords'
 
 module OneGadget
   module Fetcher
-    # define common methods for gadget fetchers.
+    # Define common methods for gadget fetchers.
     class Base
       # The absolute path of glibc.
       # @return [String] The filename.
@@ -10,7 +10,7 @@ module OneGadget
       # Instantiate a fetcher object.
       # @param [String] file Absolute path of target libc.
       def initialize(file)
-        @file = ::Shellwords.escape(file)
+        @file = file
       end
 
       # Method need to be implemented in inheritors.
@@ -19,6 +19,12 @@ module OneGadget
       end
 
       # Fetch candidates that end with call exec*.
+      #
+      # Give 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(&block)
@@ -34,7 +40,7 @@ module OneGadget
       private
 
       def objdump_cmd(start: nil, stop: nil)
-        cmd = %(objdump -w -d -M intel "#{file}")
+        cmd = %(objdump -w -d -M intel #{::Shellwords.escape(file)})
         cmd.concat(" --start-address #{start}") if start
         cmd.concat(" --stop-address #{stop}") if stop
         cmd
@@ -55,7 +61,8 @@ module OneGadget
       end
 
       def str_offset(str)
-        match = `strings -tx #{file} -n #{str.size} | grep " #{::Shellwords.escape(str)}"`.lines.map(&:strip).first
+        match = `strings -tx #{::Shellwords.escape(file)} -n #{str.size} | grep #{::Shellwords.escape(' ' + str)}`
+        match = match.lines.map(&:strip).first
         return nil if match.nil?
         # 17c8c3 /bin/sh
         match.split.first.to_i(16)

data/lib/one_gadget/gadget.rb

@@ -40,7 +40,9 @@ module OneGadget
 
     # Define class methods here.
     module ClassMethods
-      BUILDS_PATH = File.join(File.dirname(__FILE__), 'builds').freeze
+      # Path to the pre-build files.
+      BUILDS_PATH = File.join(__dir__, 'builds').freeze
+      # Cache.
       BUILDS = Hash.new { |h, k| h[k] = [] }
       # Get gadgets from pre-defined corpus.
       # @param [String] build_id Desired build id.

data/lib/one_gadget/helper.rb

@@ -9,6 +9,7 @@ require 'one_gadget/logger'
 module OneGadget
   # Define some helpful methods here.
   module Helper
+    # Format of build-id, 40 hex numbers.
     BUILD_ID_FORMAT = /[0-9a-f]{40}/
     # Define class methods here.
     module ClassMethods
@@ -125,15 +126,16 @@ module OneGadget
       end
 
       # Fetch the file archiecture of +file+.
-      # @param [String] The target ELF filename.
+      # @param [String] file The target ELF filename.
       # @return [String]
       #   Only supports :amd64, :i386 now.
       def architecture(file)
         str = ELFTools::ELFFile.new(File.open(file)).machine
         return :amd64 if str.include?('X86-64')
         return :i386 if str.include?('Intel 80386')
-      rescue ELFTools::ELFError # not a valid ELF
         :unknown
+      rescue ELFTools::ELFError # not a valid ELF
+        :invalid
       end
 
       # Present number in hex format.

data/lib/one_gadget/version.rb

@@ -1,3 +1,4 @@
 module OneGadget
-  VERSION = '1.3.4.1'.freeze
+  # Current gem version.
+  VERSION = '1.3.5'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: one_gadget
 version: !ruby/object:Gem::Version
-  version: 1.3.4.1
+  version: 1.3.5
 platform: ruby
 authors:
 - david942j
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-22 00:00:00.000000000 Z
+date: 2017-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: elftools
@@ -99,7 +99,7 @@ description: |2
 
     This gem provides such gadget finder, no need to use IDA-pro every time like a fool :p.
 
-    Also provides the command-line tool +one_gadget+ for easy usage.
+    Typing `one_gadget /path/to/libc` in terminal and having fun!
 email:
 - david942j@gmail.com
 executables: