Rest Api PDF

REST API Guide
REST API
The RESTAPI 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 RESTAPI 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 RESTAPI. 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
anAPIkey 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.
REST API 1
Now that you have an API key, you can use it to create a request to the server. All requests must include
an APIkey that is defined in a custom HTTPheader 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:
l -k: Allows connections to SSL sites without certificates.
l -v: Enables verbose mode.
l -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
l You must have an active Metasploit Pro license key to use the RESTAPI.
l Each request must have a valid API token in the HTTP 'token' header.
l All valid requests result in a 200 response.
Authenticating Requests 2
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 URIscheme 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:
https://localhost:3790/rest_api/v2/workspaces/1/hosts
This request returns a JSONobject 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,
Requesting Data 3
"detected_arch":null
}
Recapping this Section
l The URI scheme is https://<Metasploit server>:3790/rest_api/v2/workspaces/:workspace_id/.
l The serialization format for the REST API is JSON.
l Variables are prepended with a colon.
l Endpoints respond with an array of objects for an index request and a single object for a show request.
l 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:
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:
Finding IDs 4
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.
API Endpoints
The RESTAPI provides access to the resources, such as hosts and sessions, available. Currently, you
can request a list of resources (index) or the details for a single resource (show), which is identified by an
ID.
Workspaces
You can create a workspace index request or a workspace show request.
Workspaces Index Request
Returns a list of all workspaces on the Metasploit server.
API Endpoints 5
URI
/rest_api/v2/workspaces
Example
https://localhost:3790/rest_api/v2/workspaces
Parameters
A call to this endpoint requires the following parameters:
l None
Response
A successful call to this endpoint returns a 200 OK response and a JSON object.
Workspace Show Request
Returns a workspace by ID.
URI
/rest_api/v2/workspaces/:id
Example
https://localhost:3790/rest_api/v2/workspaces/1
Parameters
l id
API Endpoints 6
Response
A successful call to this endpoint returns a 200 OK response and the following fields:
l id
l name
l boundary
l description
l owner_id
l limit_to_network
l created_at
l updated_at
Hosts
You can create a hosts index request or a host show request.
Hosts Index Request
Returns a list of hosts for a particular workspace.
URI
/rest_api/v2/workspaces/:workspace_id/hosts
Example
Parameters
l workspace_id
API Endpoints 7
Response
Host Show Request
Returns a host by ID.
URI
/rest_api/v2/workspaces/:workspace_id/hosts/:id
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1
Parameters
l workspace_id
l host_id
Response
l id
l workspace_id
l address
l mac
l comm
l name
l state
l os_name
l os_flavor
API Endpoints 8
l os_sp
l os_lang
l arch
l purpose
l info
l comments
l scope
l virtual_host
l note_count
l vuln_count
l service_count
l host_detail_count
l exploit_attempt_count
l cred_count
l nexpose_data_asset_id
l history_count
l detected_arch
l created_at
l updated_at
Notes
You can create a notes index request or a note show request.
Notes Index Request
Returns a list of notes for a particular host.
URI
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/notes
API Endpoints 9
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/notes
Parameters
l workspace_id
l host_id
Response
Note Show Request
Returns a note by ID.
URI
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/notes/:id
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/notes/1
Parameters
l workspace_id
l host_id
l id
API Endpoints 10
Response
l id
l ntype
l workspace_id
l vuln_id
l service_id
l host_id
l critical
l seen
l data
l created_at
l updated_at
Sessions
You can create a sessions index request or a session show request.
Sessions Index Request
Returns a list of sessions for a particular host.
URI
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/sessions
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/sessions
Parameters
API Endpoints 11
l workspace_id
l host_id
Response
Session Show Request
Returns a session by ID.
URI
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/sessions/:id
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/sessions/1
Parameters
l workspace_id
l host_id
l id
Response
l id
l host_id
l stype
l via_exploit
l via_payload
API Endpoints 12
l desc
l port
l platform
l datastore
l close_reason
l local_id
l module_run_id
l last_seen
l campaign_id
l opened_at
l closed_at
Services
You can create a services index request or a service show request.
Services Index Request
Returns a list of services for a particular host.
URI
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services
Parameters
Response
API Endpoints 13
Service Show Request
Returns a service by ID.
URI
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:id
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1
Parameters
l workspace_id
l host_id
l id
Response
l id
l host_id
l port
l state
l name
l info
l created_at
l updated_at
Vulns
You can create a vulns index request or a vuln show request.
API Endpoints 14
Vulnerabilities Index Request
Returns a list of vulnerabilities for a particular host.
URI
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_
id/vulns
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/vulns
Parameters
l workspace_id
l host_id
l service_id
Response
Vulnerability Show Request
Returns a vulnerability by ID.
URI
id/vulns/:id
API Endpoints 15
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/vulns/1
Parameters
l workspace_id
l host_id
l service_id
l id
Response
l id Integer
l service_id
l host_id
l name
l info
l exploited_at
l vuln_detail_count
l vuln_attempt_count
l nexpose_data_vuln_def_id
l created_at
l updated_at
WebSites
You can create a websites index request or a website show request.
Websites Index Request
Returns a list of websites for a particular workspace.
API Endpoints 16
URI
id/web_sites
Example
https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/web_
sites
Parameters
l workspace_id
l host_id
l service_id
Response
Website Show Request
Returns a website by ID.
URI
id/web_sites/:id
Example
sites/1
API Endpoints 17
Parameters
l workspace_id
l host_id
l service_id
l id
Response
l id
l service_id
l vhost
l comments
l options
l created_at
l updated_at
WebForms
You can create a web forms index request or a web form show request.
Web Forms Index Request
Returns a list of web forms.
URI
id/web_sites/:web_site_id/web_forms
API Endpoints 18
Example
sites/1/web_forms
Parameters
l workspace_id
l host_id
l service_id
l web_site_id
Response
Web Form Show Request
Returns a web form by ID.
URI
id/web_sites/:web_site_id/web_forms/:id
Example
sites/1/web_forms/1
Parameters
API Endpoints 19
l workspace_id
l host_id
l service_id
l web_site_id
l id
Response
l id
l web_site_id
l path
l method
l params
l query
l created_at
l updated_at
WebPages
You can create a web pages index request or a web page show request.
Web Pages Index Request
Returns a list of web pages for a particular workspace.
URI
id/web_sites/:web_site_id/web_pages
API Endpoints 20
Example
sites/1/web_pages
Parameters
l workspace_id
l host_id
l service_id
l web_site_id
Response
Web Page Show Request
Returns a web page by ID.
URI
id/web_sites/:web_site_id/web_pages/:id
Example
sites/1/web_pages/1
Parameters
API Endpoints 21
l workspace_id
l host_id
l service_id
l web_site_id
l id
Response
l id
l web_site_id
l path
l query
l code
l cookie
l auth
l ctype
l mtime
l location
l headers Array
l body
l request
l created_at
l updated_at
WebVulns
You can create a web vulnerabilities index request or a web vulnerability show request.
Web Vulnerabilities Index Request
Returns a list of web vulnerabilities for a particular workspace.
API Endpoints 22
URI
id/web_sites/:web_site_id/web_vulns
Example
sites/1/web_pages/web_vulns
Parameters
l workspace_id
l host_id
l service_id
l web_site_id
Response
Web Vulnerability Show Request
Returns a web vulnerability by ID.
URI
id/web_sites/:web_site_id/web_vulns/:id
API Endpoints 23
Example
sites/1/web_pages/web_vulns/1
Parameters
l workspace_id
l host_id
l service_id
l web_site_id
l id
Response
l id
l web_site_id
l path
l method
l params
l pname
l risk
l name
l query
l legacy_category
l confidence
l description
l blame
l request
l owner
API Endpoints 24
l payload
l request_id
l category_id
l created_at
l updated_at
RESTAPIExample
#
# Trivial example of using the REST-based API
#
#
begin
require 'json' # provides serialization of Ruby data structures to
and from JSON format
require 'rest-client' # super-friendly HTTP access
rescue LoadError
puts "please install deps:\n"
puts "gem install json"
puts "gem install rest-client"
end
class MetasploitRestClient
attr_reader :token
def initialize(opts)
@token = opts.fetch(:token)
end
def get(url, headers={}, params={})

RestClient.get(url, headers.merge({token:token}))
end
end
token = ARGV[0]
client = MetasploitRestClient.new(token:token)
# NB: in production, host/port/scheme should be "https//<HOST>:3790"

url = "http://localhost:3000/rest_api/v1/social_
engineering/campaigns.json"
campaigns = JSON.parse client.get(url)
p campaign
RESTAPIExample 25

Rest Api PDF

Uploaded by

Copyright:

Available Formats

Rest Api PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Rest Api PDF

Uploaded by

Copyright:

Available Formats

What is the purpose of the REST API?

What is the purpose of the REST API?

How do you authenticate requests to the REST API?

How do you authenticate requests to the REST API?

REST API Guide

l -k: Allows connections to SSL sites without certificates.

l -v: Enables verbose mode.

Recapping this Section

l All valid requests result in a 200 response.

The URIscheme for a request is:

Recapping this Section

l The URI scheme is https://<Metasploit server>:3790/rest_api/v2/workspaces/:workspace_id/.

l The serialization format for the REST API is JSON.

l Variables are prepended with a colon.

l All calls to the API must be versioned. The current version is 2.

This returns all workspaces and their details, as shown below:

You can create a workspace index request or a workspace show request.

Workspaces Index Request

Returns a list of all workspaces on the Metasploit server.

A call to this endpoint requires the following parameters:

Workspace Show Request

Returns a workspace by ID.

A call to this endpoint requires the following parameters:

You can create a hosts index request or a host show request.

Hosts Index Request

Returns a list of hosts for a particular workspace.

A call to this endpoint requires the following parameters:

Host Show Request

Returns a host by ID.

A call to this endpoint requires the following parameters:

You can create a notes index request or a note show request.

Notes Index Request

Returns a list of notes for a particular host.

A call to this endpoint requires the following parameters:

Note Show Request

Returns a note by ID.

A call to this endpoint requires the following parameters:

You can create a sessions index request or a session show request.

Sessions Index Request

Returns a list of sessions for a particular host.

A call to this endpoint requires the following parameters:

Session Show Request

Returns a session by ID.

A call to this endpoint requires the following parameters:

You can create a services index request or a service show request.

Services Index Request

Returns a list of services for a particular host.

A call to this endpoint requires the following parameters:

Returns a service by ID.

A call to this endpoint requires the following parameters:

You can create a vulns index request or a vuln show request.

Returns a list of vulnerabilities for a particular host.

A call to this endpoint requires the following parameters:

Vulnerability Show Request

Returns a vulnerability by ID.

A call to this endpoint requires the following parameters:

You can create a websites index request or a website show request.

Websites Index Request

Returns a list of websites for a particular workspace.