REST API
The REST API provides an interface that enables you to easily consume the resources that are available in Metasploit Pro, such as hosts, vulnerabilities, and campaign data, from any application that can make HTTP requests. You can use the REST API to extract data from Metasploit Pro to manage in other tools, to automate tasks, and to integrate with other applications.
Authenticating Requests
You must have a valid Metasploit Pro license key in order to use the REST API. To generate an API key, you need to log in to the web interface (https://localhost:3790) and select Administration > Global Settings. When the Global Settings page appears, click on the API Keys tab and click the Create an API key button, as shown below:
The form requires that you provide a key name for the API token. After you provide a name, click the Create button to generate the token.
To view the API key, click on the obfuscated token located in the API Keys table, as shown below:
A popup window appears and displays the full key. You need to copy this key to use in your calls.
Note: The API token does not expire.
Now that you have an API key, you can use it to create a request to the server. All requests must include an API key that is defined in a custom HTTP header called 'token', which is specified using the -H option, as shown below:
$ curl -H "token:6bde125560088033c618c2app234" https://localhost:3790/rest_api/v2/base
The example above is a base route that performs an API check and uses the following options:
- -k: Allows connections to SSL sites without certificates.
- -v: Enables verbose mode.
- -H: Adds a custom HTTP header to pass to the server. Use this option to pass the API key in your requests.
The request returns the following response with a valid API key:
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 07 Apr 2015 21:26:13 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
X-UA-Compatible: IE=Edge,chrome=1
ETag: "7215ee9c7d9dc229d2921a40e899ec5f"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 2359d1d5c55e06242220a2465358cac9
X-Runtime: 0.004253
The 200 OK response code indicates that the request was successful. If you receive a 403 response, you need to verify that the API key is valid.
The examples in this guide use cURL to create, format, and send requests for resources.
Recapping this Section
- You must have an active Metasploit Pro license key to use the REST API.
- Each request must have a valid API token in the HTTP 'token' header.
- All valid requests result in a 200 response.
Requesting Data
Each resource is associated with a URI and is named as a noun, such as 'hosts', 'sessions', and 'campaigns'. You create a request for a resource using a defined URI.
The URI scheme for a request is:
https://<Metasploit server>:3790/rest_api/v2/workspaces/:workspace_id/hosts/:host_id
Any item preprended with a colon, such as 'workspace_id', indicates that it is a variable and needs to be replaced with the appropriate value. To learn how to find the ID for a workspace or host, read this section.
For example, if you want to request a list of hosts for the default workspace, the request would be similar to this:
$ curl -H "token:6bde125560088033c618c2app234" https://localhost:3790/rest_api/v2/workspaces/1/hosts
This request returns a JSON object that contains all the hosts in the default workspace as shown below:
{
"id":2,
"created_at":"2015-04-07T13:02:26-07:00",
"address":"10.20.33.22",
"mac":"",
"comm":null,
"name":"host2",
"state":"alive",
"os_name":"",
"os_flavor":"",
"os_sp":"", "os_lang":null,
"arch":null, "workspace_id":1,
"updated_at":"2015-04-07T13:02:26-07:00",
"purpose":"", "info":null,
"comments":null,
"scope":null,
"virtual_host":null,
"note_count":0,
"vuln_count":0,
"service_count":0,
"host_detail_count":0,
"exploit_attempt_count":0,
"cred_count":0,
"nexpose_data_asset_id":null,
"history_count":0,
"detected_arch":null
}
Recapping this Section
- The URI scheme is https://<Metasploit server>:3790/rest_api/v2/workspaces/:workspace_id/.
- The serialization format for the REST API is JSON.
- Variables are prepended with a colon.
- Endpoints respond with an array of objects for an index request and a single object for a show request.
- All calls to the API must be versioned. The current version is 2.
Finding IDs
To craft a request, you may need to know the ID for the resource from which you want to pull data. Most commonly, you need to know the workspace and host ID.
To view the workspace ID, run the following to view all workspaces on a particular Metasploit server:
$ curl -H "token:6bde125560088033c618c2app234" https://localhost:3790/rest_api/v2/workspaces
This returns all workspaces and their details, as shown below:
{
"id":1,
"name":"default",
"boundary":null,
"description":null,
"owner_id":null,
"limit_to_network":false,
"created_at":"2015-04-07T11:51:23-07:00",
"updated_at":"2015-04-07T11:51:23-07:00"
}
Find the 'id' field to identify the workspace ID. Then, to view a host ID, run the following:
$ curl -H "token:6bde125560088033c618c2app234" https://localhost:3790/rest_api/v2/workspaces/1/hosts
This requests the host index from workspace 1, which is the default workspace. You can replace the workspace ID with any workspace you want. The request returns all hosts in a particular workspace and their details, as shown below:
{
"id":1,
"created_at":"2015-04-07T13:02:26-07:00",
"address":"10.20.33.22",
"mac":"",
"comm":null,
"name":"host2",
"state":"alive",
"os_name":"",
"os_flavor":"",
"os_sp":"", "os_lang":null,
"arch":null, "workspace_id":1,
"updated_at":"2015-04-07T13:02:26-07:00",
"purpose":"", "info":null,
"comments":null,
"scope":null,
"virtual_host":null,
"note_count":0,
"vuln_count":0,
"service_count":0,
"host_detail_count":0,
"exploit_attempt_count":0,
"cred_count":0,
"nexpose_data_asset_id":null,
"history_count":0,
"detected_arch":null
}
The 'id' field in the example above represents the host ID.
What's Next?