Land #5183, Improve developer experience for fail_with

lib/msf/core/exploit.rb

@@ -1218,10 +1218,31 @@ class Exploit < Msf::Module
   # Failure tracking
   ##
 
+  # Raises a Msf::Exploit::Failed exception. It overrides the fail_with method
+  # in lib/msf/core/module.rb
+  #
+  # @param reason [String] A constant from Msf::Module::Failure.
+  #                        If the reason does not come from there, then it will default to
+  #                        Msf::Module::Failure::Unknown.
+  # @param mssg [String] (Optional) A message about the failure.
+  # @raise [Msf::Exploit::Failed] A custom Msf::Exploit::Failed exception.
+  # @return [void]
+  # @see Msf::Module::Failure
+  # @see Msf::Module#fail_with
+  # @example
+  #   fail_with(Msf::Module::Failure::NoAccess, 'Unable to login to upload payload')
   def fail_with(reason,msg=nil)
+    # The reason being registered here will be used later on, so it's important we don't actually
+    # provide a made-up one.
+    allowed_values = Msf::Module::Failure.constants.collect {|e| Msf::Module::Failure.const_get(e)}
+    if allowed_values.include?(reason)
       self.fail_reason = reason
+    else
+      self.fail_reason = Msf::Module::Failure::Unknown
+    end
+
     self.fail_detail = msg
-    raise Msf::Exploit::Failed, (msg || "No reason given")
+    raise Msf::Exploit::Failed, (msg || "No failure message given")
   end
 
   def report_failure

lib/msf/core/module.rb

@@ -276,7 +276,18 @@ class Module
   end
 
   #
-  # Support fail_with for all module types, allow specific classes to override
+  # Raises a RuntimeError failure message. This is meant to be used for all non-exploits,
+  # and allows specific classes to override.
+  #
+  # @param reason [String] A reason about the failure.
+  # @param msg [String] (Optional) A message about the failure.
+  # @raise [RuntimeError]
+  # @return [void]
+  # @note If you are writing an exploit, you don't use this API. Instead, please refer to the
+  #       API documentation from lib/msf/core/exploit.rb.
+  # @see Msf::Exploit#fail_with
+  # @example
+  #   fail_with('No Access', 'Unable to login')
   #
   def fail_with(reason, msg=nil)
     raise RuntimeError, "#{reason.to_s}: #{msg}"