REST API Endpoints

The REST API 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.

URI

/rest_api/v2/workspaces

Example

https://localhost:3790/rest_api/v2/workspaces

Parameters

A call to this endpoint requires the following parameters:

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

A call to this endpoint requires the following parameters:

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id
name
boundary
description
owner_id
limit_to_network
created_at
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

https://localhost:3790/rest_api/v2/workspaces/1/hosts

Parameters

A call to this endpoint requires the following parameters:

workspace_id

Response

A successful call to this endpoint returns a 200 OK response and a JSON object.

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

A call to this endpoint requires the following parameters:

workspace_id
host_id

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id
workspace_id
address
mac
comm
name
state
os_name
os_flavor
os_sp
os_lang
arch
purpose
info
comments
scope
virtual_host
note_count
vuln_count
service_count
host_detail_count
exploit_attempt_count
cred_count
nexpose_data_asset_id
history_count
detected_arch
created_at
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

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/notes

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id

Response

A successful call to this endpoint returns a 200 OK response and a JSON object.

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

A call to this endpoint requires the following parameters:

workspace_id
host_id
id

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id
ntype
workspace_id
vuln_id
service_id
host_id
critical
seen
data
created_at
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

A call to this endpoint requires the following parameters:

workspace_id
host_id

Response

A successful call to this endpoint returns a 200 OK response and a JSON object.

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

A call to this endpoint requires the following parameters:

workspace_id
host_id
id

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id
host_id
stype
via_exploit
via_payload
desc
port
platform
datastore
close_reason
local_id
module_run_id
last_seen
campaign_id
opened_at
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

A call to this endpoint requires the following parameters:

workspace_id
host_id

Response

A successful call to this endpoint returns a 200 OK response and a JSON object.

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

A call to this endpoint requires the following parameters:

workspace_id
host_id
id

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id
host_id
port
state
name
info
created_at
updated_at

Vulns

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

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

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id

Response

A successful call to this endpoint returns a 200 OK response and a JSON object.

Vulnerability Show Request

Returns a vulnerability by ID.

URI

/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_id/vulns/:id

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/vulns/1

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id
id

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id Integer
service_id
host_id
name
info
exploited_at
vuln_detail_count
vuln_attempt_count
nexpose_data_vuln_def_id
created_at
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.

URI

/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_id/web_sites

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/web_sites

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id

Response

A successful call to this endpoint returns a 200 OK response and a JSON object.

Website Show Request

Returns a website by ID.

URI

/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_id/web_sites/:id

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/web_sites/1

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id
id

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id
service_id
vhost
comments
options
created_at
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

/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_id/web_sites/:web_site_id/web_forms

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/web_sites/1/web_forms

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id
web_site_id

Response

A successful call to this endpoint returns a 200 OK response and a JSON object.

Web Form Show Request

Returns a web form by ID.

URI

/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_id/web_sites/:web_site_id/web_forms/:id

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/web_sites/1/web_forms/1

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id
web_site_id
id

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id
web_site_id
path
method
params
query
created_at
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

/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_id/web_sites/:web_site_id/web_pages

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/web_sites/1/web_pages

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id
web_site_id

Response

A successful call to this endpoint returns a 200 OK response and a JSON object.

Web Page Show Request

Returns a web page by ID.

URI

/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_id/web_sites/:web_site_id/web_pages/:id

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/web_sites/1/web_pages/1

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id
web_site_id
id

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id
web_site_id
path
query
code
cookie
auth
ctype
mtime
location
headers Array
body
request
created_at
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.

URI

/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_id/web_sites/:web_site_id/web_vulns

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/web_sites/1/web_pages/web_vulns

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id
web_site_id

Response

A successful call to this endpoint returns a 200 OK response and a JSON object.

Web Vulnerability Show Request

Returns a web vulnerability by ID.

URI

/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:service_id/web_sites/:web_site_id/web_vulns/:id

Example

https://localhost:3790/rest_api/v2/workspaces/1/hosts/1/services/1/web_sites/1/web_pages/web_vulns/1

Parameters

A call to this endpoint requires the following parameters:

workspace_id
host_id
service_id
web_site_id
id

Response

A successful call to this endpoint returns a 200 OK response and the following fields:

id
web_site_id
path
method
params
pname
risk
name
query
legacy_category
confidence
description
blame
request
owner
payload
request_id
category_id
created_at
updated_at

REST API Example

# 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

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