Pro API Methods Reference
In addition to the standard API, Metasploit Pro users can use the API to access to the commercial feature set. The Pro API methods can be used to manage a remote Metasploit Pro instance to do things like automate exploitation and reporting. While the Pro API includes a number of high-level APIs, the standard API methods are the best way to manage low-level primitives, such as sessions. In some cases, there is overlap between what a Pro API method provides and what can be found in the Standard API and the comments listed for the Pro API will make it clear which use case a specific method is designed to solve.
Pro General API
The Pro General API methods provide access to product version information, active projects, and user accounts.
pro.about
The pro.about method returns a hash containing basic information about the running Metasploit Pro instance.
Request Example:
[ "pro.about", "<token>" ]
Response Example:
{"product" => "Metasploit Pro", "version" => "4.11.0" }
pro.workspaces
The pro.workspaces method returns a list of all active Metasploit Pro projects. Although these are called products in the user interface, the underlying object is referred to as a workspace, and the terms workspace and project are used interchangeably throughout this guide.
Request Example:
[ "pro.workspaces", "<token>" ]
Response Example:
{ "Project1" => {
"created_at" => 1303706869,
"updated_at" => 1303706869,
"name" => "Project1",
"boundary" => "192.168.0.0/24",
"description" => "This is the local office network",
"owner" => "admin",
"limit_to_network" => false
}
}
pro.projects
The pro.projects method is an alias for the pro.workspaces method.
pro.workspace_add
The pro.workspace_add method adds a new workspace with the specified settings and returns a hash of that contains information on the newly created workspace.
Request Example:
[ "pro.workspace_add", "<token>", { "name" => "Project1" ]
Response Example:
{ "Project1" => {
"created_at" => 1303706869,
"updated_at" => 1303706869,
"name" => "Project1",
"boundary" => "192.168.0.0/24",
"description" => "This is the local office network",
"owner" => "admin",
"limit_to_network" => false
}
}
Hash keys that can be passed in to this method include:
- name: The unique name of the newly created workspace.
- boundary: The default network range for this project.
- description: A short amount of text describing this project.
- limit_to_network: A Boolean indicating whether to restrict operations to the boundary.
pro.project_add
The pro.project_add method is an alias for the pro.workspace_add method.
pro.workspace_del
The pro.workspace_del removes the workspace specified in the WorkspaceName parameter.
Request Example:
[ "pro.workspace_del", "<token>", "Project1" ]
Response Example:
{ "result" => "success" }
pro.project_del
The pro.project_del method is an alias for the pro.workspace_del method.
pro.users
The pro.users method returns a list of all configured user accounts in the Metasploit Pro instance.
Request Example:
[ "pro.users", "<token>" ]
Response Example:
{ "users" => {
"admin" => {
"username" => "admin",
"admin" => true,
"fullname" => "Joe Admin",
"email" => "joe_admin@example.org",
"phone" => "1-555-555-1212",
"company" => "Giant Widgets, Inc."
}
}
}
Pro License API
The Pro License API provides methods for registering and activating the Metasploit Pro product.
pro.register
The pro.register method accepts a product key as the only parameter, validates that the product key matches the correct format, and saves the product key internally. The pro.activate method must be used to fully activate the product. This method returns a hash indicating the result of the register call and the current state of the product.
Request Example:
[ "pro.register", "<token>", "ProductKey" ]
Response Example:
{
"result" => "success",
"product_key" => "XXXX-XXXX-XXXX-XXXX",
"product_serial" => "4dde9e80-c0b2cb0b-6d31b554",
"product_type" => "Metasploit Pro",
"product_version" => "4.11.0",
"product_revision" => "1",
"registered" => true,
"activated" => false,
"expiration" => 0,
"person" => "",
"organization" => "",
"email" => "",
"users" => 1,
"hardware" => true
}
pro.activate
The pro.activate method causes the Metasploit Pro installation to attempt an online activation with the previously registered product key and the specified ActivationOptions. If a 'product_key' element is provided in the ActivationOptions hash, this key will be registered prior to the activation process. In most cases, an empty hash can be specified in place of the ActivationOptions. If the Metasploit Pro instance does not have direct access to the internet, the ActivationOptions can be used to specify an internal HTTP proxy server. Proxy options can be specified in the 'proxy_host', 'proxy_port', 'proxy_user', and 'proxy_pass' elements of the ActivationOptions hash. Only standard HTTP proxies are supported. The response to the activate call will either contain a hash of license information, as the pro.register method does, or a hash containing a 'result' element with the value set to 'failure', and a second element, 'reason' indicating the reason for this failure. Note that every product key can only be activated a limited number of times, with the count determined by the license type. In the event that activation limit has been reached, Rapid7 Support must be contacted to reset the activation count.
Request Example:
[ "pro.activate", "<token>",
{
"proxy_host" => "1.2.3.4",
"proxy_port" => 80
}
]
Response Example:
{
"result" => "success",
"product_key" => "XXXX-XXXX-XXXX-XXXX",
"product_serial" => "4dde9e80-c0b2cb0b-6d31b554",
"product_type" => "Metasploit Pro",
"product_version" => "4.11.0",
"product_revision" => "1",
"registered" => true,
"activated" => true,
"expiration" => 1325376000,
"person" => "Licensed Person",
"organization" => "Licensed Organization",
"email" => "bob_admin@example.org",
"users" => 2,
"hardware" => true
}
pro.activate_offline
The pro.activate_offline method causes the Metasploit Pro installation to load a pre-generated offline activation file from the specified local filesystem path. Offline activation files are reserved for customers with network isolation requirements and are available through Rapid7 Support.
Request Example:
[ "pro.activate_offline", , "<token>", "/tmp/metasploit_pro_activation.zip" ]
Response Example:
{
"result" => "success",
"product_key" => "XXXX-XXXX-XXXX-XXXX",
"product_serial" => "4dde9e80-c0b2cb0b-6d31b554",
"product_type" => "Metasploit Pro",
"product_version" => "4.11.0",
"product_revision" => "1",
"registered" => true,
"activated" => true,
"expiration" => 1325376000,
"person" => "Licensed Person",
"organization" => "Licensed Organization",
"email" => "bob_admin@example.org",
"users" => 2,
"hardware" => true
}
pro.license
The pro.license method will return a hash indicating the current Metasploit Pro license.
Request Example:
[ "pro.license", "<token>"]
Response Example:
{
"result" => "success",
"product_key" => "XXXX-XXXX-XXXX-XXXX",
"product_serial" => "4dde9e80-c0b2cb0b-6d31b554",
"product_type" => "Metasploit Pro",
"product_version" => "4.11.0",
"product_revision" => "1",
"registered" => true,
"activated" => true,
"expiration" => 1325376000,
"person" => "Licensed Person",
"organization" => "Licensed Organization",
"email" => "bob_admin@example.org",
"users" => 2,
"hardware" => true
}
pro.revert_license
The pro.revert_license method attempts to switch to the last successfully activated product license before the current one. Only one backup license copy is kept and this method does nothing if there is no backup license available when it is called. The return value is identical to the pro.license call in that it provides the newly chosen license information as a hash. This method is used to temporarily use a license that may provide more users or other capabilities and then fallback to the original license when that temporary license expires.
Request Example:
[ "pro.license", "<token>"]
Response Example:
{
"result" => "success",
"product_key" => "XXXX-XXXX-XXXX-XXXX",
"product_serial" => "4dde9e80-c0b2cb0b-6d31b554",
"product_type" => "Metasploit Pro",
"product_version" => "4.11.0",
"product_revision" => "1",
"registered" => true,
"activated" => true,
"expiration" => 1325376000,
"person" => "Licensed Person",
"organization" => "Licensed Organization",
"email" => "bob_admin@example.org",
"users" => 5,
"hardware" => false
}
Pro Updates API
The Pro Updates API provides the ability to check for, download, and apply the latest Metasploit Pro updates. This API also includes a method for restarting the Metasploit Pro services.
pro.update_available
The pro.update_available method provides the ability to check for available updates to the Metasploit Pro instance. The UpdateCheckOptions hash can either be empty or include the 'proxy_host', 'proxy_port', 'proxy_user', and 'proxy_pass' elements to use a HTTP proxy for the check. The return value includes a hash that indicates whether an update is available, what the version number of this update is, and a description of what the update contains. Note that the description may contain HTML formatting.
Request Example:
[ "pro.update_available", "<token>", { } ]
Response Example:
{
"status" => "success",
"result" => "update",
"current" => "1",
"version" => "20120125000001",
"info" => "This updates adds new features and fixes…"
}
pro.update_install
The pro.update_install method provides the ability to install an update package by name, specified through the 'version' element of the InstallOptions hash. The 'proxy_host', 'proxy_port', 'proxy_user', and 'proxy_pass' elements can be supplied in this hash to indicate that a HTTP proxy should be used. This method returns a hash indicating whether the update was started successfully and what the current status of the installation is. The download and installation process is completed as a single step as the progress can be tracked through calls to the pro.update_status method. Note that the pro.restart_service method must be called to finalize the update.
Request Example:
[ "pro.update_install", "<token>", { "version" => "20120125000001" } ]
Response Example:
{
"status" => "success",
"result" => "Downloading",
"error" => ""
}
pro.update_install_offline
The pro.update_install_offline method provides the ability install an update package from a local filesystem. Customers that require offline updates should contact Rapid7 Support to be notified of the download location of each update package. The status of the offline package installation can be monitored by calling the pro.update_status method. Note that the pro.restart_service method must be called to finalize the update.
Request Example:
[ "pro.update_install_offline", "<token>", "/tmp/metasploit_pro_update.zip" ]
Response Example:
{
"status" => "success",
"result" => "Installing",
"error" => ""
}
pro.update_status
The pro.update_status method returns a hash indicating the current status of the update installation process. If the update is still being retrieved from the server, the current progress of the download will be returned in the 'download_total', 'download_done', and 'download_pcnt' elements.
Request Example:
[ "pro.update_status", "<token>" ]
Response Example:
{
"status" => "success",
"result" => "Downloading",
"error" => "",
"download_total" => "1000000",
"download_done" => "100000",
"download_pcnt" => "10"
}
pro.update_stop
The pro.update_stop method forcibly stops any existing update process, whether it is downloading the update package or installing the contents.
Request Example:
[ "pro.update_stop", "<token>" ]
Response Example:
{ "status" => "success" }
pro.restart_service
The pro.restart_service method causes the Metasploit Pro RPC Service (prosvc) and the Metasploit Pro Web Service to restart. This is necessary to complete the installation of an update package.
Request Example:
[ "pro.restart_service", "<token>" ]
Response Example:
{ "status" => "success" }
Pro Task API
Metasploit Pro uses tasks to manage background jobs initiated by the user through the web interface. Scanning, exploiting, bruteforcing, importing, and reporting are all handled through tasks. The Pro task API provides methods for enumerating active tasks, stopping tasks, and retrieving the raw log file for a given task.
pro.task_list
The pro.task_list method returns a hash of active tasks.
Request Example:
[ "pro.task_list", "<token>" ]
Response Example:
{ "108" =>
{
"status" => "running",
"error" => "",
"created_at" => 1306792667,
"progress" => 25,
"description" => "Launching",
"info" => "#1 ICONICS WebHMI ActiveX Buffer Overflow",
"workspace" => "Branch Office",
"username" => "admin",
"result" => "",
"path" => "tasks/task_pro.single_108.txt",
"size" => 425
}
}
pro.task_status
The pro.task_status method returns the current status of a given task.
Request Example:
[ "pro.task_status", "<token>", "108" ]
Response Example:
{ "108" =>
{
"status" => "running",
"error" => "",
"created_at" => 1306792667,
"progress" => 25,
"description" => "Launching",
"info" => "#1 ICONICS WebHMI ActiveX Buffer Overflow",
"workspace" => "Branch Office",
"username" => "admin",
"result" => "",
"path" => "tasks/task_pro.single_108.txt",
"size" => 425
}
}
pro.task_stop
The pro.task_stop method terminates the task specified in the task ID parameter.
Request Example:
[ "pro.task_status", "<token>", "108" ]
Response Example:
{ "task" => "108", "status" => "stopped" }
pro.task_log
The pro.task_log method returns the status and log data for the task specified in the task ID parameter.
Request Example:
[ "pro.task_log", "<token>", "108" ]
Response Example:
{
"status" => "running",
"error" => "",
"created_at" => 1306792667,
"progress" => 25,
"description" => "Launching",
"info" => "#1 ICONICS WebHMI ActiveX Buffer Overflow",
"workspace" => "Branch Office",
"username" => "admin",
"result" => "",
"path" => "tasks/task_pro.single_108.txt",
"size" => 425,
"log" => "<425 bytes of output data>"
}
pro.task_delete_log
The pro.task_delete_log method deletes the associated log file for a specific task.
Request Example:
[ "pro.task_delete_log", "<token>", "108" ]
Response Example:
{ "status" => "succcess" }
Pro Feature API
The Pro Feature API includes methods that provide access to many of the top-level features in the Metasploit Pro user interface. These methods include launching discovery scans, importing data from other tools, launching automated exploits, running bruteforce attacks, and generating reports. Since these methods are designed to expose all of the functionality available through the user interface, they take a large number of parameters.
pro.start_discover
The pro.start_discover method is the backend method that drives the scan action within the Metasploit Pro user interface. This action launches a discovery scan against a range of IP addresses, identifying active hosts, open services, and extracting information from the discovered services. The resulting data is stored in the backend database. The pro.start_discover method takes a large number of options in the form of a single hash parameter and returns a task ID that can be monitored using the Pro task API.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Description |
|---|---|---|---|
| ips | Yes | [ "192.168.0.0/24" ] | This option determines what IP addresses and IP ranges to include in the scan. This option is an array of IP addresses and/or IP ranges. |
| workspace | Yes | Project1 | This option indicates the project name that this scan should be part of. This correlates to the full name of the project as listed in the user interface. |
| username | No | admin | This option specifies which Pro username this scan task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_BLACKLIST_HOSTS | No | 192.168.0.1 | This option determines what addresses within the ips range should be excluded from the scan. Multiple entries should be separated by spaces. |
| DS_PORTSCAN_SPEED | No | Insane | This option should be one of Paranoid, Sneaky, Polite, Normal, Aggressive or Insane. These correspond to the common options in the Nmap security scanner and progressively increase the speed of the scan. Insane is actually a reasonable setting for a local Ethernet network. |
| DS_PORTS_EXTRA | No | 1-65535 | This option allows additional TCP ports to be included in the scan. Ports are specified in Nmap format (ranges separated by –'s and commas between ranges). |
| DS_PORTS_BLACKLIST | No | 9100, 1723 | This option defines a list of ports that should always be excluded. |
| DS_PORTS_CUSTOM | No | 1-1024 | This option overrides the built-in port list (derived from the loaded exploit modules) and only scans the ports listed. |
| DS_PORTSCAN_TIMEOUT | No | 300 | This option sets the maximum amount of time, in seconds, that the scanner should spend on a single host. If you increase the range of ports to scan with another option, this should also be increased. 300 seconds (5 minutes) is a reasonable setting even for heavily filtered networks. |
| DS_PORTSCAN_SOURCE_PORT | No | 53 | This option configures the source port for the scan. Setting this to 80, 53, or 20 can often bypass poorly configured firewalls and access lists. |
| DS_CustomNmap | No | -sF -O | This option can be used to completely override the Nmap command line normally used by Pro and replace it (excluding hosts and ports). |
| DS_UDP_PROBES | No | false | This option can be used to disable UDP service probes by setting it to false (it is enabled otherwise). |
| DS_FINGER_USERS | No | false | This option can be used to disable the finger service (79/tcp) automated username harvesting that occurs by default when enabled. |
| DS_SNMP_SCAN | No | false | This option can be used to disable the SNMP scanner that is normally included in the scan by default. This scanner attempts to guess a small number of common SNMP communities for each targeted host. |
| DS_IDENTIFY_SERVICES | No | false | This option can be used to disable the service identification phase that is normally triggered when one or services are not identified in the first pass. |
| DS_SMBUser | No | Administrator | This option can be used to extract additional information from SMB services if a valid username and password is supplied. |
| DS_SMBPass | No | S3cr3t | This option defines the password that corresponds to the DS_SMBUser option. |
| DS_SMBDomain | No | CORP | This option defines the domain that corresponds to the DS_SMBUser option. |
| DS_DRY_RUN | No | true | This option, when set to true, will cause the task to show what it would do, but not actually send any network traffic. |
| DS_SINGLE_SCAN | No | true | This option, when set to true, will scan each host sequentially instead of multiple hosts at once. Useful for reducing packet loss on especially poor networks. |
| DS_FAST_DETECT | No | true | This option, when set to true, will limit the scan to a small set of TCP ports. |
A sample request to use the default settings to scan 192.168.0.0/24 would look like:
[ "pro.start_discover", "<token>",
{
"ips" => [ "192.168.0.0/24" ],
"workspace" => "Project1"
}
]
If we change the same request to scan all 65535 TCP ports, it would look like:
[ "pro.start_discover", "<token>",
{
"ips" => [ "192.168.0.0/24" ],
"workspace" => "Project1",
"DS_PORTS_CUSTOM" => "1-65535"
}
]
Response Example:
{ "task_id" => "109" }
pro.start_import
The pro.start_import method is what drives the import action within the Metasploit Pro user interface. This method assumes that a file is already on the local disk (relative to the Metasploit Pro system) or that a Nexpose Console has been configured with one or more active sites. To import arbitrary data without having to upload the file to the server first, please see the pro.import_data method instead. The pro.start_import method takes a large number of options in the form of a single hash parameter and returns a task ID that can be monitored using the Pro task API.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Description |
|---|---|---|---|
| workspace | Yes | Project1 | This option indicates the project name that this import should be part of. This correlates to the full name of the project as listed in the user interface. |
| username | No | admin | This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_PATH | No | /tmp/nexpose.xml | This option specifies the server-local file path to import. If you are calling this API from a remote system, it makes more sense to call the pro.import_data API instead. |
| DS_BLACKLIST_HOSTS | No | 192.168.0.1 | This option determines what addresses should be excluded from the import. Multiple entries should be separated by spaces. |
| DS_PRESERVE_HOSTS | No | true | This option can be used to prevent modifications to existing hosts during an import. |
| DS_REMOVE_FILE | No | true | This option tells the service to delete the file specified as DS_PATH after importing it. |
| DS_ImportTags | No | false | This option indicates whether to import tags as well as host data when processing a Metasploit Pro export file. |
| DS_NEXPOSE_CONSOLE | No | EnterpriseScanner | This option, when combined with the DS_NEXPOSE_SITE parameter, can be used to import data directly from a per-configured Nexpose Console. Leave this blank to import from a file path. |
| DS_NEXPOSE_SITE | No | Finance | This option, when combined with the DS_NEXPOSE_CONSOLE parameter, can be used to import data directly from an existing Nexpose site. Leave this blank to import from a file path. |
A sample request to import a Nexpose Export XML would look like:
Request Example:
[ "pro.start_import", "<token>",
{
"workspace" => "Project1",
"DS_PATH" => "/tmp/nexpose.xml"
}
]
Response Example:
{ "task_id" => "109" }
pro.start_import_creds
The pro.start_import_creds method is used to import credentials (users, passwords, hashes, and keys). This method assumes that a file is already on the local disk (relative to the Metasploit Pro system. The pro.start_import_creds method takes a large number of options in the form of a single hash parameter and returns a task ID that can be monitored using the Pro task API.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Description |
|---|---|---|---|
| workspace | Yes | Project1 | This option indicates the project name that this import should be part of. This correlates to the full name of the project as listed in the user interface. |
| username | No | admin | This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_IMPORT_PATH | No | /tmp/wordlist.txt | This option specifies the server-local file path to import. |
| DS_FTYPE | No | pass | This option determines tells the service that kind of import this is. It should be one of "userpass", "user", "pass", pwdump", or "ssh_keys". |
| DS_NAME | No | common_passwords | This option indicates a unique name of this imported data set. |
| DS_DESC | No | Common passwords | This option provides a user-visible description of this imported data |
| DS_ORIG_FILE_NAME | No | my_passwords.txt | This option indicates the original file name of the credential data. |
| DS_REMOVE_FILE | No | true | This option indicates whether the service should delete the local file after importing it. |
Request Example:
[ "pro.start_import_creds", "<token>",
{
"workspace" => "Project1",
"DS_IMPORT_PATH" => "/tmp/pwdump.txt",
"DS_FTYPE" => "pwdump",
"DS_NAME" => "domain_dump",
"DS_DESC" => "Password hashes from the DC",
"DS_REMOVE_FILE" => false
}
]
Response Example:
{ "task_id" => "109" }
pro.start_nexpose
The pro.start_nexpose method is used to launch Nexpose scans directly through the Metasploit Pro service. The pro.start_nexpose method takes a large number of options in the form of a single hash parameter and returns a task ID that can be monitored using the Pro task API.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Description |
|---|---|---|---|
| workspace | Yes | Project1 | This option indicates the project name that this import should be part of. This correlates to the full name of the project as listed in the user interface. |
| username | No | admin | This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_WHITELIST_HOSTS | Yes | 192.168.0.0/24 | This option indicates the project name that this import should be part of. This correlates to the full name of the project as listed in the user interface. |
| DS_BLACKLIST_HOSTS | No | 192.168.0.3 | This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_NEXPOSE_HOST | No | 127.0.0.1 | This option specifies the list of addresses and network ranges to scan. |
| DS_NEXPOSE_PORT | No | 3780 | This option specifies the port of the Nexpose Console. |
| DS_NEXPOSE_USER | No | nxadmin | This option specifies a valid username for the Nexpose Console. |
| nexpose_pass | No | S3cr3t | This option specifies the password for the user account. It uses a different syntax to prevent the password from being logged in the Event table. |
| DS_SCAN_TEMPLATE | No | pentest-audit | The option specifies the scan template to use. The common templates include: pentest-audit full-audit, exhaustive-audit, discovery, aggressive-discovery, and dos-audit. |
Request Example:
The following shows an example of a request to start a new Nexpose scan:
[ "pro.start_nexpose", "<token>",
{
"workspace" => "Project1",
"DS_WHITELIST_HOSTS" => "192.168.0.0/24",
"DS_NEXPOSE_HOST" => "127.0.0.1",
"DS_NEXPOSE_PORT" => 3780,
"DS_NEXPOSE_USER" => "nxadmin",
"nexpose_pass" => "s3cr3t",
"DS_SCAN_TEMPLATE" => "pentest-audit"
}
]
Response Example:
{ "task_id" => "109" }
pro.start_bruteforce
The pro.start_bruteforce method is used to launch a new Bruteforce task. The pro.start_bruteforce method takes a large number of options in the form of a single hash parameter and returns a task ID that can be monitored using the Pro task API. The bruteforce task requires hosts and services to be present first via scan, import, or Nexpose.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Description |
|---|---|---|---|
| workspace | Yes | Project1 | This option indicates the project name that this import should be part of. This correlates to the full name of the project as listed in the user interface. |
| username | No | admin | This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_WHITELIST_HOSTS | Yes | 192.168.0.0/24 | This option specifies the list of addresses and network ranges to test. |
| DS_BLACKLIST_HOSTS | No | 192.168.0.3 | This option specifies the list of addresses and network ranges to exclude from the target range. |
| DS_STOP_ON_SUCCESS | Yes | true | This option indicates whether the bruteforce attack should continue testing a service after cracking the first account. |
| DS_VERBOSE | No | true | This option indicates how much diagnostic information is shown during bruteforce. |
| DS_INCLUDE_KNOWN | Yes | true | This option indicates whether the bruteforce attack should use credentials that were previously found. |
| DS_DRY_RUN | No | true | This option indicates whether to skip the bruteforce attack and just show what usernames and passwords would have been tested. |
| DS_BRUTEFORCE_SCOPE | Yes | normal | This option indicates what bruteforce mode to operate in. This is one of the following settings: quick, defaults, normal, deep, known, imported, or 50k. |
| DS_BRUTEFORCE_SPEED | Yes | turbo | This option specifies how fast to conduct the bruteforce attack. This is one of the following settings: Glacial, Slow, Stealthy, Normal, Fast, or Turbo. |
| DS_BRUTEFORCE_SERVICES | Yes | SSH | This option specifies what protocols to test. Multiple protocols should be separated by spaces. Available protocols include: SMB, Postgres, DB2, MySQL, MSSQL, Oracle, HTTP, HTTPS, SSH, Telnet, FTP, EXEC, LOGIN, SHELL, VNC, and SNMP. |
| DS_BRUTEFORCE_GETSESSION | Yes | true | This option specifies whether to use cracked accounts to gain access to the tested systems. |
| DS_QUICKMODE_CREDS | No | Username Password\n | This option specifies additional credentials to use as part of the bruteforce attack. The syntax is "username" followed by a space, following by the "password", and a new line "\n" for each credential. |
| DS_PAYLOAD_METHOD | No | auto | This option determines what connection method to use when opening sessions, it can be one of auto, reverse, or bind. |
| DS_PAYLOAD_TYPE | No | meterpreter | This option determines whether to prefer meterpreter or shell session types. |
| DS_PAYLOAD_PORTS | No | 4000-5000 | This option specifies the port range to use for bind and reverse connections. |
| DS_SMB_DOMAINS | No | Domain1 | This option specifies a list of domains, separated by spaces, to use when brute forcing protocols that speak NTLM. |
| DS_PRESERVE_DOMAINS | No | true | This option specifies whether to use the original domain name with each username and password previously identified. |
| DS_CRED_FILE_IDS | No | 34 | This option specifies what imported credential files to include in this bruteforce task. This requires knowledge of the imported credential file IDs. |
| DS_MAXGUESSESPERSERVICE | No | 100 | This option specifies the maximum number of authentication attempts per service, it defaults to 0 which is unlimited. |
| DS_MAXMINUTESPERSERVICE | No | 60 | This option specifies the maximum amount of time in minutes to spend on each service, it defaults to 0 which is unlimited. |
| DS_MAXGUESSESPERUSER | No | 3 | This option specifies the maximum number of guesses to try for each unique user account, it defaults to 0 which is unlimited. |
| DS_MAXMINUTESOVERALL | No | 30 | This option specifies the maximum amount of time to run for the entire bruteforce task, it defaults to 0 which is unlimited. |
| DS_MAXGUESSESOVERALL | No | 1000 | This option specifies the maximum number of guesses to try overall, it defaults to 0 which is unlimited. |
| DS_BRUTEFORCE_SKIP_BLANK_PASSWORDS | No | true | This option specifies whether to skip blank passwords entirely, it defaults to false. |
| DS_BRUTEFORCE_SKIP_MACHINE_NAMES | No | true | This option specifies whether to skip machine names as a password seed source for the wordlist, it defaults to false. |
| DS_BRUTEFORCE_SKIP_BUILTIN_WINDOWS_ACCOUNTS | No | true | This option specifies whether to skip builtin Windows accounts that typically do not have weak passwords (service accounts). |
| DS_BRUTEFORCE_SKIP_BLANK_BUILTIN_UNIX_ACCOUNTS | No | true | This options specifies whether to skip built-in Unix accounts that typically do have weak passwords (service accounts). |
| DS_BRUTEFORCE_RECOMBINE_CREDS | No | true | This option specifies whether to recombine known, imported, and additional credentials to create the wordlists. |
| DS_MSSQL_WINDOWS_AUTH | No | true | This option indicates that MSSQL Server authentication should use NTLM instead of Standard mode. This defaults to false. |
A sample request to start a new Bruteforce task:
Request Example:
[ "pro.start_bruteforce", "<token>",
{
"workspace" => "Project1",
"DS_WHITELIST_HOSTS" => "192.168.0.0/24",
"DS_BRUTEFORCE_SCOPE" => "defaults",
"DS_BRUTEFORCE_SERVICES" => "SSH HTTP",
"DS_BRUTEFORCE_SPEED" => "TURBO",
"DS_INCLUDE_KNOWN" => normal,
"DS_BRUTEFORCE_GETSESSION" => true
}
]
Response Example:
{ "task_id" => "109" }
pro.start_exploit
The pro.start_exploit method is what drives the exploit action within the Metasploit Pro user interface. The pro.start_exploit method takes a large number of options in the form of a single hash parameter and returns a task ID that can be monitored using the Pro task API. The exploit action requires hosts, services, and optionally vulnerabilities to be present before it can be used. This can be accomplished using the scan, import, and Nexpose actions first.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Description |
|---|---|---|---|
| workspace | Yes | Project1 | This option indicates the project name that this import should be part of. This correlates to the full name of the project as listed in the user interface. |
| username | No | admin | This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_WHITELIST_HOSTS | Yes | 192.168.0.0/24 | This option indicates the project name that this import should be part of. This correlates to the full name of the project as listed in the user interface. |
| DS_BLACKLIST_HOSTS | No | 192.168.0.3 | This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_WHITELIST_PORTS | No | 1-1000 | This option specifies what ports are allowed during the exploitation task. This defaults to 1-65535 (all ports). |
| DS_BLACKLIST_PORTS | No | 80,443 | This option determines what addresses should be excluded from the test. Multiple entries should be separated by spaces. This option specifies a list of ports to avoid during the exploitation task. |
| DS_MinimumRank | Yes | great | This option specifies the minimum reliability level of exploits to include the exploitation task. This is one of the following settings, in order of increasing liability: low, average, normal, good, great, or excellent. This option indicates how many exploits to run in parallel. The default is 5 and a reasonable maximum is 10 due to how resources are allocated. This option sets the maximum amount of time any individual exploit can run. Setting this below 2 minutes can prevent some exploits from working. This option determines whether to attempt to avoid exploiting systems that already have an active session. The default is true. This option specifies whether to avoid running exploits against systems that are known to fall over during common testing. This is based on an internal blacklist and results in printers and many network devices being skipped automatically by the exploit engine. This setting defaults to true. This option instructs the exploit engine to use OS information when matching exploits to hosts. Exploits will only be skipped when the confidence of the OS signature is high. The default for this option is true. |
| DS_EXPLOIT_SPEED | Yes | 5 | This option indicates how many exploits to run in parallel. The default is 5 and a reasonable maximum is 10 due to how resources are allocated. |
| DS_EXPLOIT_TIMEOUT | No | 5 | This option sets the maximum amount of time any individual exploit can run. Setting this below 2 minutes can prevent some exploits from working. |
| DS_LimitSessions | No | false | This option determines whether to attempt to avoid exploiting systems that already have an active session. The default is true. |
| DS_IgnoreFragileDevices | No | false | This option specifies whether to avoid running exploits against systems that are known to fall over during common testing. This is based on an internal blacklist and results in printers and many network devices being skipped automatically by the exploit engine. This setting defaults to true. |
| DS_FilterByOS | No | false | This option instructs the exploit engine to use OS information when matching exploits to hosts. Exploits will only be skipped when the confidence of the OS signature is high. The default for this option is true. |
| DS_OnlyMatch | No | false | This option, when set to true, instructions to exploit engine to match exploits but not actually run them. The default setting is false. |
| DS_MATCH_VULNS | Yes | false | This option instructs the exploit engine to match exploits based on vulnerability references. This setting defaults to true. |
| DS_MATCH_PORTS | Yes | false | This option instructs the exploit engine to match exploits based on open services. This setting defaults to true. |
| DS_PAYLOAD_METHOD | No | auto | This option determines what connection method to use when opening sessions, it can be one of auto, reverse, or bind. |
| DS_PAYLOAD_TYPE | No | meterpreter | This option determines whether to prefer meterpreter or shell session types. |
| DS_PAYLOAD_PORTS | No | 4000-5000 | This option specifies the port range to use for bind and reverse connections. |
| DS_EVASION_LEVEL_TCP | No | 1 | This option specifies a transport-level evasion level between 0 and 3. |
| DS_EVASION_LEVEL_APP | No | 1 | This option specifies an application-level evasion level between 0 and 3. |
| DS_ModuleFilter | No | exploit/windows/smb/psexec | This option specifies a whitelist of module names that are allowed to be run, separated by commas. By default all modules are considered that meet the other criteria. |
A sample request to run exploits across a network range:
Request Example:
[ "pro.start_exploit", "<token>",
{
"workspace" => "Project1",
"DS_WHITELIST_HOSTS" => "192.168.0.0/24",
"DS_MinimumRank" => "great",
"DS_EXPLOIT_SPEED" => 5,
"DS_EXPLOIT_TIMEOUT" => 2,
"DS_LimitSessions" => true,
"DS_MATCH_VULNS" => true,
"DS_MATCH_PORTS" => true
}
]
Response Example:
{ "task_id" => "109" }
pro.start_cleanup
The pro.start_cleanup method is what drives the Cleanup action within the Metasploit Pro user interface. The pro.start_cleanup method takes a number of options in the form of a single hash parameter and returns a task ID that can be monitored using the Pro task API.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Description |
|---|---|---|---|
| workspace | Yes | Project1 | This option indicates the project name that this import should be part of. This correlates to the full name of the project as listed in the user interface. |
| username | No | admin | This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_SESSIONS | Yes | 1 2 3 | This option specifies a list of session IDs to close. These are RPC service session IDs. |
| DS_DBSESSIONS | No | 1001 1002 | This option specifies a list of session IDs by their database identifiers. |
Request Example:
[ "pro.start_cleanup", "<token>",
{
"workspace" => "Project1",
"DS_SESSIONS" => "100 101 102",
}
]
Response Example:
{ "task_id" => "109" }
pro.start_collect
The pro.start_collect method is what drives the Collect action within the Metasploit Pro user interface. The pro.start_collect method takes a number of options in the form of a single Response: parameter and returns a task ID that can be monitored using the Pro task API.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Description |
|---|---|---|---|
| workspace | Yes | Project1 | This option indicates the project name that this import should be part of. This correlates to the full name of the project as listed in the user interface. |
| username | No | admin | This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used. |
| DS_SESSIONS | Yes | 1 2 3 | This option specifies a list of session IDs to close. These are RPC service session IDs. |
| DS_COLLECT_SYSINFO | Yes | true | This option indicates whether basic system information should be acquired. |
| DS_COLLECT_PASSWD | Yes | true | This option indicates whether password and hashes should be acquired. |
| DS_COLLECT_SCREENSHOTS | Yes | true | This option indicates whether screenshots should be taken. |
| DS_COLLECT_SSH | Yes | true | This option indicates whether ssh key information should be acquired. |
| DS_COLLECT_FILES | Yes | true | This option indicates whether specific files matching a pattern should be acquired. |
| DS_COLLECT_FILES_PATTERN | No | *.doc | This option sets the file pattern to automatically download. |
| DS_COLLECT_FILES_COUNT | No | 100 | This option sets the maximum number of files to download per session. |
| DS_COLLECT_FILES_SIZE | No | 40 | This option sets the maximum file size to download per file, in kilobytes. |
Request Example:
[ "pro.start_collect", "<token>",
{
"workspace" => "Project1",
"DS_SESSIONS" => "100 101 102",
"DS_COLLECT_SYSINFO" => true,
"DS_COLLECT_PASSWD" => true,
"DS_COLLECT_SCREENSHOTS" => true,
"DS_COLLECT_SSH" => true,
"DS_COLLECT_FILES" => false
}
]
Response Example:
{ "task_id" => "109" }
pro.start_report
The pro.start_report method drives the report actions within the Metasploit Pro user interface. The pro.start_report method takes a number of options in the form of a single hash parameter and returns a task ID that can be monitored using the Pro task API.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Type | Description |
|---|---|---|---|---|
| workspace_name | Yes | Project1 | String | The name of the workspace that you want to use to gather data for the report. |
| name | Yes | reportABC | String | The name the report will be saved as. |
| report_type | Yes | audit | String | The type of report you want to generate. The report_type can be activity, audit, credentials, collected_evidence, compromised_hosts, custom, fisma, mm_auth, mm_pnd, mm_segment, pci, services, social_engineering, or webapp_assessment. |
| report_template | Yes | /path/to/custom.jrxml | String | The template used for custom reports. To specify a template, enter the full file path to the custom Jasper JRXML template. Do not use this field unless the report_type is set to 'custom'. |
| created_by: | Yes | admin | String | The username to which the report should be attributed. |
| file_formats | Yes | Array | The file formats you want generate for the report. Available file formats include PDF, HTML, RTF, XML, and Word; however, the file formats that are available vary for each report type. The Activity, Web App Assessment, FISMA, and PCI reports do not include the Word format. Only the PCI and FISMA reports support the XML format. |
|
| email_recipients | No | joe@mail.com, jon@mail.com | String | The addresses to which the report should be emailed. Addresses can be separated with comma, semicolon, newlines, or spaces. |
| mask_credentials | No | true | Boolean | Enables or disables the masking of credentials in a report. Set this option to true or false. |
| included_addresses | No | 192.168.1.0/24 | String | Includes the specified hosts in the report. |
| excluded_addresses | No | 192.168.1.1 | String | Excludes the specified hosts from the report. |
| logo_path | No | String | Adds a custom logo to the report's cover page. You must specify the full path to the image. The image must have agif, png, jpg, or jpeg file type. |
|
| se_campaign_id | No | 1 | Integer | The ID of the social engineering campaign you want to use to gather data for the report. Only use this field for Social Engineering reports. |
| sections | No | cover, project_summary, task_details | Array | Identifies the sections you want to include in the report. Only the specified sections will be included. Otherwise, if you do not specify this option, all sections will be included. To see the section names for a report, use the pro.list_report_types method. |
| usernames_reported | No | admin1, admin 2 | String | Includes a list of active users in the Executive summary section of the report. You must provide a comma separated list of user names. |
Request Example:
[ "pro.report_start", "<token>",
{
workspace: workspace_name,
name: "default_#{Time.now.to_i}",
report_type: :audit,
created_by: 'whoareyou',
file_formats: [:pdf]
}
]
pro.report_list
The pro.report_list method displays all reports that have been generated in the specified workspace.
pro.list_report_types
The pro.list_report_types method displays all the report types that can be generated in a workspace.
pro.report_download
The pro.report_download method downloads the specified report and its artifacts.
pro.report_artifact_download
The pro.report_artifact_download method downloads the specified report artifact.
pro.start_export
The pro.start_export method drives the export actions within the Metasploit Pro user interface.
The individual options within the hash are defined in the table below.
| Option | Required | Example | Type | Description |
|---|---|---|---|---|
| workspace_name | Yes | project1 | String | The name of the workspace that you want to export data from. |
| export_type | Yes | |||
| created_by: | Yes | admin | String | The username to which the export should be attributed. |
| name | No | reportABC | String | The name the export file will be saved as. |
| mask_credentials | No | true | Boolean | Enables or disables the masking of credentials in an export. Set this option to true or false. |
| included_addresses | No | 192.168.1.0/24 | String | Includes the specified hosts in the export. |
| excluded_addresses | No | 192.168.1.1 | String | Excludes the specified hosts from the export. |
pro.export_list
The pro.export_list method displays all exports that have been generated in the specified workspace.
pro.export_download
The pro.export_download method downloads the specified export file.
Pro Import API
pro.import_data
The pro.import_data method starts a new import task with the supplied data.
Request Example:
[ "pro.import_data", "<token>", "Project1", "<DATA>",
{
'blacklist_hosts' => '',
'preserve_hosts' => false
}
Response Example:
{ "task_id" => "109" }
pro.import_file
The pro.import_file method starts a new import task with the supplied server-local path.
Request Example:
[ "pro.import_file", "<token>", "Project1", "/home/data/report.xml",
{
'blacklist_hosts' => '',
'preserve_hosts' => false
}
]
Response Example:
{ "task_id" => "109" }
pro.validate_import_file
The pro.validate_import_file method validates a file on disk to verify that it is a support data format. This method is non-standard in that it only returns a true or false value.
Request Example:
[ "pro.import_file", "<token>", "Project1", "/home/data/report.xml",
{
'blacklist_hosts' => '',
'preserve_hosts' => false
}
]
Response Example:
true
Pro Loot API
pro.loot_download
The pro.loot_download method downloads the file associated with loot record, by unique ID
Request Example:
[ "pro.loot_download", "<token>", 99 ]
Response Example:
{ "data" => "<BinaryData>" }
pro.loot_list
The pro.loot_download method returns a list of available loot records in a workspace
Request Example:
[ "pro.loot_list", "<token>", "Project1" ]
Response Example:
{
"900" => {
'workspace' => "Project1",
'host' => "1.2.3.4",
'service' => 80,
'proto' => 'tcp',
'ltype' => 'screenshot',
'ctype' => 'image/jpeg',
'created_at' => <Unix Timestamp Integer>,
'updated_at' => <Unix Timestamp Integer>,
'name' => 'desktop.jpg',
'info' => 'User desktop screenshot',
'path' => '/opt/metasploit/loot/wspace_1_xxxxx.jpg',
'size' => 40945
}
}
Pro Module API
pro.module_search
The pro.module_search method scans the module database and returns any entries matching the specified search query.
Request Example:
[ "pro.module_search", "<token>", "dcom" ]
Response Example:
{ "matches"=>
{"exploit/windows/dcerpc/ms03_026_dcom"=>
{"type" => "exploit",
"name" => "Microsoft RPC DCOM Interface Overflow",
"rank" => 500,
"description" => "Long description…",
"license" => "Metasploit Framework License (BSD)",
"filepath" => "[..]/windows/dcerpc/ms03_026_dcom.rb",
"version" => "11545",
"arch" => [],
"platform" => [],
"references" =>
[["CVE", "2003-0352"],
["OSVDB", "2100"],
["MSB", "MS03-026"],
["BID", "8205"]],
"authors" =>
["hdm <hdm[at]metasploit.com>",
"spoonm <spoonm@no$email.com>",
"cazz <bmc[at]shmoo.com>"],
"privileged" => true,
"disclosure_date" => 1058313600,
"targets" => {0=>"Windows NT SP3-6a/2000/XP/2003 Universal"},
"default_target" =>"0",
"stance" => "aggressive"}, …
}
}
}
pro.module_validate
The pro.module_validate method is used to determine whether a set of options satisfies the requirements of a given module.
Request Example:
[ "pro.module_validate", "<token>",
"exploit/windows/smb/psexec", {
"RHOST" => "1.2.3.4"
}
]
Response Example:
{ "result" => "success" }
Invalid options would result in the following:
Response Example:
{
"result" => "failure",
"error" => "The following options failed to validate: RHOST."
}
pro.modules
The pro.modules method returns the full set of modules for a given type
Request Example:
[ "pro.modules", "<token>", "post" ]
Response Example:
{"modules" =>
{ "post/linux/gather/checkvm" =>
{"type" => "post",
"name" => "Linux Gather Virtual Environment Detection",
"rank" => 300,
"description" => "Long description…",
"license" => "Metasploit Framework License (BSD)",
"filepath" => "[…]post/linux/gather/checkvm.rb",
"version" => "13173",
"arch" => [],
"platform" => ["Msf::Module::Platform::Linux"],
"references" => [],
"authors" => ["Carlos Perez <carlos_perez[at]darkoperator.com>"],
"privileged" => false}, …
}
}
}
What's Next?