CoCalc Logo Icon
StoreFeaturesDocsShareSupportNewsAboutSign UpSign In
rapid7

Real-time collaboration for Jupyter Notebooks, Linux Terminals, LaTeX, VS Code, R IDE, and more,
all in one place.

GitHub Repository: rapid7/metasploit-framework
 Path: blob/master/docs/metasploit-framework.wiki/Handling-Module-Failures-with-fail_with.md
Views: 11766

On this page

When a module fails, the fail_with method provides a standardized way to describe the reason for the failure. The first parameter depends on the cause of the failure.

Example uses

modules/exploits/osx/local/sudo_password_bypass.rb fails using Failure::NotVulnerable if the check method does not indicate that the target is vulnerable:

  if check != CheckCode::Vulnerable
    fail_with Failure::NotVulnerable, 'Target is not vulnerable'
  end

modules/exploits/multi/http/struts2_namespace_ognl.rb fails using the Failure::PayloadFailed if the target's response does not include a string indicating that the payload successfully executed. Alternatively, if the target responds with an HTTP error, the module invokes fail_with using the Failure::UnexpectedReply parameter:

  if r && r.headers && r.headers['Location'].split('/')[1] == success_string
    print_good("Payload successfully dropped and executed.")
  elsif r && r.headers['Location']
    vprint_error("RESPONSE: " + r.headers['Location'])
    fail_with(Failure::PayloadFailed, "Target did not successfully execute the request")
  elsif r && r.code == 400
    fail_with(Failure::UnexpectedReply, "Target reported an unspecified error while executing the payload")
  end

Comprehensive list of fail_with parameters

The following are currently used fail_with parameters and a brief description of common uses.

fail_with parameterReason for failure
Failure::BadConfigThe user-provided parameters are invalid and must be corrected.
Failure::DisconnectedThe target closed the connection forcibly.
Failure::NoAccessAn attempt to authenticate failed, likely due to invalid credentials.
Failure::NoneThe outcome for the module has already been met, for example a privilege escalation is already in an elevated context)
Failure::NoTargetThe specified TARGET or PAYLOAD variables are misconfigured or the target environment is unsupported.
Failure::NotFoundA preexisting file or resource on target is missing.
Failure::NotVulnerableThe target returned a response indicative of being patched or otherwise mitigated.
Failure::PayloadFailedA return code from payload execution indicates the payload did not execute or terminated unexpectedly.
Failure::TimeoutExpiredThe target did not respond to the connection request in a timely manner. Check RHOSTS and RPORT, then consider increasing WFSDelay.
Failure::UnexpectedReplyThe target responded in an entirely unexpected way, and may not be running the vulnerable service at all.
Failure::UnknownAn entirely unexpected exception occurred, and the target may not be running the expected services at all.
Failure::UnreachableThe host or service is not reachable, often indicated by a refused connection or ICMP "unreachable" message.