Improve validation and error handling for forgeticket module

lib/msf/core/data_store.rb

@@ -51,7 +51,11 @@ def []=(k, v)
     unless opt.nil?
       if opt.validate_on_assignment?
         unless opt.valid?(v, check_empty: false)
-          raise Msf::OptionValidateError.new(["Value '#{v}' is not valid for option '#{k}'"])
+          if self.options[k].examples.empty?
+            raise Msf::OptionValidateError, ["Value '#{v}' is not valid for option '#{k}'"]
+          else
+            raise Msf::OptionValidateError, ["Value '#{v}' is not valid for option '#{k}'. Example value: #{self.options[k].examples.join(', ')}"]
+          end
         end
         v = opt.normalize(v)
       end

lib/msf/core/data_store_with_fallbacks.rb

@@ -70,7 +70,11 @@ def []=(k, v)
     unless opt.nil?
       if opt.validate_on_assignment?
         unless opt.valid?(v, check_empty: false)
-          raise Msf::OptionValidateError.new(["Value '#{v}' is not valid for option '#{k}'"])
+          if self.options[k].examples.empty?
+            raise Msf::OptionValidateError, ["Value '#{v}' is not valid for option '#{k}'"]
+          else
+            raise Msf::OptionValidateError, ["Value '#{v}' is not valid for option '#{k}'. Example value: #{self.options[k].examples.join(', ')}"]
+          end
         end
         v = opt.normalize(v)
       end

lib/msf/core/opt_base.rb

@@ -25,13 +25,14 @@ class OptBase
     # also be a string as standin for the required description field.
     #
     def initialize(in_name, attrs = [],
-                   required: false, desc: nil, default: nil, conditions: [], enums: [], regex: nil, aliases: [], max_length: nil,
+                   required: false, desc: nil, default: nil, conditions: [], enums: [], regex: nil, examples: [], aliases: [], max_length: nil,
                    fallbacks: [])
       self.name     = in_name
       self.advanced = false
       self.evasion  = false
       self.aliases  = aliases
       self.max_length = max_length
+      self.examples = examples
       self.conditions = conditions
       self.fallbacks = fallbacks
 
@@ -225,6 +226,13 @@ def invalid_value_length?(value)
     # @return [Array<String>] the array of fallbacks
     attr_accessor :fallbacks
 
+    #
+    # Array of examples for this option.
+    # This will be used for error handling to give more verbosity to user via examples as part of error messages.
+    #
+    # @return [Array<String>] the array of examples
+    attr_accessor :examples
+
     #
     # The max length of the input value
     #

lib/msf/ui/formatter/option_validate_error.rb

@@ -12,16 +12,32 @@ class OptionValidateError
         def self.print_error(mod, error)
           raise ArgumentError, "invalid error type #{error.class}, expected ::Msf::OptionValidateError" unless error.is_a?(::Msf::OptionValidateError)
 
-          if error.reasons.empty?
-            mod.print_error("#{error.class} The following options failed to validate: #{error.options.join(', ')}")
-          else
-            mod.print_error("#{error.class} The following options failed to validate:")
-            error.options.sort.each do |option_name|
-              reasons = error.reasons[option_name]
-              if reasons
-                mod.print_error("Invalid option #{option_name}: #{reasons.join(', ')}")
+          error.options.each do |option|
+            # Assign module examples unless the value is not available within options as it wasn't created as an option object.
+            # example: value assigned directly to datastore without being created as an options object via `OptString.new` or similar.
+            # See spec/lib/msf/ui/console/command_dispatcher/exploit_spec.rb:279
+            option_examples = mod.options[option].nil? ? [] : mod.options[option].examples
+            option_value = mod.datastore[option]
+
+            if error.reasons.empty?
+              if option_examples.empty? && option_value.blank?
+                mod.print_error("#{error.class} The following option failed to validate: A value is required for option '#{option}'.")
+              elsif option_examples.empty?
+                mod.print_error("#{error.class} The following option failed to validate: Value '#{option_value}' is not valid for option '#{option}'.")
+              elsif option_value.blank?
+                mod.print_error("#{error.class} The following option failed to validate: A value is required for option '#{option}'. Example value: #{option_examples.join(', ')}")
               else
-                mod.print_error("Invalid option #{option_name}")
+                mod.print_error("#{error.class} The following option failed to validate: Value '#{option_value}' is not valid for option '#{option}'. Example value: #{option_examples.join(', ')}")
+              end
+            else
+              mod.print_error("#{error.class} The following options failed to validate:")
+              option.sort.each do |option_name|
+                reasons = error.reasons[option_name]
+                if reasons
+                  mod.print_error("Invalid option #{option_name}: #{reasons.join(', ')}")
+                else
+                  mod.print_error("Invalid option #{option_name}")
+                end
               end
             end
           end

modules/auxiliary/admin/kerberos/forge_ticket.rb

@@ -44,10 +44,11 @@ def initialize(info = {})
         OptInt.new('USER_RID', [ true, "The Domain User's relative identifier(RID)", Rex::Proto::Kerberos::Pac::DEFAULT_ADMIN_RID]),
         OptString.new('NTHASH', [ false, 'The krbtgt/service nthash' ]),
         OptString.new('AES_KEY', [ false, 'The krbtgt/service AES key' ]),
-        OptString.new('DOMAIN', [ true, 'The Domain (upper case) Ex: DEMO.LOCAL' ]),
-        OptString.new('DOMAIN_SID', [ true, 'The Domain SID, Ex: S-1-5-21-1755879683-3641577184-3486455962']),
-        OptString.new('SPN', [ false, 'The Service Principal Name (Only used for silver ticket)'], conditions: %w[ACTION == FORGE_SILVER]),
-        OptInt.new('DURATION', [ true, 'Duration of the ticket in days', 3650]),
+        OptString.new('DOMAIN', [ false, 'The Domain (upper case) Ex: DEMO.LOCAL' ]),
+        OptString.new('DOMAIN_SID', [ false, 'The Domain SID, Ex: S-1-5-21-1755879683-3641577184-3486455962'], regex: /^S-\d-\d+-(\d+-){1,14}\d+$/, examples: %w[S-1-5-21-1755879683-3641577184-3486455962 S-1-5-21-1180699209-877415012-3182924384-1004]),
+        OptString.new('SPN', [ false, 'The Service Principal Name (Only used for silver ticket) Ex: MSSqlSvc/host.domain.local:1434'], conditions: %w[ACTION == FORGE_SILVER], regex: %r{.*/.*}, examples: %w[MSSqlSvc/host.domain.local:1433 MSSqlSvc/host.domain.local:1434]),
+        OptInt.new('DURATION', [ false, 'Duration of the ticket in days', 3650]),
+        OptString.new('TICKET_PATH', [false, 'Path to the ticket you wish to debug'])
       ]
     )
     deregister_options('RHOSTS', 'RPORT', 'Timeout')

spec/lib/msf/ui/console/command_dispatcher/auxiliary_spec.rb

@@ -168,7 +168,7 @@ def cleanup
 
         subject.cmd_check
         expected_output = [
-          'Msf::OptionValidateError The following options failed to validate: RHOSTS'
+          "Msf::OptionValidateError The following option failed to validate: A value is required for option 'RHOSTS'."
         ]
 
         expect(@combined_output).to match_array(expected_output)
@@ -296,7 +296,7 @@ def cleanup
         current_mod.datastore['RHOSTS'] = ''
         subject.cmd_check
         expected_output = [
-          'Msf::OptionValidateError The following options failed to validate: RHOSTS'
+          "Msf::OptionValidateError The following option failed to validate: A value is required for option 'RHOSTS'."
         ]
 
         expect(@combined_output).to match_array(expected_output)
@@ -397,7 +397,7 @@ def cleanup
 
         subject.cmd_run
         expected_output = [
-          'Msf::OptionValidateError The following options failed to validate: RHOSTS'
+          "Msf::OptionValidateError The following option failed to validate: A value is required for option 'RHOSTS'."
         ]
 
         expect(@combined_output).to match_array(expected_output)
@@ -508,7 +508,7 @@ def cleanup
 
         subject.cmd_run
         expected_output = [
-          'Msf::OptionValidateError The following options failed to validate: RHOSTS'
+          "Msf::OptionValidateError The following option failed to validate: A value is required for option 'RHOSTS'."
         ]
 
         expect(@combined_output).to match_array(expected_output)
@@ -609,7 +609,7 @@ def cleanup
         current_mod.datastore['RHOSTS'] = ''
         subject.cmd_run
         expected_output = [
-          'Msf::OptionValidateError The following options failed to validate: RHOSTS'
+          "Msf::OptionValidateError The following option failed to validate: A value is required for option 'RHOSTS'."
         ]
 
         expect(@combined_output).to match_array(expected_output)

spec/lib/msf/ui/console/command_dispatcher/exploit_spec.rb

@@ -126,7 +126,7 @@ def set_default_payload(mod)
         current_mod.datastore['RHOSTS'] = ''
         subject.cmd_check
         expected_output = [
-          'Msf::OptionValidateError The following options failed to validate: RHOSTS'
+          "Msf::OptionValidateError The following option failed to validate: A value is required for option 'RHOSTS'."
         ]
 
         expect(@combined_output).to match_array(expected_output)
@@ -243,7 +243,7 @@ def set_default_payload(mod)
         current_mod.datastore['RHOSTS'] = nil
         subject.cmd_run
         expected_output = [
-          'Msf::OptionValidateError The following options failed to validate: RHOSTS'
+          "Msf::OptionValidateError The following option failed to validate: A value is required for option 'RHOSTS'."
         ]
 
         expect(@combined_output).to match_array(expected_output)
@@ -255,7 +255,7 @@ def set_default_payload(mod)
         current_mod.datastore['RHOSTS'] = ''
         subject.cmd_run
         expected_output = [
-          'Msf::OptionValidateError The following options failed to validate: RHOSTS'
+          "Msf::OptionValidateError The following option failed to validate: A value is required for option 'RHOSTS'."
         ]
 
         expect(@combined_output).to match_array(expected_output)
@@ -284,7 +284,7 @@ def set_default_payload(mod)
         subject.cmd_run
         expected_output = [
           'Exploit completed, but no session was created.',
-          'Msf::OptionValidateError The following options failed to validate: REQUIRED_PAYLOAD_OPTION'
+          "Msf::OptionValidateError The following option failed to validate: Value 'foo' is not valid for option 'REQUIRED_PAYLOAD_OPTION'."
         ]
 
         expect(@combined_output).to match_array(expected_output)