pwntools 0.1.0 → 1.2.1

data/lib/pwnlib/constants/constant.rb

@@ -1,19 +1,35 @@
 # encoding: ASCII-8BIT
+# frozen_string_literal: true
 
 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)
+        super()
         @str = str
         @val = val
       end
 
       # We don't need to fall back to super for this, so just disable the lint.
-      def method_missing(method, *args, &block) # rubocop:disable Style/MethodMissing
+      def method_missing(method, *args, &block)
         @val.__send__(method, *args, &block)
       end
 

data/lib/pwnlib/constants/constants.rb

@@ -1,45 +1,63 @@
 # encoding: ASCII-8BIT
+# frozen_string_literal: true
+
+require 'dentaku'
 
-require 'pwnlib/context'
 require 'pwnlib/constants/constant'
+require 'pwnlib/context'
+require 'pwnlib/errors'
 
 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)
+      # @raise [Pwnlib::Errors::ConstantNotFoundError]
+      #   Raised when undefined constant(s) provided.
       #
-      # @todo(david942j): Support eval('O_CREAT | O_APPEND') (i.e. safeeval)
+      # @example
+      #   Constants.eval('O_CREAT')
+      #   #=> Constant('(O_CREAT)', 0x40)
+      #   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)
-        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 ::Pwnlib::Errors::ConstantNotFoundError, "Undefined constant(s): #{e.unbound_variables.join(', ')}"
+        end
+        ::Pwnlib::Constants::Constant.new("(#{str})", val)
       end
 
       private
@@ -48,6 +66,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 +75,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
@@ -71,12 +96,13 @@ module Pwnlib
       def load_constants((os, arch))
         filename = File.join(__dir__, os, "#{arch}.rb")
         return {} unless File.exist?(filename)
+
         builder = ConstantBuilder.new
         builder.instance_eval(IO.read(filename))
         builder.tbl
       end
-    end
 
-    extend ClassMethods
+      include ::Pwnlib::Context
+    end
   end
 end

data/lib/pwnlib/constants/linux/amd64.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 const :__NR_read, 0
 const :__NR_write, 1
 const :__NR_open, 2
@@ -235,7 +237,6 @@ const :__NR_epoll_ctl, 233
 const :__NR_tgkill, 234
 const :__NR_utimes, 235
 const :__NR_vserver, 236
-const :__NR_vserver, 236
 const :__NR_mbind, 237
 const :__NR_set_mempolicy, 238
 const :__NR_get_mempolicy, 239
@@ -302,6 +303,36 @@ const :__NR_recvmmsg, 299
 const :__NR_fanotify_init, 300
 const :__NR_fanotify_mark, 301
 const :__NR_prlimit64, 302
+const :__NR_name_to_handle_at, 303
+const :__NR_open_by_handle_at, 304
+const :__NR_clock_adjtime, 305
+const :__NR_syncfs, 306
+const :__NR_sendmmsg, 307
+const :__NR_setns, 308
+const :__NR_getcpu, 309
+const :__NR_process_vm_readv, 310
+const :__NR_process_vm_writev, 311
+const :__NR_kcmp, 312
+const :__NR_finit_module, 313
+const :__NR_sched_setattr, 314
+const :__NR_sched_getattr, 315
+const :__NR_renameat2, 316
+const :__NR_seccomp, 317
+const :__NR_getrandom, 318
+const :__NR_memfd_create, 319
+const :__NR_kexec_file_load, 320
+const :__NR_bpf, 321
+const :__NR_execveat, 322
+const :__NR_userfaultfd, 323
+const :__NR_membarrier, 324
+const :__NR_mlock2, 325
+const :__NR_copy_file_range, 326
+const :__NR_preadv2, 327
+const :__NR_pwritev2, 328
+const :__NR_pkey_mprotect, 329
+const :__NR_pkey_alloc, 330
+const :__NR_pkey_free, 331
+const :__NR_statx, 332
 const :SYS32_restart_syscall, 0
 const :SYS32_exit, 1
 const :SYS32_fork, 2

data/lib/pwnlib/constants/linux/i386.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 const :__NR_exit, 1
 const :__NR_fork, 2
 const :__NR_read, 3

data/lib/pwnlib/context.rb

@@ -1,4 +1,5 @@
 # encoding: ASCII-8BIT
+# frozen_string_literal: true
 
 require 'logger'
 
@@ -17,7 +18,7 @@ module Pwnlib
         newline: "\n",
         os: 'linux',
         signed: false,
-        timeout: Float::INFINITY
+        timeout: :forever
       }.freeze
 
       OSES = %w(linux freebsd windows).sort
@@ -30,10 +31,11 @@ module Pwnlib
       LITTLE_64 = { endian: 'little', bits: 64 }.freeze
 
       class << self
+        private
+
         def longest(d)
           Hash[d.sort_by { |k, _v| k.size }.reverse]
         end
-        private :longest
       end
 
       ARCHS = longest(
@@ -76,19 +78,26 @@ module Pwnlib
 
       VALID_SIGNED = SIGNEDNESSES.keys
 
-      # XXX(Darkpi): Should we just hard-coded all levels here,
-      # or should we use Logger#const_defined?
-      # (This would include constant SEV_LEVEL, and exclude UNKNOWN)?
+      # We use Logger#const_defined for pwnlib logger.
       LOG_LEVELS = %w(DEBUG INFO WARN ERROR FATAL UNKNOWN).freeze
 
+      # Instantiate a {Pwnlib::Context::ContextType} object.
       def initialize(**kwargs)
         @attrs = DEFAULT.dup
         update(**kwargs)
       end
 
+      # Convenience function, which is shorthand for setting multiple variables at once.
+      #
+      # @param [Hash] kwargs
+      #   Variables to be assigned in the environment.
+      #
+      # @example
+      #   context.update(arch: 'amd64', os: :linux)
       def update(**kwargs)
         kwargs.each do |k, v|
           next if v.nil?
+
           public_send("#{k}=", v)
         end
         self
@@ -97,16 +106,29 @@ module Pwnlib
       alias [] update
       alias call update
 
+      # Create a string representation of self.
       def to_s
         vals = @attrs.map { |k, v| "#{k} = #{v.inspect}" }
         "#{self.class}(#{vals.join(', ')})"
       end
 
-      # This would return what the block return.
+      # Create a context manager for a block.
+      #
+      # @param [Hash] kwargs
+      #   Variables to be assigned in the environment.
+      #
+      # @return
+      #   This would return what the block returned.
+      #
+      # @example
+      #   context.local(arch: 'amd64') { puts context.endian }
+      #   # little
       def local(**kwargs)
         raise ArgumentError, "Need a block for #{self.class}##{__callee__}" unless block_given?
-        # XXX(Darkpi): improve performance for this if this is too slow, since we use this in many
-        #              places that has argument endian / signed / ...
+
+        # XXX(Darkpi):
+        #   improve performance for this if this is too slow, since we use this in many places that has argument
+        #   endian / signed / ...
         old_attrs = @attrs.dup
         begin
           update(**kwargs)
@@ -116,6 +138,13 @@ module Pwnlib
         end
       end
 
+      # Clear the contents of the context, which will set all values to their defaults.
+      #
+      # @example
+      #   context.arch = 'amd64'
+      #   context.clear
+      #   context.bits == 32
+      #   #=> true
       def clear
         @attrs = DEFAULT.dup
       end
@@ -125,74 +154,136 @@ module Pwnlib
         define_method(k) { @attrs[k] }
       end
 
+      # Set the newline.
+      #
+      # @param [String] newline
+      #   The newline.
+      #
+      # @example
+      #   context.newline = "\r\n"
       def newline=(newline)
         @attrs[:newline] = newline
       end
 
-      # TODO(Darkpi): Timeout module.
+      # Set the default amount of time to wait for a blocking operation before it times out.
+      #
+      # @param [Float, :forever] timeout
+      #   Any positive floating number, indicates timeout in seconds.
+      #
+      # @example
+      #   context.timeout = 5.14
       def timeout=(timeout)
         @attrs[:timeout] = timeout
       end
 
-      # Difference from Python pwntools:
-      # We always change +bits+ and +endian+ field whether user have already changed them.
+      # Set the architecture of the target binary.
+      #
+      # @param [String, Symbol] arch
+      #   The architecture. Only values in {Pwnlib::Context::ContextType::ARCHS} are available.
+      #
+      # @diff We always change +bits+ and +endian+ field whether user have already changed them.
       def arch=(arch)
-        arch = arch.downcase.gsub(/[[:punct:]]/, '')
+        arch = arch.to_s.downcase.gsub(/[[:punct:]]/, '')
         defaults = ARCHS[arch]
         raise ArgumentError, "arch must be one of #{ARCHS.keys.sort.inspect}" unless defaults
+
         defaults.each { |k, v| @attrs[k] = v }
         @attrs[:arch] = arch
       end
 
+      # Set the word size of the target machine in bits (i.e. the size of general purpose registers).
+      #
+      # @param [Integer] bits
+      #   The word size.
       def bits=(bits)
-        raise ArgumentError, "bits must be > 0 (#{bits} given)" unless bits > 0
+        raise ArgumentError, "bits must be > 0 (#{bits} given)" unless bits.positive?
+
         @attrs[:bits] = bits
       end
 
+      # The word size of the target machine.
       def bytes
         bits / 8
       end
 
+      # Set the word size of the target machine in bytes (i.e. the size of general purpose registers).
+      #
+      # @param [Integer] bytes
+      #   The word size.
       def bytes=(bytes)
         self.bits = bytes * 8
       end
 
+      # The endianness of the target machine.
+      #
+      # @param [String, Symbol] endian
+      #   The endianness. Only values in {Pwnlib::Context::ContextType::ENDIANNESSES} are available.
+      #
+      # @example
+      #   context.endian = :big
       def endian=(endian)
-        endian = ENDIANNESSES[endian.downcase]
+        endian = ENDIANNESSES[endian.to_s.downcase]
         raise ArgumentError, "endian must be one of #{ENDIANNESSES.sort.inspect}" if endian.nil?
+
         @attrs[:endian] = endian
       end
 
+      # Set the verbosity of the logger in +Pwnlib+.
+      #
+      # @param [String, Symbol] value
+      #   The verbosity. Only values in {Pwnlib::Context::ContextType::LOG_LEVELS} are available.
+      #
+      # @example
+      #   context.log_level = :debug
       def log_level=(value)
         log_level = nil
         case value
-        when String
-          value = value.upcase
+        when String, Symbol
+          value = value.to_s.upcase
           log_level = Logger.const_get(value) if LOG_LEVELS.include?(value)
         when Integer
           log_level = value
         end
         raise ArgumentError, "log_level must be an integer or one of #{LOG_LEVELS.inspect}" unless log_level
+
         @attrs[:log_level] = log_level
       end
 
+      # Set the operating system of the target machine.
+      #
+      # @param [String, Symbol] os
+      #   The name of the os. Only values in {Pwnlib::Context::ContextType::OSES} are available.
+      #
+      # @example
+      #   context.os = :windows
       def os=(os)
-        os = os.downcase
+        os = os.to_s.downcase
         raise ArgumentError, "os must be one of #{OSES.sort.inspect}" unless OSES.include?(os)
+
         @attrs[:os] = os
       end
 
+      # Set the signedness for packing opreation.
+      #
+      # @param [String, Symbol, true, false] value
+      #   The signedness. Only values in {Pwnlib::Context::ContextType::SIGNEDNESSES} are available.
+      #
+      # @example
+      #   context.signed == false
+      #   #=> true
+      #   context.signed = 'signed'
+      #   context.signed == true
+      #   #=> true
       def signed=(value)
         signed = nil
         case value
-        when String
-          signed = SIGNEDNESSES[value.downcase]
+        when String, Symbol
+          signed = SIGNEDNESSES[value.to_s.downcase]
         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
 
@@ -201,20 +292,30 @@ module Pwnlib
 
     @context = ContextType.new
 
+    # @!attribute [r] context
+    #   @return [ContextType] the singleton context for all class.
     class << self
       attr_reader :context
     end
 
-    # For include.
+    # A module for include hook for context.
+    # Including Pwnlib::Context from module M would add +context+ as a private instance method and a private class
+    # method for module M.
     # @!visibility private
-    def context
-      ::Pwnlib::Context.context
+    module IncludeContext
+      private
+
+      def context
+        ::Pwnlib::Context.context
+      end
     end
 
     # @!visibility private
     def self.included(base)
-      # XXX(Darkpi): Should we do this?
-      base.__send__(:private, :context)
+      base.include(IncludeContext)
+      class << base
+        include IncludeContext
+      end
     end
   end
 end