Sample Usage

The following scripts provide examples of how you can use the RPC API to perform common tasks. These examples can be viewed in metasploit/apps/pro/api-example.

Adding a Workspace

#

# NOTE: Workspace and Project are the same thing.

#

require_relative 'metasploit_rpc_client'

workspace_attrs = {

 

name: "FooCorp Pentest",

limit_to_network: true,

boundary: "10.2.3.1-10.2.3.24",

description: "A test of FooCorp's mission-critical internal Quake LAN."

}

 

# Setup stuff from CLI

api_token = ARGV[0]

host = ARGV[1]

 

# Make the client - set ssl to true in install environments

client = MetasploitRPCClient.new(host:host, token:api_token, ssl:false, port:50505)

client.call "pro.workspace_add", workspace_attrs

 

Listing, Downloading, and Generating a Report

# Examples of report listing, download, and generation via RPC API.

#

# Usage:

# ruby report_api_test.rb <SERVICE KEY> <MSPro instance> '<WorkspaceName>'

#

# Service key: Generate an API token from Global Settings, requires

# Pro licensed instance.

# MSPro instance: 127.0.0.1 if running locally

#

#

 

require_relative 'metasploit_rpc_client'

 

# Setup stuff from CLI

api_token = ARGV[0]

host = ARGV[1]

workspace_name = ARGV[2]

# Make the client

client = MetasploitRPCClient.new(host:host, token:api_token, ssl:false, port:50505)

 

## Reports

# List report types

type_list = client.call('pro.list_report_types')

puts "Allowed Report types: \n#{type_list}"

 

# List current reports

#report_list = client.call('pro.report_list', workspace_name)

#puts "\n\nExisting Reports: #{report_list}\n"

 

# Download report artifact

#report_artifact_id = 1

#artifact = client.call('pro.report_artifact_download', report_artifact_id)

#tmp_path = "/tmp/report_#{report_artifact_id}#{File.extname(artifact['file_path'])}"

#File.open(tmp_path, 'w') {|c| c.write artifact['data']}

#puts "Wrote report artifact #{report_artifact_id} to #{tmp_path}"

 

# Create a report

#report_hash = {workspace: workspace_name,

# name: "SuperTest_#{Time.now.to_i}",

# report_type: :audit,

# #se_campaign_id: 1,

# created_by: 'whoareyou',

# file_formats: [:pdf]

#}

#report_creation = client.call('pro.start_report', report_hash)

#puts "\n\nCreated report: \n#{report_creation}"

 

## Download report and child artifacts

#report_id = 1

#report = client.call('pro.report_download', report_id)

#report['report_artifacts'].each_with_index do |a, i|

# tmp_path = "/tmp/report_test_#{i}_#{Time.now.to_i}#{File.extname(a['file_path'])}"

# File.open(tmp_path, 'w') {|c| c.write a['data']}

# puts "Wrote report artifact #{report_id} to #{tmp_path}"

#end

Importing Data

#

# Example of data import via the RPC API.

#

# Usage:

# ruby import_api_test.rb <Service key> <MSPro instance> \

# '<Project name>' \

# '<Full path to import file>'

#

# Service key: Generate an API token from Global Settings, requires

# Pro licensed instance.

# MSPro instance: 127.0.0.1, if running locally

# Project name: name of an existing workspace into which to import

# Import file path: fully qualified path to import file of supported

# format

#

require_relative 'metasploit_rpc_client'

 

# CLI arguments

api_token = ARGV[0]

host = ARGV[1]

workspace_name = ARGV[2]

import_file_path = ARGV[3]

 

unless api_token && host && workspace_name

raise Exception, 'You must specify an API token, an instance address, and a workspace name.'

end

unless import_file_path

raise Exception, 'You must specify an import file path.'

end

 

# Make the client

client = MetasploitRPCClient.new(host:host, token:api_token, ssl:false, port:50505)

 

# Import config

import_hash = {

workspace: workspace_name,

# Toggle datastore options (documented, with some exceptions, like

# this handy one) thusly:

# DS_AUTOTAG_OS: true,

# TODO Update with correct path:

DS_PATH: import_file_path

}

 

import = client.call('pro.start_import', import_hash)

puts "\nStarted import: \n#{import}"

Exporting Data

# Examples of export listing, download, and generation via

# RPC API.

#

# Usage:

# ruby export_api_test.rb <SERVICE KEY> <MSPro instance> '<WorkspaceName>'

#

# Service key: Generate an API token from Global Settings, requires

# Pro licensed instance.

# MSPro instance: 127.0.0.1 if running locally

#

#

 

require_relative 'metasploit_rpc_client'

 

# Setup stuff from CLI

api_token = ARGV[0]

host = ARGV[1]

workspace_name = ARGV[2]

 

# Make the client

client = MetasploitRPCClient.new(host:host, token:api_token, ssl:false, port:50505)

 

### Exports

## List current exports

export_list = client.call('pro.export_list', workspace_name)

puts "Existing Exports: #{export_list}"

 

## Create export

# export_types = ['zip_workspace','xml','replay_scripts','pwdump']

# export_config = {created_by: 'whoareyou',

# export_type: export_types[0],

# workspace: workspace_name}

# export_creation = client.call('pro.start_export', export_config)

# puts "Created export: #{export_creation}"

 

## Download export

# export_id = 1

# export = client.call('pro.export_download', export_id)

# tmp_path = "/tmp/export_test_#{export_id}#{File.extname(export['file_path'])}"

# File.open(tmp_path, 'w') {|c| c.write export['data']}

# puts "Wrote export #{export_id} to #{tmp_path}"

 

What's Next?

• RPC API
• Standard API Methods Reference
• Pro API Methods Reference
• Sample Usage