metasploit-framework/documentation/msfrpc.txt

[ INTRODUCTION ]

The msfrpcd daemon uses the xmlrpc plugin to provide a remote
interface to the Metasploit Framework. By default, this service
listens on port 55553, uses SSL, and is password protected.

The RPC interface allows access to a minimal set of framework
APIs, covering the core framework, the module set, the job list,
and the session table. These APIs can be used to enumerate
modules, execute them, and interact with the resulting sessions
and jobs. 


[ USAGE ]

To activate the RPC interface, launch msfrpcd, or load msfconsole
and load the xmlrpc plugin. 

$ ./msfrpcd -P s3cr3tp4ss
 - or -
msf> load xmlrpc Pass=s3cr3tp4ss

Once the interface is started, any compatible RPC interface can be used
to interact with the service. The 'msfrpc' client provides a Ruby
shell that can be used to talk to the service.

$ ./msfrpc -h server_name -P s3cr3tp4ss
[*] The 'rpc' object holds the RPC client interface

>> rpc.call("core.version")
=> {"version"=>"3.3-dev"}


[ API - AUTH ]

 Method: auth.login
Expects: username, password
Returns: { "result" => "success", "token" => "<token>" } 
Summary: This method is used by rpc.login() to obtain the session key
(token) which is sent in subsequent requests. This token uniquely
identifies a particular client and can be used by multiple clients,
even after the originating TCP session is closed. The RPC client
object automatically sends this token with all other method calls.
Inactive tokens are destroyed after five minutes of non-use. 


[ API - CORE ]

 Method: core.version
Expects: none
Returns: { "version" => "<framework-version>" } 


[ API - MODULE ]

 Method: module.exploits
 Method: module.auxiliary
 Method: module.payloads
 Method. module.encoders
 Method: module.nops
Expects: none
Returns: { "modules" => [ "module1", "module2", ... ] } 
Summary: This method is used to obtain a list of available modules
of the specified type. The resulting module names can be used in
other calls within the module service.

 Method: module.info
Expects: module_type, module_name
Returns: { "name" => "<name>", ... }
Summary: This method returns all shared module fields (name, authors,
version, description, etc), but also the list of targets and actions
when appropriate.

 Method: module.options
Expects: module_type, module_name
Returns: { "<option_name>" => { "type" => "integer", ... } }
Summary: This method returns a list of all options for a given module,
including advanced and evasion options. The returned hash contains
detailed information about each option, including its type, its
default value, whether it is required, and so on.

 Method: module.compatible_payloads
Expects: module_name
Returns: { "payloads" => [ "payload1", "payload2", ... ] }
Summary: This method only works for exploit modules and returns a
list of payloads that are compatible with the specified exploit.

 Method: module.execute
Expects: module_type, module_name, options_hash
Returns: { "result" => "success" }
Summary: This method only works for exploit and auxiliary modules
and uses the simplified framework API to launch these modules
with the specified options. Option values should be placed into
the options_hash argument, including items such as PAYLOAD,
TARGET, ACTION, and all required options.



[ API - JOB ]

 Method: job.list
Expects: none
Returns: { "<job_id>" => "<job_name>" }
Summary: This method returns a list of running jobs, along with
the name of the job.

 Method: job.stop
Expects: job_id
Returns: { "result" => "success" }
Summary: This method kills a specific job by ID



[ API - SESSION ]

 Method: session.list
Expects: none
Returns: { "<session_id>" => { "type" => "shell", ... } }
Summary: This method returns a list of active sessions, including
the fields type, tunnel_local, tunnel_peer, via_exploit,
via_payload, and desc.  

 Method: session.stop
Expects: session_id
Returns: { "result" => "success" }
Summary: This method kills a specific session by ID

 Method: session.shell_read
Expects: session_id
Returns: { "data" => "<shell_data>" }
Summary: This method reads any pending output from a session. This
method only works for sessions of type "shell" and does not block.

 Method: session.shell_write
Expects: session_id, shell_data
Returns: { "write_count" => "<number_of_bytes_written>" }
Summary: This method writes the specified input into the session. 
This method only works for sessions of type "shell" and does not 
block.


[ EXCEPTIONS ]

When an error occurs, an exception is thrown on the client side. This
exception will be of class XMLRPC::FaultException and the faultCode
and faultString methods of this exception will contain detailed
information about the problem. Many API calls will raise faultCode
of 404 when the specified item is not found. An unhandled, server
exception will result in a faultCode of 500 on the client side.



[ SECURITY CONSIDERATIONS ]

At this time, the SSL certificate used by the service is 
dynamically allocated, making it vulnerable to a man-in-the-middle
attack. Future versions will address this by allowing a certificate
to be generated and verified.

The current implementation passes the username and password for the
RPC service as parameters on the command line. This can lead to
disclosure of the password to other local users on some Unix systems.
The msfrpc and msfrpcd applications change the displayed arguments
as soon as they are launched, but there is still a brief window of
time where another local user may snoop the msfrpcd password. In the
future, the password will be specified via TTY or file.