pwntools 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d329dcead1dc5c93633effddf3c627f5071cce80
-  data.tar.gz: b5bf6ed6299056cbd1fd93ad6a37e04a992ce3e1
+SHA256:
+  metadata.gz: 7c323ddeb8d8f4ea3d4d087fc69eb53ee7594f64c2ee01dfb57ada9e2a9eb111
+  data.tar.gz: b9177cb71feb8ecc038680cf850f0b654eea567c7f6774d8ad35cdb1b8949e93
 SHA512:
-  metadata.gz: 71594da6ddc2572a11e2d41c641f04d494d1ea2d3e81ef1a6fd82d92edb3af3599e7099bbdc3393d56a5955fcfd983416dd8be787087fb06d3a586286eb13079
-  data.tar.gz: b7cfba8de4134ea156f58244dff5d1a4e7431b376d1a75d9713503552c11911fb103187249e063baef93cac1f1ce651864f64815e5e2105fc539a6d8ef491df8
+  metadata.gz: 76cbcd91657ecaee5b8bfae49bfe378539937718a1eb46fbe517c8559919877a153cffb0e5beeb06dde68fe64cd7ab9e1fb30af507547771f49331e7bb90c93b
+  data.tar.gz: 1aedd2cb397654aa4bc4e13761a1587431f7a67ecec2150c5e6393f1275dfd14801089e0de7234ddd887b2fb99c9635c9bc438ba183c6fcf8d021331269d99b5

data/README.md

@@ -57,7 +57,7 @@ gem install pwntools
 ```sh
 git clone https://github.com/peter50216/pwntools-ruby
 cd pwntools-ruby
-gem build pwntools.gemspec && gem install pwntools-*.gem
+bundle install && bundle exec rake install
 ```
 
 ### optional
@@ -101,9 +101,10 @@ sudo make install
 - [x] elf
 - [x] dynelf
 - [x] logger
-- [ ] tube
+- [x] tube
   - [x] sock
-  - [ ] process
+  - [x] process
+  - [x] serialtube
 - [ ] fmtstr
 - [x] util
   - [x] pack

data/Rakefile

@@ -7,8 +7,10 @@ require 'rake/testtask'
 require 'rubocop/rake_task'
 require 'yard'
 
+import 'tasks/shellcraft/x86.rake'
+
 RuboCop::RakeTask.new(:rubocop) do |task|
-  task.patterns = ['lib/**/*.rb', 'test/**/*.rb']
+  task.patterns = ['lib/**/*.rb', 'tasks/**/*.rake', 'test/**/*.rb']
 end
 
 task default: %i(install_git_hooks rubocop test)

data/lib/pwnlib/asm.rb

@@ -1,8 +1,12 @@
 # encoding: ASCII-8BIT
 
+require 'tempfile'
+
+require 'elftools'
 require 'keystone_engine/keystone_const'
 
 require 'pwnlib/context'
+require 'pwnlib/errors'
 require 'pwnlib/util/ruby'
 
 module Pwnlib
@@ -11,6 +15,15 @@ module Pwnlib
   module Asm
     module_function
 
+    # Default virtaul memory base address of architectures.
+    #
+    # This address may be different by using different linker.
+    DEFAULT_VMA = {
+      i386: 0x08048000,
+      amd64: 0x400000,
+      arm: 0x8000
+    }.freeze
+
     # Disassembles a bytestring into human readable assembly.
     #
     # {.disasm} depends on another open-source project - capstone, error will be raised if capstone is not intalled.
@@ -22,7 +35,7 @@ module Pwnlib
     # @return [String]
     #   Disassemble result with nice typesetting.
     #
-    # @raise [LoadError]
+    # @raise [Pwnlib::Errors::DependencyError]
     #   If libcapstone is not installed.
     #
     # @example
@@ -85,6 +98,80 @@ module Pwnlib
       KeystoneEngine::Ks.new(ks_arch, ks_mode).asm(code)[0]
     end
 
+    # Builds an ELF file from executable code.
+    #
+    # @param [String] data
+    #   Assembled code.
+    # @param [Integer?] vma
+    #   The load address for the ELF file.
+    #   If +nil+ is given, default address will be used.
+    #   See {DEFAULT_VMA}.
+    # @param [Boolean] to_file
+    #   Returns ELF content or the path to the ELF file.
+    #   If +true+ is given, the ELF will be saved into a temp file.
+    #
+    # @return [String, Object]
+    #   Without block
+    #   - If +to_file+ is +false+ (default), returns the content of ELF.
+    #   - Otherwise, a file is created and the path is returned.
+    #   With block given, an ELF file will be created and its path will be yielded.
+    #   This method will return what the block returned, and the ELF file will be removed after the block yielded.
+    #
+    # @yieldparam [String] path
+    #   The path to the created ELF file.
+    #
+    # @yieldreturn [Object]
+    #   Whatever you want.
+    #
+    # @raise [::Pwnlib::Errors::UnsupportedArchError]
+    #   Raised when don't know how to create an ELF under architecture +context.arch+.
+    #
+    # @diff
+    #   Unlike pwntools-python uses cross-compiler to compile code into ELF, we create ELFs in pure Ruby
+    #   implementation. Therefore, we have higher flexibility and less binary dependencies.
+    #
+    # @example
+    #   bin = make_elf(asm(shellcraft.sh))
+    #   bin[0, 4]
+    #   #=> "\x7FELF"
+    # @example
+    #   path = make_elf(asm(shellcraft.cat('/proc/self/maps')), to_file: true)
+    #   puts `#{path}`
+    #   # 08048000-08049000 r-xp 00000000 fd:01 27671233                           /tmp/pwn20180129-3411-7klnng.elf
+    #   # f77c7000-f77c9000 r--p 00000000 00:00 0                                  [vvar]
+    #   # f77c9000-f77cb000 r-xp 00000000 00:00 0                                  [vdso]
+    #   # ffda6000-ffdc8000 rwxp 00000000 00:00 0                                  [stack]
+    # @example
+    #   # no need 'to_file' parameter if block is given
+    #   make_elf(asm(shellcraft.cat('/proc/self/maps'))) do |path|
+    #     puts `#{path}`
+    #     # 08048000-08049000 r-xp 00000000 fd:01 27671233                           /tmp/pwn20180129-3411-7klnng.elf
+    #     # f77c7000-f77c9000 r--p 00000000 00:00 0                                  [vvar]
+    #     # f77c9000-f77cb000 r-xp 00000000 00:00 0                                  [vdso]
+    #     # ffda6000-ffdc8000 rwxp 00000000 00:00 0                                  [stack]
+    #   end
+    def make_elf(data, vma: nil, to_file: false)
+      to_file ||= block_given?
+      vma ||= DEFAULT_VMA[context.arch.to_sym]
+      vma &= -0x1000
+      # ELF header
+      # Program headers
+      # <data>
+      headers = create_elf_headers(vma)
+      ehdr = headers[:elf_header]
+      phdr = headers[:program_header]
+      entry = ehdr.num_bytes + phdr.num_bytes
+      ehdr.e_entry = entry + phdr.p_vaddr
+      ehdr.e_phoff = ehdr.num_bytes
+      phdr.p_filesz = phdr.p_memsz = entry + data.size
+      elf = ehdr.to_binary_s + phdr.to_binary_s + data
+      return elf unless to_file
+      path = Dir::Tmpname.create(['pwn', '.elf']) do |temp|
+        File.open(temp, 'wb', 0o750) { |f| f.write(elf) }
+      end
+      block_given? ? yield(path).tap { File.unlink(path) } : path
+    end
+
     ::Pwnlib::Util::Ruby.private_class_method_block do
       def cap_arch
         {
@@ -118,7 +205,7 @@ module Pwnlib
       def require_message(lib, msg)
         require lib
       rescue LoadError => e
-        raise LoadError, e.message + "\n\n" + msg
+        raise ::Pwnlib::Errors::DependencyError, e.message + "\n\n" + msg
       end
 
       def install_crabstone_guide
@@ -140,6 +227,89 @@ https://github.com/keystone-engine/keystone/tree/master/docs
 
         EOS
       end
+
+      # build headers according to context.arch/bits/endian
+      def create_elf_headers(vma)
+        elf_header = create_elf_header
+        # we only need one LOAD segment
+        program_header = create_program_header(vma)
+        elf_header.e_phentsize = program_header.num_bytes
+        elf_header.e_phnum = 1
+        {
+          elf_header: elf_header,
+          program_header: program_header
+        }
+      end
+
+      def create_elf_header
+        header = ::ELFTools::Structs::ELF_Ehdr.new(endian: endian)
+        # this decide size of entries
+        header.elf_class = context.bits
+        header.e_ident.magic = ::ELFTools::Constants::ELFMAG
+        header.e_ident.ei_class = { 32 => 1, 64 => 2 }[context.bits]
+        header.e_ident.ei_data = { little: 1, big: 2 }[endian]
+        # Not sure what version field means, seems it can be any value.
+        header.e_ident.ei_version = 1
+        header.e_ident.ei_padding = "\x00" * 7
+        header.e_type = ::ELFTools::Constants::ET::ET_EXEC
+        header.e_machine = e_machine
+        # XXX(david942j): is header.e_flags important?
+        header.e_ehsize = header.num_bytes
+        header
+      end
+
+      def create_program_header(vma)
+        header = ::ELFTools::Structs::ELF_Phdr[context.bits].new(endian: endian)
+        header.p_type = ::ELFTools::Constants::PT::PT_LOAD
+        header.p_offset = 0
+        header.p_vaddr = vma
+        header.p_paddr = vma
+        header.p_flags = 4 | 1 # r-x
+        header.p_align = arch_align
+        header
+      end
+
+      # Not sure how this field is used, remove this if it is not important.
+      # This table is collected by cross-compiling and see the align in LOAD segment.
+      def arch_align
+        case context.arch.to_sym
+        when :i386, :amd64 then 0x1000
+        when :arm then 0x8000
+        end
+      end
+
+      # Mapping +context.arch+ to +::ELFTools::Constants::EM::EM_*+.
+      ARCH_EM = {
+        aarch64: 'AARCH64',
+        alpha: 'ALPHA',
+        amd64: 'X86_64',
+        arm: 'ARM',
+        cris: 'CRIS',
+        i386: '386',
+        ia64: 'IA_64',
+        m68k: '68K',
+        mips64: 'MIPS',
+        mips: 'MIPS',
+        powerpc64: 'PPC64',
+        powerpc: 'PPC',
+        s390: 'S390',
+        sparc64: 'SPARCV9',
+        sparc: 'SPARC'
+      }.freeze
+
+      def e_machine
+        const = ARCH_EM[context.arch.to_sym]
+        if const.nil?
+          raise ::Pwnlib::Errors::UnsupportedArchError,
+                "Unknown machine type of architecture #{context.arch.inspect}."
+        end
+        ::ELFTools::Constants::EM.const_get("EM_#{const}")
+      end
+
+      def endian
+        context.endian.to_sym
+      end
+
       include ::Pwnlib::Context
     end
   end

data/lib/pwnlib/constants/constants.rb

@@ -4,6 +4,7 @@ require 'dentaku'
 
 require 'pwnlib/constants/constant'
 require 'pwnlib/context'
+require 'pwnlib/errors'
 
 module Pwnlib
   # Module containing constants.
@@ -36,17 +37,23 @@ module Pwnlib
       # @return [Constant]
       #   The evaluated result.
       #
+      # @raise [Pwnlib::Errors::ConstantNotFoundError]
+      #   Raised when undefined constant(s) provided.
+      #
       # @example
-      #   eval('O_CREAT')
+      #   Constants.eval('O_CREAT')
       #   #=> Constant('(O_CREAT)', 0x40)
-      #   eval('O_CREAT | O_APPEND')
+      #   Constants.eval('O_CREAT | O_APPEND')
       #   #=> Constant('(O_CREAT | O_APPEND)', 0x440)
+      # @example
+      #   Constants.eval('meow')
+      #   # Pwnlib::Errors::ConstantNotFoundError: Undefined constant(s): meow
       def eval(str)
         return str unless str.instance_of?(String)
         begin
           val = calculator.evaluate!(str.strip).to_i
         rescue Dentaku::UnboundVariableError => e
-          raise NameError, e.message
+          raise ::Pwnlib::Errors::ConstantNotFoundError, "Undefined constant(s): #{e.unbound_variables.join(', ')}"
         end
         ::Pwnlib::Constants::Constant.new("(#{str})", val)
       end

data/lib/pwnlib/context.rb

@@ -274,9 +274,7 @@ module Pwnlib
         when true, false
           signed = value
         end
-        if signed.nil?
-          raise ArgumentError, "signed must be boolean or one of #{SIGNEDNESSES.keys.sort.inspect}"
-        end
+        raise ArgumentError, "signed must be boolean or one of #{SIGNEDNESSES.keys.sort.inspect}" if signed.nil?
         @attrs[:signed] = signed
       end
 

data/lib/pwnlib/elf/elf.rb

@@ -1,5 +1,6 @@
-require 'elftools'
 require 'ostruct'
+
+require 'elftools'
 require 'rainbow'
 
 require 'pwnlib/logger'
@@ -40,7 +41,7 @@ module Pwnlib
       #   #=> #<Pwnlib::ELF::ELF:0x00559bd670dcb8>
       def initialize(path, checksec: true)
         path = File.realpath(path)
-        @elf_file = ELFTools::ELFFile.new(File.open(path, 'rb')) # rubocop:disable Style/AutoResourceCleanup
+        @elf_file = ELFTools::ELFFile.new(File.open(path, 'rb'))
         load_got
         load_plt
         load_symbols
@@ -67,7 +68,6 @@ module Pwnlib
         [@got, @plt, @symbols].compact.each do |tbl|
           tbl.each_pair { |k, _| tbl[k] += val - old }
         end
-        val
       end
 
       # Return the protection information, wrapper with color codes.

data/lib/pwnlib/errors.rb

@@ -0,0 +1,30 @@
+# encoding: ASCII-8BIT
+
+module Pwnlib
+  # Generic {Pwnlib} exception class.
+  class Error < StandardError
+  end
+
+  # Pnwlib Errors
+  module Errors
+    # Raised by some IO operations in tubes.
+    class EndOfTubeError < ::Pwnlib::Error
+    end
+
+    # Raised when a dependent file fails to load.
+    class DependencyError < ::Pwnlib::Error
+    end
+
+    # Raised when a given constant is invalid or undefined.
+    class ConstantNotFoundError < ::Pwnlib::Error
+    end
+
+    # Raised when timeout exceeded.
+    class TimeoutError < ::Pwnlib::Error
+    end
+
+    # Raised when method doesn't support under current architecture.
+    class UnsupportedArchError < ::Pwnlib::Error
+    end
+  end
+end

data/lib/pwnlib/ext/helper.rb

@@ -9,7 +9,7 @@ module Pwnlib
           .map { |x| [x, x] }
           .concat(m2.to_a)
           .each do |method, proxy_to|
-            class_eval <<-EOS
+            class_eval(<<-EOS, __FILE__, __LINE__ + 1)
               def #{method}(*args, &block)
               #{mod}.#{proxy_to}(self, *args, &block)
               end

data/lib/pwnlib/logger.rb

@@ -1,7 +1,11 @@
 # encoding: ASCII-8BIT
 
 require 'logger'
+
+require 'method_source/code_helpers' # don't require 'method_source', it pollutes Method/Proc classes.
 require 'rainbow'
+require 'ruby2ruby'
+require 'ruby_parser'
 
 require 'pwnlib/context'
 
@@ -13,6 +17,12 @@ module Pwnlib
     # The type for logger which inherits Ruby builtin Logger.
     # Main difference is using +context.log_level+ instead of +level+ in logging methods.
     class LoggerType < ::Logger
+      # To use method +expression_at+.
+      #
+      # XXX(david942j): move this extension if other modules need +expression_at+ as well.
+      extend ::MethodSource::CodeHelpers
+
+      # Color codes for pretty logging.
       SEV_COLOR = {
         'DEBUG' => '#ff5f5f',
         'INFO' => '#87ff00',
@@ -24,8 +34,8 @@ module Pwnlib
       # Instantiate a {Pwnlib::Logger::LoggerType} object.
       def initialize
         super(STDOUT)
-        @formatter = proc do |severity, _datetime, _progname, msg|
-          format("[%s] %s\n", Rainbow(severity).color(SEV_COLOR[severity]), msg)
+        @formatter = proc do |severity, _datetime, progname, msg|
+          format("[%s] %s\n", Rainbow(progname || severity).color(SEV_COLOR[severity]), msg)
         end
       end
 
@@ -43,6 +53,70 @@ module Pwnlib
         true
       end
 
+      # Log the arguments and their evalutated results.
+      #
+      # This method has same severity as +INFO+.
+      #
+      # The difference between using arguments and passing a block is the block will be executed if the logger's level
+      # is sufficient to log a message.
+      #
+      # @param [Array<#inspect>] args
+      #   Anything. See examples.
+      #
+      # @yieldreturn [#inspect]
+      #   See examples.
+      #   Block will be invoked only if +args+ is empty.
+      #
+      # @return See ::Logger#add.
+      #
+      # @example
+      #   x = 2
+      #   y = 3
+      #   log.dump(x + y, x * y)
+      #   # [DUMP] (x + y) = 5, (x * y) = 6
+      # @example
+      #   libc = 0x7fc0bdd13000
+      #   log.dump libc.hex
+      #   # [DUMP] libc.hex = "0x7fc0bdd13000"
+      #
+      #   libc = 0x7fc0bdd13000
+      #   log.dump { libc.hex }
+      #   # [DUMP] libc.hex = "0x7fc0bdd13000"
+      #   log.dump { libc = 12345678; libc.hex }
+      #   # [DUMP] libc = 12345678
+      #   #        libc.hex = "0xbc614e"
+      # @example
+      #   log.dump do
+      #     meow = 123
+      #     # comments will be ignored
+      #     meow <<= 1 # this is a comment
+      #     meow
+      #   end
+      #   # [DUMP] meow = 123
+      #   #        meow = (meow << 1)
+      #   #        meow = 246
+      #
+      # @note
+      #   This method does NOT work in a REPL shell (such as irb and pry).
+      #
+      # @note
+      #   The source code where invoked +log.dump+ will be parsed by using +ruby_parser+,
+      #   therefore this method fails in some situations, such as:
+      #     log.dump(&something) # will fail in souce code parsing
+      #     log.dump { 1 }; log.dump { 2 } # 1 will be logged two times
+      def dump(*args)
+        severity = INFO
+        # Don't invoke the block if it's unnecessary.
+        return true if severity < context.log_level
+        caller_ = caller_locations(1, 1).first
+        src = source_of(caller_.absolute_path, caller_.lineno)
+        results = args.empty? ? [[yield, source_of_block(src)]] : args.zip(source_of_args(src))
+        msg = results.map { |res, expr| "#{expr.strip} = #{res.inspect}" }.join(', ')
+        # do indent if msg contains multiple lines
+        first, *remain = msg.split("\n")
+        add(severity, ([first] + remain.map { |r| '[DUMP] '.gsub(/./, ' ') + r }).join("\n"), 'DUMP')
+      end
+
       private
 
       def add(severity, message = nil, progname = nil)
@@ -51,6 +125,70 @@ module Pwnlib
         super(severity, message, progname)
       end
 
+      def source_of(path, line_number)
+        File.open(path) { |f| LoggerType.expression_at(f, line_number) }
+      end
+
+      # Find the content of block that invoked by log.dump { ... }.
+      #
+      # @param [String] source
+      #
+      # @return [String]
+      #
+      # @example
+      #   source_of_block("log.dump do\n123\n456\nend")
+      #   #=> "123\n456\n"
+      def source_of_block(source)
+        parse_and_search(source, [:iter, [:call, nil, :dump]]) { |sexp| ::Ruby2Ruby.new.process(sexp.last) }
+      end
+
+      # Find the arguments passed to log.dump(...).
+      #
+      # @param [String] source
+      #
+      # @return [Array<String>]
+      #
+      # @example
+      #   source_of_args("log.dump(x, y, x + y)")
+      #   #=> ["x", "y", "(x + y)"]
+      def source_of_args(source)
+        parse_and_search(source, [:call, nil, :dump]) do |sexp|
+          sexp[3..-1].map { |s| ::Ruby2Ruby.new.process(s) }
+        end
+      end
+
+      # This method do the following things:
+      #   1. Parse the source code to `Sexp` (using `ruby_parser`)
+      #   2. Traverse the sexp to find the block/arguments (according to target) when calling `dump`
+      #   3. Convert the sexp of block back to Ruby code (using gem `ruby2ruby`)
+      #
+      # @yieldparam [Sexp] sexp
+      #   The found Sexp according to +target+.
+      def parse_and_search(source, target)
+        sexp = ::RubyParser.new.process(source)
+        sexp = search_sexp(sexp, target)
+        return nil if sexp.nil?
+        yield sexp
+      end
+
+      # depth-first search
+      def search_sexp(sexp, target)
+        return nil unless sexp.is_a?(::Sexp)
+        return sexp if match_sexp?(sexp, target)
+        sexp.find do |e|
+          f = search_sexp(e, target)
+          break f if f
+        end
+      end
+
+      def match_sexp?(sexp, target)
+        target.zip(sexp.entries).all? do |t, s|
+          next true if t.nil?
+          next match_sexp?(s, t) if t.is_a?(Array)
+          s == t
+        end
+      end
+
       include ::Pwnlib::Context
     end