wpxf 2.0.0a

data/lib/wpxf/core/opts/boolean_option.rb

@@ -0,0 +1,37 @@
+
+# frozen_string_literal: true
+
+module Wpxf
+  # A boolean option.
+  class BooleanOption < Option
+    # Check if the specified value is valid in the context of this option.
+    # @param value the value to validate.
+    # @return [Boolean] true if valid.
+    def valid?(value)
+      return false if empty_required_value?(value)
+      return true if !required? && empty?(value)
+
+      pattern = /^(y|yes|n|no|t|f|0|1|true|false)$/i
+      value?(value) && !value.to_s.match(pattern).nil?
+    end
+
+    # @param value the value to normalize.
+    # @return [Boolean] a normalized value to conform with the type that.
+    #   the option is conveying.
+    def normalize(value)
+      valid?(value) && !value.to_s.match(/^(y|yes|t|1|true)$/i).nil?
+    end
+
+    # @param value the value to check.
+    # @return [Boolean] true if the value is a true boolean value.
+    def true?(value)
+      normalize(value)
+    end
+
+    # @param value the value to check.
+    # @return [Boolean] true if the value is a false boolean value.
+    def false?(value)
+      !true?(value)
+    end
+  end
+end

data/lib/wpxf/core/opts/enum_option.rb

@@ -0,0 +1,15 @@
+
+# frozen_string_literal: true
+
+module Wpxf
+  # An enum option.
+  class EnumOption < Option
+    # Check if the specified value is valid in the context of this option.
+    # @param value the value to validate.
+    # @return [Boolean] true if valid.
+    def valid?(value)
+      return false if value && !enums.include?(value)
+      super
+    end
+  end
+end

data/lib/wpxf/core/opts/integer_option.rb

@@ -0,0 +1,74 @@
+
+# frozen_string_literal: true
+
+module Wpxf
+  # An integer option.
+  class IntegerOption < Option
+    # Initializes a named option.
+    # @param attrs an object containing the following values
+    #   * *name*: the name of the option (required)
+    #   * *desc*: the description of the option (required)
+    #   * *required*: whether or not the option is required
+    #   * *default*: the default value of the option
+    #   * *advanced*: whether or not this is an advanced option
+    #   * *evasion*: whether or not this is an evasion option
+    #   * *enums*: the list of potential valid values
+    #   * *regex*: regex to validate the option value
+    #   * *min*: the lowest valid value
+    #   * *max*: the highest valid value
+    def initialize(attrs)
+      super
+
+      self.min = attrs[:min].to_i unless attrs[:min].nil?
+      self.max = attrs[:max].to_i unless attrs[:max].nil?
+    end
+
+    # @param value the value to normalize.
+    # @return [Integer] a normalized value to conform with the type that
+    #   the option is conveying.
+    def normalize(value)
+      if value.to_s.match?(/^0x[a-fA-F\d]+$/)
+        value.to_i(16)
+      else
+        value.to_i
+      end
+    end
+
+    # @param value the value to validate.
+    # @return [Boolean] true if the value is a valid integer.
+    def valid_integer?(value)
+      value && !value.to_s.match(/^0x[0-9a-fA-F]+$|^-?\d+$/).nil?
+    end
+
+    # @param value the value to validate.
+    # @return [Boolean] true if the value meets the minimum valid value
+    #   requirement.
+    def meets_min_requirement?(value)
+      min.nil? || (normalize(value) >= min)
+    end
+
+    # @param value the value to validate.
+    # @return [Boolean] true if the value meets the maximum valid value
+    #   requirement.
+    def meets_max_requirement?(value)
+      max.nil? || (normalize(value) <= max)
+    end
+
+    # Check if the specified value is valid in the context of this option.
+    # @param value the value to validate.
+    # @return [Boolean] true if valid.
+    def valid?(value)
+      return true if value.nil? && !required?
+      return false unless valid_integer?(value)
+      return false unless meets_min_requirement?(value)
+      return false unless meets_max_requirement?(value)
+      super
+    end
+
+    # @return [Integer, nil] the lowest valid value.
+    attr_accessor :min
+
+    # @return [Integer, nil] the highest valid value.
+    attr_accessor :max
+  end
+end

data/lib/wpxf/core/opts/option.rb

@@ -0,0 +1,121 @@
+
+# frozen_string_literal: true
+
+module Wpxf
+  # The base class for all module options.
+  class Option
+    # Initializes a named option.
+    # @param attrs an object containing the following values
+    #   * *name*: the name of the option (required)
+    #   * *desc*: the description of the option (required)
+    #   * *required*: whether or not the option is required
+    #   * *default*: the default value of the option
+    #   * *advanced*: whether or not this is an advanced option
+    #   * *evasion*: whether or not this is an evasion option
+    #   * *enums*: the list of potential valid values
+    #   * *regex*: regex to validate the option value
+    def initialize(attrs)
+      if attrs[:name].nil? && attrs[:desc].nil?
+        raise 'A value must be specified for :name and :desc'
+      end
+
+      self.name = attrs[:name]
+      self.desc = attrs[:desc]
+      update_optional_attributes(attrs)
+    end
+
+    # Update the optional attributes of the option.
+    # @param attrs [Hash] the new values.
+    def update_optional_attributes(attrs)
+      self.required = attrs[:required] || false
+      self.default = attrs[:default]
+      self.advanced = attrs[:advanced] || false
+      self.evasion = attrs[:evasion] || false
+      self.enums = attrs[:enums]
+      self.regex = attrs[:regex]
+    end
+
+    # @return [Boolean] true if this is an advanced option.
+    def advanced?
+      advanced
+    end
+
+    # @return [Boolean] true if this is an evasion option.
+    def evasion?
+      evasion
+    end
+
+    # @return [Boolean] true if this is a required option.
+    def required?
+      required
+    end
+
+    # Checks if the specified value is valid in the context of this option.
+    # @param value the value to validate.
+    # @return [Boolean] true if valid.
+    def valid?(value)
+      return false if empty_required_value?(value)
+      return true if !required? && empty?(value)
+      return value.to_s.match?(regex) if regex
+
+      true
+    end
+
+    # @param value the value to check.
+    # @return [Boolean] true if the value is nil or empty.
+    def empty?(value)
+      value.nil? || value.to_s.empty?
+    end
+
+    # @param value the value to check.
+    # @return [Boolean] true if the value is not nil or empty.
+    def value?(value)
+      !empty?(value)
+    end
+
+    # @param value the value to check against.
+    # @return [Boolean] true if the value supplied is nil or empty and
+    #   it's required to be a valid value.
+    def empty_required_value?(value)
+      required? && empty?(value)
+    end
+
+    # @param value the value to normalize.
+    # @return a normalized value to conform with the type that the option
+    #   is conveying.
+    def normalize(value)
+      value
+    end
+
+    # @param value the value to get the display value of.
+    # @return [String] a string representing a user-friendly display of
+    #   the chosen value.
+    def display_value(value)
+      value.to_s
+    end
+
+    # @return [String] the name of the option.
+    attr_accessor :name
+
+    # @return [Boolean] whether or not the option is required.
+    attr_accessor :required
+
+    # @return [String] the description of the option.
+    attr_accessor :desc
+
+    # @return [Object, nil] the default value of the option.
+    attr_accessor :default
+
+    # @return [Boolean] whether or not this is an advanced option.
+    attr_accessor :advanced
+
+    # @return [Boolean] whether or not this is an evasion option.
+    attr_accessor :evasion
+
+    # @return [Array, nil] the list of potential valid values.
+    attr_accessor :enums
+
+    # @return [String, nil] an optional regex to validate the option value.
+    attr_accessor :regex
+  end
+end

data/lib/wpxf/core/opts/path_option.rb

@@ -0,0 +1,15 @@
+
+# frozen_string_literal: true
+
+module Wpxf
+  # A file system path option.
+  class PathOption < Option
+    # Check if the specified value is valid in the context of this option.
+    # @param value the value to validate.
+    # @return [Boolean] true if valid.
+    def valid?(value)
+      return super if empty?(value)
+      File.exist?(value)
+    end
+  end
+end

data/lib/wpxf/core/opts/port_option.rb

@@ -0,0 +1,25 @@
+
+# frozen_string_literal: true
+
+module Wpxf
+  # A network port option.
+  class PortOption < Option
+    # @param value the value to normalize.
+    # @return [Integer] a normalized value to conform with the type that
+    #   the option is conveying.
+    def normalize(value)
+      value.to_i
+    end
+
+    # Check if the specified value is valid in the context of this option.
+    # @param value the value to validate.
+    # @return [Boolean] true if valid.
+    def valid?(value)
+      if value.to_s.match(/^\d+$/).nil? || (value.to_i.negative? || value.to_i > 65_535)
+        return false
+      end
+
+      super
+    end
+  end
+end

data/lib/wpxf/core/opts/string_option.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Wpxf
+  # A string option.
+  class StringOption < Option
+    # @param value the value to normalize. If a string starting with
+    #   "file:" is specified, the path following it will be used to populate
+    #   the value from the contents of the file.
+    # @return [String] a normalized value to conform with the type that
+    #   the option is conveying.
+    def normalize(value)
+      match = value&.match(/^file:(.*)/)
+      if match
+        path = match[1]
+        begin
+          value = File.read(path)
+        rescue ::Errno::ENOENT, ::Errno::EISDIR
+          value = nil
+        end
+      end
+
+      value
+    end
+
+    # Check if the specified value is valid in the context of this option.
+    # @param value the value to validate.
+    # @return [Boolean] true if valid.
+    def valid?(value)
+      value = normalize(value)
+      super(value)
+    end
+  end
+end

data/lib/wpxf/core/output_emitters.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Wpxf
+  # Provides methods for emitting events that should output information
+  # to the user interface of the calling application.
+  module OutputEmitters
+    # Emit a successful operation event.
+    # @param message [String] the message to output.
+    # @param verbose [Boolean] the verbose level flag.
+    def emit_success(message, verbose = false)
+      event_emitter.emit(
+        event: :output,
+        verbose: verbose,
+        type: :success,
+        msg: message
+      )
+    end
+
+    # Emit a general info event.
+    # @param message [String] the message to output.
+    # @param verbose [Boolean] the verbose level flag.
+    def emit_info(message, verbose = false)
+      event_emitter.emit(
+        event: :output,
+        verbose: verbose,
+        type: :info,
+        msg: message
+      )
+    end
+
+    # Emit a warning event.
+    # @param message [String] the message to output.
+    # @param verbose [Boolean] the verbose level flag.
+    def emit_warning(message, verbose = false)
+      event_emitter.emit(
+        event: :output,
+        verbose: verbose,
+        type: :warning,
+        msg: message
+      )
+    end
+
+    # Emit an error event.
+    # @param message [String] the message to output.
+    # @param verbose [Boolean] the verbose level flag.
+    def emit_error(message, verbose = false)
+      event_emitter.emit(
+        event: :output,
+        verbose: verbose,
+        type: :error,
+        msg: message
+      )
+    end
+
+    # Emit an event containing tabular data.
+    # @param rows [Array] an array of hashes containing the row data.
+    # @param verbose [Boolean] the verbose level flag.
+    def emit_table(rows, verbose = false)
+      event_emitter.emit(
+        event: :output,
+        verbose: verbose,
+        type: :table,
+        rows: rows
+      )
+    end
+  end
+end

data/lib/wpxf/core/payload.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Wpxf
+  # The base class for all payloads.
+  class Payload
+    include Wpxf::Options
+
+    def initialize
+      super
+
+      register_options([
+        BooleanOption.new(
+          name: 'encode_payload',
+          desc: 'Encode the payload to avoid fingerprint detection',
+          required: true,
+          default: true
+        )
+      ])
+
+      self.queued_commands = []
+    end
+
+    # @return an encoded version of the payload.
+    def encoded
+      compiled = _raw_payload_with_random_var_names
+      if normalized_option_value('encode_payload')
+        "<?php eval(base64_decode('#{Base64.strict_encode64(compiled)}')); ?>"
+      else
+        "<?php #{compiled} ?>"
+      end
+    end
+
+    # Helper method to escape single quotes in a string.
+    # @param val [String] the string with quotes to escape.
+    # @return [String] the string with quotes escaped.
+    def escape_single_quotes(val)
+      val.gsub(/'/) { "\\'" }
+    end
+
+    # Generate a random variable name.
+    # @return [String] a random name beetween 5 and 20 alpha characters.
+    def random_var_name
+      Utility::Text.rand_alpha(rand(5..20))
+    end
+
+    # Generate a hash of variable names.
+    # @param keys [Array] an array of keys.
+    # @return [Hash] a hash containing a unique name for each key.
+    def generate_vars(keys)
+      vars = {}
+      keys.each do |key|
+        loop do
+          var_name = random_var_name
+          unless vars.value?(var_name)
+            vars[key] = random_var_name
+            break
+          end
+        end
+      end
+      vars
+    end
+
+    # Do any pre-exploit setup required by the payload.
+    # @param mod [Module] the module using the payload.
+    # @return [Boolean] true if successful.
+    def prepare(mod)
+      true if mod
+    end
+
+    # Run payload specific post-exploit procedures.
+    # @param mod [Module] the module using the payload.
+    # @return [Boolean] true if successful.
+    def post_exploit(mod)
+      true if mod
+    end
+
+    # Cleanup any allocated resource to the payload.
+    def cleanup
+      nil
+    end
+
+    # Run checks to raise warnings to the user of any issues or noteworthy
+    # points in regards to the payload being used with the current module.
+    # @param mod [Module] the module using the payload.
+    def check(mod)
+      nil
+    end
+
+    # @return [Hash] a hash of constants that should be injected at the
+    #   beginning of the payload.
+    def constants
+      {}
+    end
+
+    # @return [Array] an array of variable names that should be obfuscated in
+    #   the payload that is generated.
+    def obfuscated_variables
+      ['wpxf_disabled', 'wpxf_output', 'wpxf_exec', 'wpxf_cmd', 'wpxf_handle', 'wpxf_pipes', 'wpxf_fp']
+    end
+
+    # @return [String] the PHP preamble that should be included at the
+    #   start of all payloads.
+    def php_preamble
+      preamble = DataFile.new('php', 'preamble.php').php_content
+      constants.each do |k, v|
+        preamble += "  $#{k} = " + (v.is_a?(String) ? "'#{escape_single_quotes(v)}'" : v.to_s) + ";\n"
+      end
+      preamble
+    end
+
+    # Enqueue a command to be executed on the target system, if the
+    # payload supports queued commands.
+    # @param cmd [String] the command to execute when the payload is executed.
+    def enqueue_command(cmd)
+      queued_commands.push(cmd)
+    end
+
+    # @return the payload in its raw format.
+    attr_accessor :raw
+
+    # @return [Array] the commands queued to be executed on the target.
+    attr_accessor :queued_commands
+
+    private
+
+    def _raw_payload_with_random_var_names
+      payload = +"#{php_preamble} #{raw}"
+      vars = generate_vars(obfuscated_variables)
+      obfuscated_variables.each { |v| payload.gsub!("$#{v}", "$#{vars[v]}") }
+      payload
+    end
+  end
+end