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 below.

ips

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.

  • Required - Yes
  • Example - [ "192.168.0.0/24" ]

workspace

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.

  • Required - Yes
  • Example - Project1

username

This option specifies which Pro username this scan task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - admin

DS_BLACKLIST_HOSTS

This option determines what addresses within the ips range should be excluded from the scan. Multiple entries should be separated by spaces.

  • Required - No
  • Example - 192.168.0.1

DS_PORTSCAN_SPEED

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.

  • Required - No
  • Example - Insane

DS_PORTS_EXTRA

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).

  • Required - No
  • Example - 1-65535

DS_PORTS_BLACKLIST

This option defines a list of ports that should always be excluded.

  • Required - No
  • Example - 9100, 1723

DS_PORTS_CUSTOM

This option overrides the built-in port list (derived from the loaded exploit modules) and only scans the ports listed.

  • Required - No
  • Example - 1-1024

DS_PORTSCAN_TIMEOUT

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.

  • Required - No
  • Example - 300

DS_PORTSCAN_SOURCE_PORT

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.

  • Required - No
  • Example - 53

DS_CustomNmap

This option can be used to completely override the Nmap command line normally used by Pro and replace it (excluding hosts and ports).

  • Required - No
  • Example - -sF -O

DS_UDP_PROBES

This option can be used to disable UDP service probes by setting it to false (it is enabled otherwise).

  • Required - No
  • Example - false

DS_FINGER_USERS

This option can be used to disable the finger service (79/tcp) automated username harvesting that occurs by default when enabled.

  • Required - No
  • Example - false

DS_SNMP_SCAN

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.

  • Required - No
  • Example - false

DS_IDENTIFY_SERVICES

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.

  • Required - No
  • Example - false

DS_SMBUser

This option can be used to extract additional information from SMB services if a valid username and password is supplied.

  • Required - No
  • Example - Administrator

DS_SMBPass

This option defines the password that corresponds to the DS_SMBUser option.

  • Required - No
  • Example - S3cr3t

DS_SMBDomain

This option defines the domain that corresponds to the DS_SMBUser option.

  • Required - No
  • Example - CORP

DS_DRY_RUN

This option, when set to true, will cause the task to show what it would do, but not actually send any network traffic.

  • Required - No
  • Example - true

DS_SINGLE_SCAN

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.

  • Required - No
  • Example - true

DS_FAST_DETECT

This option, when set to true, will limit the scan to a small set of TCP ports.

  • Required - No
  • Example - true

Request Example

A sample request to use the default settings to scan 192.168.0.0/24 would look like:

shell
1
[ "pro.start_discover", "<token>",
2
  {
3
  "ips" => [ "192.168.0.0/24" ],
4
  "workspace" => "Project1"
5
  }
6
]

If we change the same request to scan all 65535 TCP ports, it would look like:

shell
1
[ "pro.start_discover", "<token>",
2
  {
3
  "ips" => [ "192.168.0.0/24" ],
4
  "workspace" => "Project1",
5
  "DS_PORTS_CUSTOM" => "1-65535"
6
  }
7
]

Response Example

json
1
{ "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 below.

workspace

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.

  • Required - Yes
  • Example - Project1

username

This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - admin

DS_PATH

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.

  • Required - No
  • Example - /tmp/nexpose.xml

DS_BLACKLIST_HOSTS

This option determines what addresses should be excluded from the import. Multiple entries should be separated by spaces.

  • Required - No
  • Example - 192.168.0.1

DS_PRESERVE_HOSTS

This option can be used to prevent modifications to existing hosts during an import.

  • Required - No
  • Example - true

DS_REMOVE_FILE

This option tells the service to delete the file specified as DS_PATH after importing it.

  • Required - No
  • Example - true

DS_ImportTags

This option indicates whether to import tags as well as host data when processing a Metasploit Pro export file.

  • Required - No
  • Example - false

DS_NEXPOSE_CONSOLE

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.

  • Required - No
  • Example - EnterpriseScanner

DS_NEXPOSE_SITE

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.

  • Required - No
  • Example - Finance

Request Example

A sample request to import a Nexpose Export XML would look like:

shell
1
[ "pro.start_import", "<token>",
2
  {
3
  "workspace" => "Project1",
4
  "DS_PATH" => "/tmp/nexpose.xml"
5
  }
6
]

Response Example

json
1
{ "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.

workspace

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.

  • Required - Yes
  • Example - Project1

username

This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - admin

DS_IMPORT_PATH

This option specifies the server-local file path to import.

  • Required - No
  • Example - /tmp/wordlist.txt

DS_FTYPE

This option determines tells the service that kind of import this is. It should be one of "userpass", "user", "pass", pwdump", or "ssh_keys".

  • Required - No
  • Example - pass

DS_NAME

This option indicates a unique name of this imported data set.

  • Required - No
  • Example - common_passwords

DS_DESC

This option provides a user-visible description of this imported data

  • Required - No
  • Example - Common passwords

DS_ORIG_FILE_NAME

This option indicates the original file name of the credential data.

  • Required - No
  • Example - my_passwords.txt

DS_REMOVE_FILE

This option indicates whether the service should delete the local file after importing it.

  • Required - No
  • Example - true

Request Example

shell
1
[ "pro.start_import_creds", "<token>",
2
  {
3
  "workspace" => "Project1",
4
  "DS_IMPORT_PATH" => "/tmp/pwdump.txt",
5
  "DS_FTYPE" => "pwdump",
6
  "DS_NAME" => "domain_dump",
7
  "DS_DESC" => "Password hashes from the DC",
8
  "DS_REMOVE_FILE" => false
9
  }
10
]

Response Example

json
1
{ "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.

workspace

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.

  • Required - Yes
  • Example - Project1

username

This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - admin

DS_WHITELIST_HOSTS

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.

  • Required - Yes
  • Example - 192.168.0.0/24

DS_BLACKLIST_HOSTS

This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - 192.168.0.3

DS_NEXPOSE_HOST

This option specifies the list of addresses and network ranges to scan.

  • Required - No
  • Example - 127.0.0.1

DS_NEXPOSE_PORT

This option specifies the port of the Nexpose Console.

  • Required - No
  • Example - 3780

DS_NEXPOSE_USER

This option specifies a valid username for the Nexpose Console.

  • Required - No
  • Example - nxadmin

nexpose_pass

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.

  • Required - No
  • Example - S3cr3t

DS_SCAN_TEMPLATE

The option specifies the scan template to use. The common templates include: pentest-audit full-audit, exhaustive-audit, discovery, aggressive-discovery, and dos-audit.

  • Required - No
  • Example - pentest-audit

Request Example

The following shows an example of a request to start a new Nexpose scan:

shell
1
[ "pro.start_nexpose", "<token>",
2
  {
3
  "workspace" => "Project1",
4
  "DS_WHITELIST_HOSTS" => "192.168.0.0/24",
5
  "DS_NEXPOSE_HOST" => "127.0.0.1",
6
  "DS_NEXPOSE_PORT" => 3780,
7
  "DS_NEXPOSE_USER" => "nxadmin",
8
  "nexpose_pass" => "s3cr3t",
9
  "DS_SCAN_TEMPLATE" => "pentest-audit"
10
  }
11
]

Response Example

json
1
{ "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.

workspace

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.

  • Required - Yes
  • Example - Project1

username

This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - admin

DS_WHITELIST_HOSTS

This option specifies the list of addresses and network ranges to test.

  • Required - Yes
  • Example - 192.168.0.0/24

DS_BLACKLIST_HOSTS

This option specifies the list of addresses and network ranges to exclude from the target range.

  • Required - No
  • Example - 192.168.0.3

DS_STOP_ON_SUCCESS

This option indicates whether the bruteforce attack should continue testing a service after cracking the first account.

  • Required - Yes
  • Example - true

DS_VERBOSE

This option indicates how much diagnostic information is shown during bruteforce.

  • Required - No
  • Example - true

DS_INCLUDE_KNOWN

This option indicates whether the bruteforce attack should use credentials that were previously found.

  • Required - Yes
  • Example - true

DS_DRY_RUN

This option indicates whether to skip the bruteforce attack and just show what usernames and passwords would have been tested.

  • Required - No
  • Example - true

DS_BRUTEFORCE_SCOPE

This option indicates what bruteforce mode to operate in. This is one of the following settings: quick, defaults, normal, deep, known, imported, or 50k.

  • Required - Yes
  • Example - normal

DS_BRUTEFORCE_SPEED

This option specifies how fast to conduct the bruteforce attack. This is one of the following settings: Glacial, Slow, Stealthy, Normal, Fast, or Turbo.

  • Required - Yes
  • Example - turbo

DS_BRUTEFORCE_SERVICES

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.

  • Required - Yes
  • Example - SSH

DS_BRUTEFORCE_GETSESSION

This option specifies whether to use cracked accounts to gain access to the tested systems.

  • Required - Yes
  • Example - true

DS_QUICKMODE_CREDS

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.

  • Required - No
  • Example - Username Password\n

DS_PAYLOAD_METHOD

This option determines what connection method to use when opening sessions, it can be one of auto, reverse, or bind.

  • Required - No
  • Example - auto

DS_PAYLOAD_TYPE

This option determines whether to prefer meterpreter or shell session types.

  • Required - No
  • Example - meterpreter

DS_PAYLOAD_PORTS

This option specifies the port range to use for bind and reverse connections.

  • Required - No
  • Example - 4000-5000

DS_SMB_DOMAINS

This option specifies a list of domains, separated by spaces, to use when brute forcing protocols that speak NTLM.

  • Required - No
  • Example - Domain1

DS_PRESERVE_DOMAINS

This option specifies whether to use the original domain name with each username and password previously identified.

  • Required - No
  • Example - true

DS_CRED_FILE_IDS

This option specifies what imported credential files to include in this bruteforce task. This requires knowledge of the imported credential file IDs.

  • Required - No
  • Example - 34

DS_MAXGUESSESPERSERVICE

This option specifies the maximum number of authentication attempts per service, it defaults to 0 which is unlimited.

  • Required - No
  • Example - 100

DS_MAXMINUTESPERSERVICE

This option specifies the maximum amount of time in minutes to spend on each service, it defaults to 0 which is unlimited.

  • Required - No
  • Example - 60

DS_MAXGUESSESPERUSER

This option specifies the maximum number of guesses to try for each unique user account, it defaults to 0 which is unlimited.

  • Required - No
  • Example - 3

DS_MAXMINUTESOVERALL

This option specifies the maximum amount of time to run for the entire bruteforce task, it defaults to 0 which is unlimited.

  • Required - No
  • Example - 30

DS_MAXGUESSESOVERALL

This option specifies the maximum number of guesses to try overall, it defaults to 0 which is unlimited.

  • Required - No
  • Example - 1000

DS_BRUTEFORCE_SKIP_BLANK_PASSWORDS

This option specifies whether to skip blank passwords entirely, it defaults to false.

  • Required - No
  • Example - true

DS_BRUTEFORCE_SKIP_MACHINE_NAMES

This option specifies whether to skip machine names as a password seed source for the wordlist, it defaults to false.

  • Required - No
  • Example - true

DS_BRUTEFORCE_SKIP_BUILTIN_WINDOWS_ACCOUNTS

This option specifies whether to skip builtin Windows accounts that typically do not have weak passwords (service accounts).

  • Required - No
  • Example - true

DS_BRUTEFORCE_SKIP_BLANK_BUILTIN_UNIX_ACCOUNTS

This options specifies whether to skip built-in Unix accounts that typically do have weak passwords (service accounts).

  • Required - No
  • Example - true

DS_BRUTEFORCE_RECOMBINE_CREDS

This option specifies whether to recombine known, imported, and additional credentials to create the wordlists.

  • Required - No
  • Example - true

DS_MSSQL_WINDOWS_AUTH

This option indicates that MSSQL Server authentication should use NTLM instead of Standard mode. This defaults to false.

  • Required - No
  • Example - true

A sample request to start a new Bruteforce task:

Request Example

shell
1
[ "pro.start_bruteforce", "<token>",
2
  {
3
  "workspace" => "Project1",
4
  "DS_WHITELIST_HOSTS" => "192.168.0.0/24",
5
  "DS_BRUTEFORCE_SCOPE" => "defaults",
6
  "DS_BRUTEFORCE_SERVICES" => "SSH HTTP",
7
  "DS_BRUTEFORCE_SPEED" => "TURBO",
8
  "DS_INCLUDE_KNOWN" => normal,
9
  "DS_BRUTEFORCE_GETSESSION" => true
10
  }
11
]

Response Example

json
1
{ "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.

workspace

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.

  • Required - Yes
  • Example - Project1

username

This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - admin

DS_WHITELIST_HOSTS

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.

  • Required - Yes
  • Example - 192.168.0.0/24

DS_BLACKLIST_HOSTS

This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - 192.168.0.3

DS_WHITELIST_PORTS

This option specifies what ports are allowed during the exploitation task. This defaults to 1-65535 (all ports).

  • Required - No
  • Example - 1-1000

DS_BLACKLIST_PORTS

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.

  • Required - No
  • Example - 80,443

DS_MinimumRank

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.

  • Required - Yes
  • Example - great

DS_EXPLOIT_SPEED

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.

  • Required - Yes
  • Example - 5

DS_EXPLOIT_TIMEOUT

This option sets the maximum amount of time any individual exploit can run. Setting this below 2 minutes can prevent some exploits from working.

  • Required - No
  • Example - 5

DS_LimitSessions

This option determines whether to attempt to avoid exploiting systems that already have an active session. The default is true.

  • Required - No
  • Example - false

DS_IgnoreFragileDevices

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.

  • Required - No
  • Example - false

DS_FilterByOS

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.

  • Required - No
  • Example - false

DS_OnlyMatch

This option, when set to true, instructions to exploit engine to match exploits but not actually run them. The default setting is false.

  • Required - No
  • Example - false

DS_MATCH_VULNS

This option instructs the exploit engine to match exploits based on vulnerability references. This setting defaults to true.

  • Required - Yes
  • Example - false

DS_MATCH_PORTS

This option instructs the exploit engine to match exploits based on open services. This setting defaults to true.

  • Required - Yes
  • Example - false

DS_PAYLOAD_METHOD

This option determines what connection method to use when opening sessions, it can be one of auto, reverse, or bind.

  • Required - No
  • Example - auto

DS_PAYLOAD_TYPE

This option determines whether to prefer meterpreter or shell session types.

  • Required - No
  • Example - meterpreter

DS_PAYLOAD_PORTS

This option specifies the port range to use for bind and reverse connections.

  • Required - No
  • Example - 4000-5000

DS_EVASION_LEVEL_TCP

This option specifies a transport-level evasion level between 0 and 3.

  • Required - No
  • Example - 1

DS_EVASION_LEVEL_APP

This option specifies an application-level evasion level between 0 and 3.

  • Required - No
  • Example - 1

DS_ModuleFilter

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.

  • Required - No
  • Example - exploit/windows/smb/psexec

A sample request to run exploits across a network range:

Request Example

shell
1
[ "pro.start_exploit", "<token>",
2
  {
3
  "workspace" => "Project1",
4
  "DS_WHITELIST_HOSTS" => "192.168.0.0/24",
5
  "DS_MinimumRank" => "great",
6
  "DS_EXPLOIT_SPEED" => 5,
7
  "DS_EXPLOIT_TIMEOUT" => 2,
8
  "DS_LimitSessions" => true,
9
  "DS_MATCH_VULNS" => true,
10
  "DS_MATCH_PORTS" => true
11
  }
12
]

Response Example

json
1
{ "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.

workspace

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.

  • Required -Yes
  • Example - Project1

username

This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - admin

DS_SESSIONS

This option specifies a list of session IDs to close. These are RPC service session IDs.

  • Required - Yes
  • Example - 1 2 3

DS_DBSESSIONS

This option specifies a list of session IDs by their database identifiers.

  • Required - No
  • Example - 1001 1002

Request Example

shell
1
[ "pro.start_cleanup", "<token>",
2
  {
3
  "workspace" => "Project1",
4
  "DS_SESSIONS" => "100 101 102",
5
  }
6
]

Response Example

json
1
{ "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.

workspace

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.

  • Required - Yes
  • Example - Project1

username

This option specifies which Pro username this task should be attributed to. If not specified, the first user with administrative privileges is used.

  • Required - No
  • Example - admin

DS_SESSIONS

This option specifies a list of session IDs to close. These are RPC service session IDs.

  • Required - Yes
  • Example - 1 2 3

DS_COLLECT_SYSINFO

This option indicates whether basic system information should be acquired.

  • Required - Yes
  • Example - true

DS_COLLECT_PASSWD

This option indicates whether password and hashes should be acquired.

  • Required - Yes
  • Example - true

DS_COLLECT_SCREENSHOTS

This option indicates whether screenshots should be taken.

  • Required - Yes
  • Example - true

DS_COLLECT_SSH

This option indicates whether ssh key information should be acquired.

  • Required - Yes
  • Example - true

DS_COLLECT_FILES

This option indicates whether specific files matching a pattern should be acquired.

  • Required - Yes
  • Example - true

DS_COLLECT_FILES_PATTERN

This option sets the file pattern to automatically download.

  • Required - No
  • Example - *.doc

DS_COLLECT_FILES_COUNT

This option sets the maximum number of files to download per session.

  • Required - No
  • Example - 100

DS_COLLECT_FILES_SIZE

This option sets the maximum file size to download per file, in kilobytes.

  • Required - No
  • Example - 40

Request Example

shell
1
[ "pro.start_collect", "<token>",
2
  {
3
  "workspace" => "Project1",
4
  "DS_SESSIONS" => "100 101 102",
5
  "DS_COLLECT_SYSINFO" => true,
6
  "DS_COLLECT_PASSWD" => true,
7
  "DS_COLLECT_SCREENSHOTS" => true,
8
  "DS_COLLECT_SSH" => true,
9
  "DS_COLLECT_FILES" => false
10
  }
11
]

Response Example

json
1
{ "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.

workspace_name

The name of the workspace that you want to use to gather data for the report.

  • Required - Yes
  • Example - Project1
  • Type - String

name

The name the report will be saved as.

  • Required - Yes
  • Example - reportABC
  • Type - String

report_type

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.

  • Required - Yes
  • Example - audit
  • Type - String

report_template

The template used for custom reports. To specify a template, enter the full file path to the custom Jasper JRXML template.

  • Required - Yes
  • Example - /path/to/custom.jrxml
  • Type - String

Do not use this field unless the report_type is set to 'custom'.

created_by

The username to which the report should be attributed.

  • Required - Yes
  • Example - admin
  • Type - String

file_formats

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.

  • Required - Yes
  • Example - pdf
  • Type - Array

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

The addresses to which the report should be emailed. Addresses can be separated with comma, semicolon, newlines, or spaces.

  • Required - No
  • Example - joe@mail.com, jon@mail.com
  • Type - String

mask_credentials

Enables or disables the masking of credentials in a report. Set this option to true or false.

  • Required - No
  • Example - true
  • Type - Boolean

included_addresses

Includes the specified hosts in the report.

  • Required - No
  • Example - 192.168.1.0/24
  • Type - String

excluded_addresses

Excludes the specified hosts from the report.

  • Required - No
  • Example - 192.168.1.1
  • Type - String

logo_path

Adds a custom logo to the report's cover page.

  • Required - No
  • Type - String

You must specify the full path to the image. The image must have agif, png, jpg, or jpeg file type.

se_campaign_id

The ID of the social engineering campaign you want to use to gather data for the report.

  • Required - No
  • Example - 1
  • Type - Integer

Only use this field for Social Engineering reports.

sections

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.

  • Required - No
  • Example - cover, project_summary, task_details
  • Type - Array

usernames_reported

Includes a list of active users in the Executive summary section of the report. You must provide a comma separated list of user names.

  • Required - No
  • Example - admin1, admin 2
  • Type - String

Request Example

shell
1
[ "pro.report_start", "<token>",
2
  {
3
  workspace: workspace_name,
4
  name: "default_#{Time.now.to_i}",
5
  report_type: :audit,
6
  created_by: 'whoareyou',
7
  file_formats: [:pdf]
8
  }
9
]

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.

workspace_name

The name of the workspace that you want to export data from.

  • Required - Yes
  • Example - project1
  • Type - String

export_type

  • Required - Yes

created_by

The username to which the export should be attributed.

  • Required - Yes
  • Example - admin
  • Type - String

name

The name the export file will be saved as.

  • Required - No
  • Example - reportABC
  • Type - String

mask_credentials

Enables or disables the masking of credentials in an export. Set this option to true or false.

  • Required - No
  • Example - true
  • Type - Boolean

included_addresses

Includes the specified hosts in the export.

  • Required - No
  • Example - 192.168.1.0/24
  • Type - String

excluded_addresses

Excludes the specified hosts from the export.

  • Required - No
  • Example - 192.168.1.1
  • Type - String

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.