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 (with an index request) or the details for a single resource (with a show request), 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

 
1
/rest_api/v2/workspaces

Example

 
1
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

 
1
/rest_api/v2/workspaces/:id

Example

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

Parameters

A call to this endpoint requires the following parameters:

  • id

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

 
1
/rest_api/v2/workspaces/:workspace_id/hosts

Example

 
1
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

 
1
/rest_api/v2/workspaces/:workspace_id/hosts/:id

Example

 
1
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

 
1
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/notes

Example

 
1
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

 
1
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/notes/:id

Example

 
1
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

 
1
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/sessions

Example

 
1
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

 
1
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/sessions/:id

Example

 
1
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

 
1
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services

Example

 
1
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

 
1
/rest_api/v2/workspaces/:workspace_id/hosts/:host_id/services/:id

Example

 
1
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

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

Example

 
1
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

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

Example

 
1
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

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

Example

 
1
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

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

Example

 
1
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

Web Forms

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

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

Example

 
1
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

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

Example

 
1
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

Web Pages

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

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

Example

 
1
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

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

Example

 
1
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

Web Vulns

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

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

Example

 
1
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

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

Example

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

ruby
1
begin
2
require 'json' # provides serialization of Ruby data structures to and from JSON format
3
require 'rest-client' # super-friendly HTTP access
4
rescue LoadError
5
puts "please install deps:\n"
6
puts "gem install json"
7
puts "gem install rest-client"
8
end
9


10
class MetasploitRestClient
11
attr_reader :token
12


13
def initialize(opts)
14
@token = opts.fetch(:token)
15
end
16


17
def get(url, headers={}, params={})
18
RestClient.get(url, headers.merge({token:token}))
19
end
20
end
21


22
token = ARGV[0]
23
client = MetasploitRestClient.new(token:token)
24


25
# NB: in production, host/port/scheme should be "https//<HOST>:3790"
26
url = "http://localhost:3000/rest_api/v1/social_engineering/campaigns.json"
27
campaigns = JSON.parse client.get(url)
28
p campaign