dnrops
/
metasploit-framework
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add documentation on debugging and running external python modules

This commit is contained in:
adfoster-r7 2023-03-20 17:12:43 +00:00
parent 158fae2a2c
commit 83cc0bf5a9
No known key found for this signature in database
GPG Key ID: 3BD4FA3818818F04
1 changed files with 94 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
docs/metasploit-framework.wiki/Writing-External-Python-Modules.md
View File

@ -169,6 +169,99 @@ if __name__ == '__main__':
```
The example sends a get request to the given `rhost` and `targeturi`, then calls `logging.info()` on the result to have the output displayed in msfconsole.
### Debugging Python modules
If you want to run an external module as a standalone program from your metasploit-framework folder just specify the Python path to include
the Metasploit library support and run the module directly:
```
$ PYTHONPATH=./lib/msf/core/modules/external/python:$PYTHONPATH python3 ./modules/auxiliary/scanner/wproxy/att_open_proxy.py
```
The Python module will wait for stdin to receive JSON-RPC input. Entering the request to run the module:
```jsonl
{ "jsonrpc": "2.0", "id": "1337", "method": "run", "params": { "rhosts": ["127.0.0.1"], "rport": "49152" } }
```
You will see the JSON-RPC responses printed to stdout:
```jsonl
{"jsonrpc": "2.0", "method": "message", "params": {"level": "debug", "message": "127.0.0.1:49152 - Connected"}}
{"jsonrpc": "2.0", "method": "message", "params": {"level": "debug", "message": "127.0.0.1:49152 - Received 5 bytes"}}
{"jsonrpc": "2.0", "method": "message", "params": {"level": "info", "message": "127.0.0.1:49152 - Does not match"}}
{"jsonrpc": "2.0", "method": "message", "params": {"level": "debug", "message": "127.0.0.1:49152 - Does not match with: bytearray(b'xxxxx')"}}
```
You can pipe the JSON-RPC request as well for automation purposes:
```
echo '{ "jsonrpc": "2.0", "id": "1337", "method": "run", "params": { "rhosts": ["127.0.0.1"], "rport": "49152" } }' | PYTHONPATH=./lib/msf/core/modules/external/python:$PYTHONPATH python3 ./modules/auxiliary/scanner/wproxy/att_open_proxy.py
```
The Python external modules can be run directly with command line options:
```
$ PYTHONPATH=./lib/msf/core/modules/external/python:$PYTHONPATH python3.9 ./modules/auxiliary/scanner/wproxy/att_open_proxy.py --help
usage: att_open_proxy.py [-h] --rhosts RHOSTS [--rport RPORT] [ACTION]
The Arris NVG589 and NVG599 routers configured with AT&T U-verse firmware 9.2.2h0d83 expose an un-authenticated proxy that allows connecting from WAN to LAN by MAC address.
positional arguments:
ACTION The action to take (['run'])
optional arguments:
-h, --help show this help message and exit
--rport RPORT The target port, (default: 49152)
required arguments:
--rhosts RHOSTS The target address
```
For example:
```
PYTHONPATH=./lib/msf/core/modules/external/python:$PYTHONPATH python3 ./modules/auxiliary/scanner/wproxy/att_open_proxy.py --rhosts 127.0.0.1 --rport 49152
```
For exploit modules, the payload is encoded encoded using Base64 and specified in a top level `payload_encoded` key, implemented [here](https://github.com/rapid7/metasploit-framework/blob/668735e4185968405c0073465f9aafbf62930538/lib/msf/core/modules/external/templates/remote_exploit.erb#L36-L39).
Below is an example of the ([now deleted](https://github.com/rapid7/metasploit-framework/pull/15217)) [ms17_010_eternalblue_win8.py](https://github.com/rapid7/metasploit-framework/blob/6dd298ebb76a1617e24da5e4c73e43a46b226a23/modules/exploits/windows/smb/ms17_010_eternalblue_win8.py) module running:
```
$ cat options.json
{
"jsonrpc": "2.0",
"id": "1337",
"method": "run",
"params": {
"VERBOSE": true,
"RHOST": "192.168.144.131",
"RPORT": "445",
"GroomAllocations": 13,
"ProcessName": "spoolsv.exe",
"SMBUser": "test",
"SMBPass": "123456",
"payload_encoded": "/EiD5PDozAAA...etc...==="
}
}
$ cat options.json | PYTHONPATH=./lib/msf/core/modules/external/python:$PYTHONPATH python3 modules/exploits/windows/smb/ms17_010_eternalblue_win8.py
{"jsonrpc": "2.0", "method": "message", "params": {"level": "info", "message": "shellcode size: 1221"}}
{"jsonrpc": "2.0", "method": "message", "params": {"level": "info", "message": "numGroomConn: 13"}}
{"jsonrpc": "2.0", "method": "message", "params": {"level": "info", "message": "Target OS: Windows 10 Pro 10240"}}
{"jsonrpc": "2.0", "method": "message", "params": {"level": "info", "message": "got good NT Trans response"}}
{"jsonrpc": "2.0", "method": "message", "params": {"level": "info", "message": "got good NT Trans response"}}
{"jsonrpc": "2.0", "method": "message", "params": {"level": "info", "message": "SMB1 session setup allocate nonpaged pool success"}}
{"jsonrpc": "2.0", "method": "message", "params": {"level": "info", "message": "SMB1 session setup allocate nonpaged pool success"}}
```
To add breakpoints to your Python code, add the below code snippet. Note that the interactive breakpoints will only work when
running the external modules as standalone Python scripts, and won't work when running from msfconsole:
```python
import pdb; pdb.pry
```
## Coding with Style
All the Python code in Metasploit aims to be [PEP 8](https://www.python.org/dev/peps/pep-0008/) compliant. The biggest differences coming from Metasploit's Ruby style:
@ -202,4 +295,4 @@ The external modules communicate with framework via JSON-RPC. If your Python mod
[Metasploit Python library](https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/modules/external/python/)
[ERB Templates](https://github.com/rapid7/metasploit-framework/tree/master/lib/msf/core/modules/external/templates)
[ERB Templates](https://github.com/rapid7/metasploit-framework/tree/master/lib/msf/core/modules/external/templates)