Standard API Methods Reference

The API methods below are available across all editions of the Metasploit product. All API functions use the naming convention <group>.<method>. All product editions share the basic API groups defined in the Metasploit Framework. Metasploit Pro provides a number of additional APIs for accessing the Pro features. For more information on the Pro APIs, see the Pro API Methods Reference.

For more insight on the standard APIs, check out the online developer documentation.

The authentication API provides methods for logging in and managing authentication tokens. The only API that can be accessed without a valid authentication token is auth.login, which in turn returns a token.

All API users are treated as administrative users and can trivially gain access to the underlying operating system. For this reason, you should always protect API keys as if they granted root access to the system on which Metasploit is running.

auth.login

The auth.login method allows a username and password to be supplied which in turn grants the caller with a temporary authentication token. This authentication token expires five minutes after the last request made with it.

Syntax

auth.login(String: Username, String: Password)

Successful Request Example

Client:

shell
1
[ "auth.login", "MyUserName", "MyPassword"]

Server:

json
1
{ "result" => "success", "token" => "a1a1a1a1a1a…" }

Unsuccessful Request Example

Client:

shell
1
[ "auth.login", "MyUserName", "BadPassword"]

Server:

json
1
{
2
"error" => true,
3
"error_class" => "Msf::RPC::Exception",
4
"error_message" => "Invalid User ID or Password"
5
}

auth.logout

The auth.logout method will remove the specified token from the authentication token list. Note that this method can be used to disable any temporary token, not just the one used by the current user. This method will still return "success" when a permanent token is specified, but the permanent token will not be removed.

Successful Request

Client:

shell
1
[ "auth.logout", "<token>", "<LogoutToken>"]

Server:

json
1
{ "result" => "success" }

Unsuccessful Request

Client:

shell
1
[ "auth.logout", "<token>", "BadToken"]

Server:

json
1
{
2
"error" => true,
3
"error_class" => "Msf::RPC::Exception",
4
"error_message" => "Invalid Authentication Token"
5
}

auth.token_add

The auth.token_add will add an arbitrary string as a valid permanent authentication token. This token can be used for all future authentication purposes. This method will never return an error, as collisions with an existing token of the same name will be ignored.

Client:

shell
1
[ "auth.token_add", "<token>", "<NewToken>"]

Server:

json
1
{ "result" => "success" }

auth.token_generate

The auth.token_generate method will create a random 32-byte authentication token, add this token to the authenticated list, and return this token to the caller. This method should never return an error if called with a valid authentication token.

Client:

shell
1
[ "auth.token_generate", "<token>"]

Server:

json
1
{ "result" => "success", "token" => "a1a1a1a1a1a…" }

auth.token_list

The auth.token_list method will return an array of all tokens, including both temporary tokens stored in memory and permanent tokens, stored either in memory or in the backend database. This method should never return an error if called with a valid authentication token.

Client:

shell
1
[ "auth.token_list", "<token>"]

Server:

json
1
{ "tokens" => [ "token1", "token2", "token3" ] }

auth.token_remove

The auth.token_remove method will delete a specified token. This will work for both temporary and permanent tokens, including those stored in the database backend. This method should never return an error if called with a valid authentication token.

Client:

shell
1
[ "auth.token_remove", "<token>", "<TokenToBeRemoved>"]

Server:

json
1
{ "result" => "success" }

The core API provides methods for managing global variables in the framework object, saving the current configuration to disk, manipulating the module load paths, reloading all modules, managing background threads, and retrieving the server version.

core.add_module_path

This method provides a way to add a new local file system directory (local to the server) as a module path. This can be used to dynamically load a separate module tree through the API. The path must be accessible to the user ID running the Metasploit service and contain a top-level directory for each module type (exploits, nop, encoder, payloads, auxiliary, post). Module paths will be immediately scanned for new modules and modules that loaded successfully will be immediately available. Note that this will not unload modules that were deleted from the file system since previously loaded (to remove all deleted modules, the core.reload_modules method should be used instead). This module may raise an error response if the specified path does not exist.

Client:

shell
1
[ "core.add_module_path", "<token>", "<Path>"]

Server:

json
1
{
2
'exploits' => 800,
3
'auxiliary' => 300,
4
'post' => 200,
5
'encoders' => 30,
6
'nops' => 25,
7
'payloads' => 250
8
}

core.module_stats

This method returns the number of modules loaded, broken down by type.

Client:

shell
1
[ "core.module_stats", "<token>"]

Server:

json
1
{
2
'exploits' => 800,
3
'auxiliary' => 300,
4
'post' => 200,
5
'encoders' => 30,
6
'nops' => 25,
7
'payloads' => 250
8
}

core.reload_modules

This method provides a way to dump and reload all modules from all configured module paths. This is the only way to purge a previously loaded module that the caller would like to remove. This method can take a long time to return, up to a minute on slow servers.

Client:

shell
1
[ "core.reload_modules", "<token>"]

Server:

json
1
{
2
'exploits' => 800,
3
'auxiliary' => 300,
4
'post' => 200,
5
'encoders' => 30,
6
'nops' => 25,
7
'payloads' => 250
8
}

core.save

This method causes the current global datastore of the framework instance to be stored to the server's disk, typically in ~/.msf3/config. This configuration will be loaded by default the next time Metasploit is started by that user on that server.

Client:

shell
1
[ "core.save", "<token>" ]

Server:

json
1
{ "result" => "success" }

core.setg

This method provides a way to set a global datastore value in the framework instance of the server. Examples of things that can be set include normal globals like LogLevel, but also the fallback for any modules launched from this point on. For example, the Proxies global option can be set, which would indicate that all modules launched from that point on should go through a specific chain of proxies, unless the Proxies option is specifically overridden for that module.

Client:

shell
1
[ "core.setg", "<token>", "<OptionName>", "<OptionValue>"]

Server:

json
1
{ "result" => "success" }

core.unsetg

This method is the counterpart to core.setg in that it provides a way to unset (delete) a previously configured global option.

Client:

shell
1
[ "core.unsetg", "<token>", "<OptionName>" ]

Server:

json
1
{ "result" => "success" }

core.thread_list

This method will return a list the status of all background threads along with an ID number that can be used to shut down the thread.

Client:

shell
1
[ "core.thread_list", "<token>"]

Server:

json
1
{
2
0 =>
3
{
4
  "status" => "sleep",
5
  "critical" => true,
6
  "name" => "SessionScheduler-1",
7
  "started" => "2011-05-29 15:36:03 -0500"
8
  },
9
  1 =>
10
  {
11
  "status" => "sleep",
12
  "critical" => true,
13
  "name" => "SessionScheduler-2",
14
  "started" => "2011-05-29 15:36:03 -0500"
15
}
16
}

core.thread_kill

This method can be used to kill an errant background thread. The ThreadID should match what was returned by the core.thread_list method. This method will still return success even if the specified thread does not exist.

Client:

shell
1
[ "core.thread_kill", "<token>", "<ThreadID>"]

Server:

json
1
{ "result" => "success" }

core.version

This method returns basic version information about the running framework instance, the Ruby interpreter, and the RPC protocol version being used.

Client:

shell
1
[ "core.version", "<token>"]

Server:

json
1
{
2
"version" => "4.0.0-release",
3
"ruby" => "1.9.1 x86_64-linux 2010-01-10",
4
"api" => "1.0"
5
}

core.stop

This method will result in the immediate shutdown of the Metasploit server. This should only be used in extreme cases where a better control mechanism is unavailable. Note that the caller may not even receive a response, depending on how fast the server is killed.

Client:

shell
1
[ "core.stop", "<token>"]

Server:

json
1
{ "result" => "success" }

The Console API provides the ability to allocate and work with the Metasploit Framework Console. In addition to being able to send commands and read output, these methods expose the tab completion backend as well being able to detach from and kill interactive sessions. Note that consoles provide the ability to do anything a local Metasploit Framework Console user may do, including running system commands.

console.create

The console.create method is used to allocate a new console instance. The server will return a Console ID ("id") that is required to read, write, and otherwise interact with the new console. The "prompt" element in the return value indicates the current prompt for the console, which may include terminal sequences. Finally, the "busy" element of the return value determines whether the console is still processing the last command (in this case, it always be false). Note that while Console IDs are currently integers stored as strings, these may change to become alphanumeric strings in the future. Callers should treat Console IDs as unique strings, not integers, wherever possible.

Client:

shell
1
[ "console.create", "<token>"]

Server:

json
1
{
2
"id" => "0",
3
"prompt" => "msf > ",
4
"busy" => false
5
}

console.destroy

The console.destroy method deletes a running console instance by Console ID. Consoles should always be destroyed after the caller is finished to prevent resource leaks on the server side. If an invalid Console ID is specified, the "result" element will be set to the string "failure" as opposed to "success".

Client:

shell
1
[ "console.destroy", "<token>", "ConsoleID"]

Server:

json
1
{ "result" => "success" }

console.list

The console.list method will return a hash of all existing Console IDs, their status, and their prompts.

Client:

shell
1
[ "console.list", "<token>"]

Server:

json
1
{
2
"0" => {
3
  "id" => "0",
4
  "prompt" => "msf exploit(\x01\x02\x01\x02handler\x01\x02) > ",
5
  "busy" => false
6
  },
7
"1" => {
8
  "id" => "1",
9
  "prompt" => "msf > ",
10
  "busy" => true
11
  }
12
}

console.write

The console.write method will send data to a specific console, just as if it had been typed by a normal user. This means that most commands will need a newline included at the end for the console to process them properly.

Client:

shell
1
[ "console.write", "<token>", "0", "version\n"]

Server:

json
1
{ "wrote" => 8 }

console.read

The console.read method will return any output currently buffered by the console that has not already been read. The data is returned in the raw form printed by the actual console. Note that a newly allocated console will have the initial banner available to read.

Client:

shell
1
[ "console.read", "<token>", "0"]

Server:

json
1
{
2
"data" => "Framework: 4.0.0-release.14644[..]\n",
3
"prompt" => "msf > ",
4
"busy" => false
5
}

console.session_detach

The console.session_detach method simulates the user using the Control+Z shortcut to background an interactive session in the Metasploit Framework Console. This method can be used to return to the main Metasploit prompt after entering an interactive session through a sessions –i console command or through an exploit.

Client:

shell
1
[ "console.session_detach", "<token>", "ConsoleID"]

Server:

json
1
{ "result" => "success" }

console.session_kill

The console.session_kill method simulates the user using the Control+C shortcut to abort an interactive session in the Metasploit Framework Console. This method should only be used after a sessions –i command has been written or an exploit was called through the Console API. In most cases, the session API methods are a better way to session termination, while the console.session_detach method is a better way to drop back to the main Metasploit console.

Client:

shell
1
[ "console.session_kill", "<token>", "ConsoleID"]

Server:

json
1
{ "result" => "success" }

console.tabs

The console.tabs command simulates the user hitting the tab key within the Metasploit Framework Console. This method will take a current line of input and return the tab completion options that would be available within the interactive console. This allows an API caller to emulate tab completion through this interface. For example, setting the InputLine to "hel" for a newly allocated console returns a single element array with the option help.

Client:

shell
1
[ "console.tabs", "<token>", "ConsoleID", "InputLine"]

Server:

json
1
{ "tabs" => [ "option1", "option2", "option3" }

The Jobs API provides methods for listing jobs, obtaining more information about a specific job, and killing specific jobs. These methods equate the jobs command in the Metasploit Framework Console. Jobs are typically used to manage background modules.

job.list

The job.list method will return a hash, keyed by Job ID, of every active job. The Job ID is required to terminate or obtain more information about a specific job.

Client:

shell
1
[ "job.list", "<token>"]

Server:

json
1
{ "0" => "Exploit: windows/browser/ms03_020_ie_objecttype" }

job.info

The job.info method will return additional data about a specific job. This includes the start time and complete datastore of the module associated with the job.

Client:

shell
1
[ "job.info", "<token>", "JobID"]

Server:

json
1
{
2
"jid" => 0,
3
"name" => "Exploit: windows/browser/ms03_020_ie_objecttype",
4
"start_time" => 1306708444,
5
"uripath" => "/aHdzfE1i3v",
6
"datastore" => {
7
  "EnableContextEncoding" => false,
8
  "DisablePayloadHandler" => false,
9
  "SSL" => false,
10
  "SSLVersion" => "SSL3",
11
  "SRVHOST" => "0.0.0.0",
12
  "SRVPORT" => "8080",
13
  "PAYLOAD" => "windows/meterpreter/reverse_tcp",
14
  "LHOST" => "192.168.35.149",
15
  "LPORT"=>"4444"
16
  }
17
}

job.stop

The job.stop method will terminate the job specified by the Job ID.

Client:

shell
1
[ "job.stop", "<token>", "JobID"]

Server:

json
1
{ "result" => "success" }

The Modules API provides the ability to list modules, enumerate their options, identify compatible payloads, and actually run them. All module types share the same API group and the module type is passed in as a parameter when the request would be ambiguous otherwise.

module.exploits

The module.exploits method returns a list of all loaded exploit modules in the framework instance. Note that the exploit/ prefix is not included in the path name of the return module.

Client:

shell
1
[ "module.exploits", "<token>" ]

Server:

json
1
{ "modules" => [
2
  "linux/pop3/cyrus_pop3d_popsubfolders",
3
  "linux/ids/snortbopre",
4
  […]
5
  ]
6
}

module.auxiliary

The module.auxiliary method returns a list of all loaded auxiliary modules in the framework instance. Note that the auxiliary/ prefix is not included in the path name of the return module.

Client:

shell
1
[ "module.auxiliary", "<token>" ]

Server:

json
1
{ "modules" => [
2
  "pdf/foxit/authbypass",
3
  "admin/motorola/wr850g_cred",
4
  "admin/oracle/post_exploitation/win32exec"
5
  […]
6
  ]
7
}

module.post

The module.post method returns a list of all loaded post modules in the framework instance. Note that the post/ prefix is not included in the path name of the return module.

Client:

shell
1
[ "module.post", "<token>" ]

Server:

json
1
{ "modules" => [
2
  "multi/gather/env",
3
  "windows/escalate/bypassuac",
4
  […]
5
  ]
6
}

module.payloads

The module.payloads method returns a list of all loaded payload modules in the framework instance. Note that the payload/ prefix is not included in the path name of the return module.

Client:

shell
1
[ "module.payloads", "<token>" ]

Server:

json
1
{ "modules" => [
2
  "linux/armle/exec",
3
  "linux/armle/shell_reverse_tcp",
4
  […]
5
  ]
6
}

module.encoders

The module.encoders method returns a list of all loaded encoder modules in the framework instance. Note that the encoder/ prefix is not included in the path name of the return module.

Client:

shell
1
[ "module.encoders", "<token>" ]

Server:

json
1
{ "modules" => [
2
  "mipsbe/longxor",
3
  "sparc/longxor_tag",
4
  […]
5
  ]
6
}

module.nops

The module.nops method returns a list of all loaded nop modules in the framework instance. Note that the nop/ prefix is not included in the path name of the return module.

Client:

shell
1
[ "module.nops", "<token>" ]

Server:

json
1
{ "modules" => [
2
  "armle/simple",
3
  "sparc/random",
4
  […]
5
  ]
6
}

module.info

The module.info method returns a hash of detailed information about the specified module. The ModuleType should be one "exploit", "auxiliary", "post", "payload", "encoder", and "nop". The ModuleName can either include module type prefix (exploit/) or not.

Client:

shell
1
[ "module.info", "<token>", "ModuleType", "ModuleName" ]

Server:

json
1
{
2
"name" => "SPARC NOP generator",
3
"description" => "SPARC NOP generator",
4
"license" => "Metasploit Framework License (BSD)",
5
"filepath" => "<msf>/modules/nops/sparc/random.rb",
6
"version" => "10394",
7
"rank" => 300,
8
"references" => [],
9
"authors" => [ "vlad902 <vlad902@gmail.com>" ]
10
}

module.options

The module.options method returns a hash of datastore options for the specified module. The ModuleType should be one "exploit", "auxiliary", "post", "payload", "encoder", and "nop". The ModuleName can either include module type prefix (exploit/) or not.

Client:

shell
1
[ "module.options", "<token>", "ModuleType", "ModuleName" ]

Server:

json
1
{
2
"SSL"=> {
3
  "type" => "bool",
4
  "required" => false,
5
  "advanced" => true,
6
  "evasion" => false,
7
  "desc" => "Negotiate SSL for outgoing connections",
8
  "default" => false
9
  },
10
"SSLVersion" => {
11
  "type" => "enum",
12
  "required" => false,
13
  "advanced" => true,
14
  "evasion" => false,
15
  "desc" => "Specify the version…",
16
  "default" => "SSL3",
17
  "enums" => [ "SSL2", "SSL3", "TLS1" ]
18
  }
19
}

module.compatible_payloads

The module.compatible_payloads method returns a list of payloads that are compatible with the exploit module name specified.

Client:

shell
1
[ "module.compatible_payloads", "<token>", "ModuleName" ]

Server:

json
1
{
2
"payloads" => [
3
  "generic/debug_trap",
4
  "generic/shell_bind_tcp",
5
  "generic/shell_reverse_tcp"
6
  ]
7
}

module.target_compatible_payloads

The module.target_compatible_payloads method is similar to the module.compatible_payloads method in that it returns a list of matching payloads, however, it restricts those payloads to those that will work for a specific exploit target. For exploit modules that can attack multiple platforms and operating systems, this is the method used to obtain a list of available payloads after a target has been chosen.

Client:

shell
1
[ "module.target_compatible_payloads", "<token>", "ModuleName", 1 ]

Server:

json
1
{
2
"payloads" => [
3
  "generic/debug_trap",
4
  "generic/shell_bind_tcp",
5
  "generic/shell_reverse_tcp"
6
  ]
7
}

module.compatible_sessions

The module.compatible_sessions method returns a list of payloads that are compatible with the post module name specified.

Client:

shell
1
[ "module.compatible_sessions", "<token>", "ModuleName" ]

Server:

json
1
{ "sessions" => [
2
  "1",
3
  "2"
4
  ]
5
}

module.encode( String: Data, String: EncoderModule, Hash: Options )

The module.encode method provides a way to encode an arbitrary payload (specified as Data) with a specific encoder and set of options. The available options include:

• format – This option can be used to specify an output format, such as "exe", "vbs", or "raw".
• badchars – This option can be used to specify a list of raw bytes to avoid in the encoding.
• platform – This option can be used to set the operating system platform of the encoder.
• arch – This option can be used to set the architecture of the encoder.
• ecount – This option specifies the number of encoding passes to be done.

For "exe" format, the following additional options are available:

• altexe – The name of a specific executable template file to use for the output file.
• exedir – The name of an alternate directory of templates to consult for the output file.
• inject – A boolean indicating whether to inject the payload as new thread.

Client:

shell
1
[ "module.encode", "<token>", "Data", "EncoderModule", {
2
  "Option1" => "Value1",
3
  "Option2" => "Value2"
4
  }
5
]

Server:

json
1
{ "encoded" => "<raw output data>" }

module.execute

The module.execute method provides a way to launch an exploit, run an auxiliary module, trigger a post module on a session, or generate a payload. The ModuleType should be one "exploit", "auxiliary", "post", and "payload". The ModuleName can either include module type prefix (exploit/) or not. The Datastore is the full set of datastore options that should be applied to the module before executing it.

In the case of exploits, auxiliary, or post modules, the server response will return the Job ID of the running module:

Client:

shell
1
[ "module.execute", "<token>", "ModuleType", "ModuleName", {
2
  "RHOST" => "1.2.3.4",
3
  "RPORT" => "80"
4
  }
5
]

Server:

json
1
{ "job_id" => 1 }

In the case of payload modules, a number of additional options are parsed, including the datastore for the payload itself. These options are:

• BadChars – The raw list of bytes that needed to be encoded out of the payload
• Format – The output format that the payload should be converted to ("exe", "ruby", "c")
• ForceEncoding – A boolean indicating whether encoding should be done even if bytes are OK
• Template – The path to a template file for EXE output
• Platform – The operating system platform for the encoder
• KeepTemplateWorking – A boolean indicating whether to inject a new thread or not
• NopSledSize – The size of the prefixed mandatory nop sled (default is 0)
• Iterations – The number of encoding rounds to go through

The response consists of the raw payload data:

Client:

shell
1
[ "module.execute", "<token>", "ModuleType", "ModuleName", {
2
  "LHOST" => "4.3.2.1",
3
  "LPORT" => "4444"
4
  }
5
]

Server:

json
1
{ "payload" => "<raw payload data>" }

The Plugin API provides the ability to load, unload, and list loaded plugins.

plugin.load

The plugin.load method will load the specified plugin in the framework instance. The Options parameter can be used to specify initialization options to the plugin. The individual options are different for each plugin. A failed load will cause this method to return a "result" value of "failure".

Client:

shell
1
[ "plugin.load", "<token>", "PluginName", {
2
  "Option1" => "Value1",
3
  "Option2" => "Value2"
4
  }
5
]

Server:

json
1
{ "result" => "success" }

plugin.unload

The plugin.unload method will unload a previously loaded plugin by name. The name is not always identical to the string used to load the plugin in the first place, so callers should check the output of plugin.loaded when there is any confusion. A failed load will cause this method to return a "result" value of "failure".

Client:

shell
1
[ "plugin.unload", "<token>", "PluginName" ]

Server:

json
1
{ "result" => "success" }

plugin.loaded

The plugin.loaded method will enumerate all currently loaded plugins.

Client:

shell
1
[ "plugin.loaded", "<token>" ]

Server:

json
1
{ "plugins" => [ "plugin1", "plugin2", "plugin3" ] }

The Sessions API is used to list, interact with, and terminate open sessions to compromised systems. The Session ID returned by session.list is used to unique identify a given session. Note that the database IDs used to identify sessions in the Metasploit Pro user interface are translated to a framework instance-local Session ID for use by this API.

session.list

This method will list all active sessions in the framework instance.

Client:

shell
1
[ "session.list", "<token>" ]

Server:

json
1
{
2
"1" => {
3
  'type' => "shell",
4
  "tunnel_local" => "192.168.35.149:44444",
5
  "tunnel_peer" => "192.168.35.149:43886",
6
  "via_exploit" => "exploit/multi/handler",
7
  "via_payload" => "payload/windows/shell_reverse_tcp",
8
  "desc" => "Command shell",
9
  "info" => "",
10
  "workspace" => "Project1",
11
  "target_host" => "",
12
  "username" => "root",
13
  "uuid" => "hjahs9kw",
14
  "exploit_uuid" => "gcprpj2a",
15
  "routes" => [ ]
16
  }
17
}

session.stop

The session.stop method will terminate the session specified in the SessionID parameter.

Client:

shell
1
[ "session.stop", "<token>", "SessionID" ]

Server:

json
1
{ "result" => "success" }

session.shell_read

The shell.read method provides the ability to read output from a shell session. As of version 3.7.0, shell sessions also ring buffer their output, allowing multiple callers to read from one session without losing data. This is implemented through the optional ReadPointer parameter. If this parameter is not given (or set to 0), the server will reply with all buffered data and a new ReadPointer (as the "seq" element of the reply). If the caller passes this ReadPointer into subsequent calls to shell.read, only data since the previous read will be returned. By continuing to track the ReadPointer returned by the last call and pass it into the next call, multiple readers can all follow the output from a single session without conflict.

Client:

shell
1
[ "session.shell_read", "<token>", "SessionID", "ReadPointer ]

Server:

json
1
{
2
"seq" => "32",
3
"data" => "uid=0(root) gid=0(root)…"
4
}

session.shell_write

The shell.write method provides the ability to write data into an active shell session.

Most sessions require a terminating newline before they will process a command.

Client:

shell
1
[ "session.shell_write", "<token>", "SessionID", "id\n" ]

Server:

json
1
{ "write_count" => "3" }

session.meterpreter_write

The session.meterpeter_write method provides the ability write commands into the Meterpreter Console. This emulates how a user would interact with a Meterpreter session from the Metasploit Framework Console. Note that multiple concurrent callers writing and reading to the same Meterpreter session through this method can lead to a conflict, where one caller gets the others output and vice versa. Concurrent access to a Meterpreter session is best handled by running Post modules or Scripts. A newline does not need to be specified unless the console is currently tied to an interactive channel, such as a sub-shell.

Client:

shell
1
[ "session.meterpreter_write", "<token>", "SessionID", "ps" ]

Server:

json
1
{ "result" => "success" }

session.meterpreter_read

The session.meterpreter_read method provides the ability to read pending output from a Meterpreter session console. As noted in the session.meterpreter_write documentation, this method is problematic when it comes to concurrent access by multiple callers and Post modules or Scripts should be used instead.

Client:

shell
1
[ "session.meterpreter_read", "<token>", "SessionID"]

Server:

json
1
{ "data" => "<raw console output>" }

session.meterpreter_run_single

The session.meterpreter_run_single method provides the ability to run a single Meterpreter console command. This method does not need be terminated by a newline. The advantage to session.meterpreter_run_single over session.meterpreter_write is that this method will always run the Meterpreter command, even if the console tied to this sessions is interacting with a channel.

Client:

shell
1
[ "session.meterpreter_run_single", "<token>", "SessionID", "ps" ]

Server:

json
1
{ "result" => "success" }

session.meterpreter_script

The session.meterpreter_script method provides the ability to run a Meterpreter script on the specified session. This method does not provide a way to specify arguments for a script, but the session.metepreter_run_single method can handle this case.

Client:

shell
1
["session.meterpreter_script","<token>","SessionID","scriptname"]

Server:

json
1
{"result"=>"success"}Server: { "result" => "success" }

session.meterpreter_session_detach

The session.meterpreter_session_detach method stops any current channel or sub-shell interaction taking place by the console associated with the specified Meterpreter session. This simulates the console user pressing the Control+Z hotkey.

Client:

shell
1
[ "session.meterpreter_session_detach", "<token>", "SessionID" ]

Server:

json
1
{ "result" => "success" }

session.meterpreter_session_kill

The session.meterpreter_session_kill method terminates the current channel or sub-shell that the console associated with the specified Meterpreter session is interacting with. This simulates the console user pressing the Control+C hotkey.

Client:

shell
1
[ "session.meterpreter_session_detach", "<token>", "SessionID" ]

Server:

json
1
{ "result" => "success" }

session.meterpreter_tabs

The session.meterpreter_tabs command simulates the user hitting the tab key within the Meterpreter Console. This method will take a current line of input and return the tab completion options that would be available within the interactive console. This allows an API caller to emulate tab completion through this interface. For example, setting the InputLine to "hel" for a newly allocated console returns a single element array with the option help.

Client:

shell
1
[ "session.meterpreter_tabs", "<token>", "SessionID", "InputLine"]

Server:

json
1
{ "tabs" => [ "option1", "option2", "option3" }

session.compatible_modules

The session.compatible_modules method returns a list of Post modules that are compatible with the specified session. This includes matching Meterpreter Post modules to Meterpreter sessions and enforcing platform and architecture restrictions.

Client:

shell
1
[ "session.compatible_modules", "<token>", "SessionID" ]

Server:

json
1
{ "modules" => [ "multi/gather/env" ] }

session.shell_upgrade

The session.shell_upgrade method will attempt to spawn a new Meterpreter session through an existing Shell session. This requires that a multi/handler be running (windows/meterpreter/reverse_tcp) and that the host and port of this handler is provided to this method.

Client:

shell
1
[ "session.shell_upgrade", "<token>", "SessionID", "1.2.3.4", 4444 ]

Server:

json
1
{ "result" => "success" }

session.ring_clear

The session.ring_clear method will wipe out the ring buffer associated with a specific shell session. This may be useful to reclaim memory for idle background sessions.

Client:

shell
1
[ "session.ring_clear", "<token>", "SessionID" ]

Server:

json
1
{ "result" => "success" }

session.ring_last

The session.ring_last method will return the last issued ReadPointer (sequence number) for the specified Shell session.

Client:

shell
1
[ "session.ring_last", "<token>", "SessionID" ]

Server:

json
1
{ "seq" => 112 }

session.ring_put

The session.ring_put method provides the ability to write data into an active shell session.

Most sessions require a terminating newline before they will process a command.

Client:

shell
1
[ "session.ring_put", "<token>", "SessionID", "id\n" ]

Server:

json
1
{ "write_count" => "3" }