adam/metasploit-gs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c3f5bd3de2d1affa01e2f6c2066c6bb0fc6413bc
metasploit-gs/docs/development/developing-modules/external-modules/writing-external-python-modules.html
T
jenkins-metasploit c3f5bd3de2 Reboot gh-pages
2026-05-08 17:08:43 +00:00

151 lines
81 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html><html lang="en-US"><head><meta charset="UTF-8"><meta http-equiv="X-UA-Compatible" content="IE=Edge"><link rel="shortcut icon" href="/assets/images/favicon.png" type="image/x-icon"><link rel="stylesheet" href="/assets/css/just-the-docs-default.css"> <script async src="https://www.googletagmanager.com/gtag/js?id=UA-4622520-7"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-4622520-7', { 'anonymize_ip': true }); </script> <script type="text/javascript" src="/assets/js/vendor/lunr.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/mermaid@10.8.0/dist/mermaid.min.js"></script> <script type="text/javascript" src="/assets/js/just-the-docs.js"></script><meta name="viewport" content="width=device-width, initial-scale=1"><title>Writing Python Modules | Metasploit Documentation Penetration Testing Software, Pen Testing Security</title><meta name="generator" content="Jekyll v4.3.4" /><meta property="og:title" content="Writing Python Modules" /><meta property="og:locale" content="en_US" /><meta name="description" content="View Metasploit Framework Documentation" /><meta property="og:description" content="View Metasploit Framework Documentation" /><link rel="canonical" href="https://rapid7.github.io/metasploit-framework/docs/development/developing-modules/external-modules/writing-external-python-modules.html" /><meta property="og:url" content="https://rapid7.github.io/metasploit-framework/docs/development/developing-modules/external-modules/writing-external-python-modules.html" /><meta property="og:site_name" content="Metasploit Documentation Penetration Testing Software, Pen Testing Security" /><meta property="og:type" content="website" /><meta name="twitter:card" content="summary" /><meta property="twitter:title" content="Writing Python Modules" /> <script type="application/ld+json"> {"@context":"https://schema.org","@type":"WebPage","description":"View Metasploit Framework Documentation","headline":"Writing Python Modules","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://rapid7.github.io/metasploit-framework/assets/images/favicon.png"}},"url":"https://rapid7.github.io/metasploit-framework/docs/development/developing-modules/external-modules/writing-external-python-modules.html"}</script><body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-link" viewBox="0 0 24 24"><title>Link</title><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path> </svg> </symbol> <symbol id="svg-search" viewBox="0 0 24 24"><title>Search</title><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search"> <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"><title>Menu</title><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"><line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"><title>Expand</title><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right"><polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-doc" viewBox="0 0 24 24"><title>Document</title><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file"><path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline> </svg> </symbol> </svg> <script type="text/javascript" src="/assets/js/toggle_init.js"></script><div class="side-bar"><div class="site-header"> <a href="/" class="site-title lh-tight"><img src="/assets/images/metasploit-logo-dark-external-use.svg" alt="Metasploit Logo" class="title-logo" /> </a> <a href="#" id="menu-button" class="site-button"> <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg> </a></div><nav role="navigation" aria-label="Main" id="site-nav" class="site-nav"><ul class="nav-list"><li class="nav-list-item active"><a href="/" class="nav-list-link">Home</a><li class="nav-list-item active"><a href="/docs/code-of-conduct.html" class="nav-list-link">Code Of Conduct</a><li class="nav-list-item active"><a href="/docs/modules.html" class="nav-list-link">Modules</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/pentesting/" class="nav-list-link">Pentesting</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-setting-module-options.html" class="nav-list-link">Setting Module Options</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-upgrading-shells-to-meterpreter.html" class="nav-list-link">Upgrading Shells to Meterpreter</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-post-gather-modules.html" class="nav-list-link">Post Gather Modules</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-http.html" class="nav-list-link">HTTP + HTTPS</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-kubernetes.html" class="nav-list-link">Kubernetes</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-mysql.html" class="nav-list-link">MySQL</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-postgresql.html" class="nav-list-link">PostgreSQL</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-smb.html" class="nav-list-link">SMB</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-ssh.html" class="nav-list-link">SSH</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-winrm.html" class="nav-list-link">WinRM</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-mssql.html" class="nav-list-link">MSSQL</a><li class="nav-list-item active"><a href="/docs/pentesting/metasploit-guide-ldap.html" class="nav-list-link">LDAP</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/pentesting/active-directory/" class="nav-list-link">Active Directory</a><ul class="nav-list"><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/pentesting/active-directory/ad-certificates/" class="nav-list-link">AD CS</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/ad-certificates/overview.html" class="nav-list-link">Overview</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/ad-certificates/attacking-ad-cs-esc-vulnerabilities.html" class="nav-list-link">Attacking AD CS ESC Vulnerabilities Using Metasploit</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/ad-certificates/ldap_esc_vulnerable_cert_finder.html" class="nav-list-link">Vulnerable cert finder</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/ad-certificates/ad_cs_cert_template.html" class="nav-list-link">Manage certificate templates</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/ad-certificates/icpr_cert.html" class="nav-list-link">Request certificates</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/pentesting/active-directory/kerberos/" class="nav-list-link">Kerberos</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/overview.html" class="nav-list-link">Overview</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/service_authentication.html" class="nav-list-link">Authenticating to SMB/WinRM/etc</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/kerberos_login.html" class="nav-list-link">Kerberos login enumeration and bruteforcing</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/get_ticket.html" class="nav-list-link">Get Ticket granting tickets and service tickets</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/ticket_converter.html" class="nav-list-link">Converting kirbi and ccache files</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/forge_ticket.html" class="nav-list-link">Forging tickets</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/inspect_ticket.html" class="nav-list-link">Inspecting tickets</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/kerberoasting.html" class="nav-list-link">Kerberoasting</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/keytab.html" class="nav-list-link">Keytab support and decrypting wireshark traffic</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/rbcd.html" class="nav-list-link">Resource-based constrained delegation (RBCD)</a><li class="nav-list-item active"><a href="/docs/pentesting/active-directory/kerberos/unconstrained_delegation.html" class="nav-list-link">Unconstrained delegation</a></ul></ul></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/using-metasploit/" class="nav-list-link">Using Metasploit</a><ul class="nav-list"><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/using-metasploit/getting-started/" class="nav-list-link">Getting Started</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/using-metasploit/getting-started/nightly-installers.html" class="nav-list-link">Nightly Installers</a><li class="nav-list-item active"><a href="/docs/using-metasploit/getting-started/reporting-a-bug.html" class="nav-list-link">Reporting a Bug</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/using-metasploit/basics/" class="nav-list-link">Basics</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/using-metasploit/basics/using-metasploit.html" class="nav-list-link">Running modules</a><li class="nav-list-item active"><a href="/docs/using-metasploit/basics/how-to-use-a-metasploit-module-appropriately.html" class="nav-list-link">How to use a Metasploit module appropriately</a><li class="nav-list-item active"><a href="/docs/using-metasploit/basics/how-payloads-work.html" class="nav-list-link">How payloads work</a><li class="nav-list-item active"><a href="/docs/using-metasploit/basics/module-documentation.html" class="nav-list-link">Module Documentation</a><li class="nav-list-item active"><a href="/docs/using-metasploit/basics/how-to-use-a-reverse-shell-in-metasploit.html" class="nav-list-link">How to use a reverse shell in Metasploit</a><li class="nav-list-item active"><a href="/docs/using-metasploit/basics/how-to-use-msfvenom.html" class="nav-list-link">How to use msfvenom</a><li class="nav-list-item active"><a href="/docs/using-metasploit/basics/managing-sessions.html" class="nav-list-link">Managing Sessions</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/using-metasploit/intermediate/" class="nav-list-link">Intermediate</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/using-metasploit/intermediate/metasploit-database-support.html" class="nav-list-link">Database Support</a><li class="nav-list-item active"><a href="/docs/using-metasploit/intermediate/evading-anti-virus.html" class="nav-list-link">Evading Anti Virus</a><li class="nav-list-item active"><a href="/docs/using-metasploit/intermediate/exploit-ranking.html" class="nav-list-link">Exploit Ranking</a><li class="nav-list-item active"><a href="/docs/using-metasploit/intermediate/hashes-and-password-cracking.html" class="nav-list-link">Hashes and Password Cracking</a><li class="nav-list-item active"><a href="/docs/using-metasploit/intermediate/how-to-use-plugins.html" class="nav-list-link">Metasploit Plugins</a><li class="nav-list-item active"><a href="/docs/using-metasploit/intermediate/payload-uuid.html" class="nav-list-link">Payload UUID</a><li class="nav-list-item active"><a href="/docs/using-metasploit/intermediate/pivoting-in-metasploit.html" class="nav-list-link">Pivoting in Metasploit</a><li class="nav-list-item active"><a href="/docs/using-metasploit/intermediate/running-private-modules.html" class="nav-list-link">Running Private Modules</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/using-metasploit/advanced/" class="nav-list-link">Advanced</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/how-to-configure-dns.html" class="nav-list-link">How to Configure DNS</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/metasploit-web-service.html" class="nav-list-link">Metasploit Web Service</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/using-metasploit/advanced/meterpreter/" class="nav-list-link">Meterpreter</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter.html" class="nav-list-link">Overview</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-configuration.html" class="nav-list-link">Configuration</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/debugging-dead-meterpreter-sessions.html" class="nav-list-link">Debugging Dead Meterpreter Sessions</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-debugging-meterpreter-sessions.html" class="nav-list-link">Debugging Meterpreter Sessions</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-executebof-command.html" class="nav-list-link">ExecuteBof Command</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-http-communication.html" class="nav-list-link">HTTP Communication</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/how-to-get-started-with-writing-a-meterpreter-script.html" class="nav-list-link">How to get started with writing a Meterpreter script</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-paranoid-mode.html" class="nav-list-link">Paranoid Mode</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/powershell-extension.html" class="nav-list-link">Powershell Extension</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/python-extension.html" class="nav-list-link">Python Extension</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-reg-command.html" class="nav-list-link">Reg Command</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-reliable-network-communication.html" class="nav-list-link">Reliable Network Communication</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-sleep-control.html" class="nav-list-link">Sleep Control</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-stageless-mode.html" class="nav-list-link">Stageless Mode</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/the-ins-and-outs-of-http-and-https-communications-in-meterpreter-and-metasploit-stagers.html" class="nav-list-link">The ins and outs of HTTP and HTTPS communications in Meterpreter and Metasploit Stagers</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-timeout-control.html" class="nav-list-link">Timeout Control</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-transport-control.html" class="nav-list-link">Transport Control</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-unicode-support.html" class="nav-list-link">Unicode Support</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/meterpreter/meterpreter-wishlist.html" class="nav-list-link">Wishlist</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/using-metasploit/advanced/RPC/" class="nav-list-link">RPC</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/RPC/how-to-use-metasploit-json-rpc.html" class="nav-list-link">How to use Metasploit JSON RPC</a><li class="nav-list-item active"><a href="/docs/using-metasploit/advanced/RPC/how-to-use-metasploit-messagepack-rpc.html" class="nav-list-link">How to use Metasploit Messagepack RPC</a></ul></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/using-metasploit/other/" class="nav-list-link">Other</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/using-metasploit/other/how-to-use-metasploit-mcp-server.html" class="nav-list-link">How to use Metasploit MCP Server</a><li class="nav-list-item active"><a href="/docs/using-metasploit/other/how-to-use-metasploit-with-ngrok.html" class="nav-list-link">How to use Metasploit with ngrok</a><li class="nav-list-item active"><a href="/docs/using-metasploit/other/how-to-use-the-favorite-command.html" class="nav-list-link">How to use the Favorite command</a><li class="nav-list-item active"><a href="/docs/using-metasploit/other/information-about-unmet-browser-exploit-requirements.html" class="nav-list-link">Information About Unmet Browser Exploit Requirements</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/using-metasploit/other/oracle-support/" class="nav-list-link">Oracle Support</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/using-metasploit/other/oracle-support/how-to-get-oracle-support-working-with-kali-linux.html" class="nav-list-link">How to get Oracle Support working with Kali Linux</a><li class="nav-list-item active"><a href="/docs/using-metasploit/other/oracle-support/oracle-usage.html" class="nav-list-link">Oracle Usage</a></ul><li class="nav-list-item active"><a href="/docs/using-metasploit/other/why-cve-is-not-available.html" class="nav-list-link">Why CVE is not available</a></ul></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/" class="nav-list-link active">Development</a><ul class="nav-list"><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/get-started/" class="nav-list-link">Get Started</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/get-started/contributing-to-metasploit.html" class="nav-list-link">Contributing to Metasploit</a><li class="nav-list-item active"><a href="/docs/development/get-started/creating-your-first-pr.html" class="nav-list-link">Creating Your First PR</a><li class="nav-list-item active"><a href="/docs/development/get-started/setting-up-a-metasploit-development-environment.html" class="nav-list-link">Setting Up a Metasploit Development Environment</a><li class="nav-list-item active"><a href="/docs/development/get-started/sanitizing-pcaps.html" class="nav-list-link">Sanitizing PCAPs</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/get-started/git/" class="nav-list-link">Git</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/get-started/git/git-reference-sites.html" class="nav-list-link">Git Reference Sites</a><li class="nav-list-item active"><a href="/docs/development/get-started/git/git-cheatsheet.html" class="nav-list-link">Git cheatsheet</a><li class="nav-list-item active"><a href="/docs/development/get-started/git/keeping-in-sync-with-rapid7-master.html" class="nav-list-link">Keeping in sync with rapid7 master</a><li class="nav-list-item active"><a href="/docs/development/get-started/git/remote-branch-pruning.html" class="nav-list-link">Remote Branch Pruning</a><li class="nav-list-item active"><a href="/docs/development/get-started/git/using-git.html" class="nav-list-link">Using Git</a></ul><li class="nav-list-item active"><a href="/docs/development/get-started/navigating-and-understanding-metasploits-codebase.html" class="nav-list-link">Navigating the codebase</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/" class="nav-list-link active">Developing Modules</a><ul class="nav-list"><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/guides/" class="nav-list-link">Guides</a><ul class="nav-list"><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/guides/scanners/" class="nav-list-link">Scanners</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/scanners/how-to-write-a-http-loginscanner-module.html" class="nav-list-link">Writing a HTTP LoginScanner</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/scanners/creating-metasploit-framework-loginscanners.html" class="nav-list-link">Writing an FTP LoginScanner</a></ul><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/how-to-check-microsoft-patch-levels-for-your-exploit.html" class="nav-list-link">How to check Microsoft patch levels for your exploit</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/how-to-use-fetch-payloads.html" class="nav-list-link">How to use Fetch Payloads</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/how-to-use-command-stagers.html" class="nav-list-link">How to use command stagers</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/how-to-write-a-check-method.html" class="nav-list-link">How to write a check method</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/how-to-write-a-cmd-injection-module.html" class="nav-list-link">How to write a cmd injection module</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/how-to-write-a-browser-exploit-using-httpserver.html" class="nav-list-link">Writing a browser exploit</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/how-to-get-started-with-writing-a-post-module.html" class="nav-list-link">Writing a post module</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/how-to-get-started-with-writing-an-auxiliary-module.html" class="nav-list-link">Writing an auxiliary module</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/guides/get-started-writing-an-exploit.html" class="nav-list-link">Writing an exploit</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/external-modules/" class="nav-list-link active">External Modules</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/developing-modules/external-modules/writing-external-metasploit-modules.html" class="nav-list-link">Overview</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/external-modules/writing-external-golang-modules.html" class="nav-list-link">Writing GoLang Modules</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/external-modules/writing-external-python-modules.html" class="nav-list-link active">Writing Python Modules</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/module-metadata/" class="nav-list-link">Module metadata</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/developing-modules/module-metadata/definition-of-module-reliability-side-effects-and-stability.html" class="nav-list-link">Definition of Module Reliability Side Effects and Stability</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/module-metadata/how-to-use-datastore-options.html" class="nav-list-link">How to use datastore options</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/module-metadata/module-reference-identifiers.html" class="nav-list-link">Module Reference Identifiers</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/libraries/" class="nav-list-link">Libraries</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/api.html" class="nav-list-link">API</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-use-msf-auxiliary-authbrute-to-write-a-bruteforcer.html" class="nav-list-link">AuthBrute</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-cleanup-after-module-execution.html" class="nav-list-link">Cleanup</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/libraries/c/" class="nav-list-link">Compiling C</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/c/how-to-use-metasploit-framework-compiler-windows-to-compile-c-code.html" class="nav-list-link">Overview</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/c/how-to-decode-base64-with-metasploit-framework-compiler.html" class="nav-list-link">Base64 Support</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/c/how-to-decrypt-rc4-with-metasploit-framework-compiler.html" class="nav-list-link">RC4 Support</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/c/how-to-xor-with-metasploit-framework-compiler.html" class="nav-list-link">XOR Support</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/libraries/deserialization/" class="nav-list-link">Deserialization</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/deserialization/dot-net-deserialization.html" class="nav-list-link">Dot Net Deserialization</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/deserialization/generating-ysoserial-java-serialized-objects.html" class="nav-list-link">Java Deserialization</a></ul><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/handling-module-failures-with-fail_with.html" class="nav-list-link">Fail_with</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-use-the-fileformat-mixin-to-create-a-file-format-exploit.html" class="nav-list-link">Fileformat</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-use-the-git-mixin-to-write-an-exploit-module.html" class="nav-list-link">Git Mixin</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/libraries/http/" class="nav-list-link">HTTP</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/http/how-to-write-a-browser-exploit-using-browserexploitserver.html" class="nav-list-link">BrowserExploitServer</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/http/how-to-send-an-http-request-using-httpclient.html" class="nav-list-link">How to Send an HTTP Request Using HttpClient</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/http/how-to-parse-an-http-response.html" class="nav-list-link">How to parse an HTTP response</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/http/how-to-send-an-http-request-using-rex-proto-http-client.html" class="nav-list-link">How to send an HTTP request using Rex Proto Http Client</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/http/how-to-write-a-module-using-httpserver-and-httpclient.html" class="nav-list-link">How to write a module using HttpServer and HttpClient</a></ul><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-log-in-metasploit.html" class="nav-list-link">Logging</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/libraries/obfuscation/" class="nav-list-link">Obfuscation</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/obfuscation/how-to-use-metasploit-framework-obfuscation-crandomizer.html" class="nav-list-link">C Obfuscation</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/obfuscation/how-to-obfuscate-javascript-in-metasploit.html" class="nav-list-link">JavaScript Obfuscation</a></ul><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-use-phpexe-to-exploit-an-arbitrary-file-upload-bug.html" class="nav-list-link">PhpExe</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/post-mixins.html" class="nav-list-link">PostMixins</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-use-powershell-in-an-exploit.html" class="nav-list-link">Powershell</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-use-railgun-for-windows-post-exploitation.html" class="nav-list-link">Railgun</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/using-reflectivedll-injection.html" class="nav-list-link">ReflectiveDLL Injection</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-do-reporting-or-store-data-in-module-development.html" class="nav-list-link">Reporting and Storing Data</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-use-the-seh-mixin-to-exploit-an-exception-handler.html" class="nav-list-link">SEH Exploitation</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/developing-modules/libraries/smb_library/" class="nav-list-link">SMB Library</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/smb_library/guidelines-for-writing-modules-with-smb.html" class="nav-list-link">Guidelines for Writing Modules with SMB</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/smb_library/what-my-rex-proto-smb-error-means.html" class="nav-list-link">What my Rex Proto SMB Error means</a></ul><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/sql-injection-libraries.html" class="nav-list-link">SQL Injection</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-use-the-msf-exploit-remote-tcp-mixin.html" class="nav-list-link">TCP</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-use-wbemexec-for-a-write-privilege-attack-on-windows.html" class="nav-list-link">WbemExec</a><li class="nav-list-item active"><a href="/docs/development/developing-modules/libraries/how-to-zip-files-with-msf-util-exe-to_zip.html" class="nav-list-link">Zip</a></ul></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/google-summer-of-code/" class="nav-list-link">Google Summer of Code</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2017-mentor-organization-application.html" class="nav-list-link">2017 Mentor Organization Application</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2017-project-ideas.html" class="nav-list-link">2017 Project Ideas</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2017-student-proposal.html" class="nav-list-link">2017 Student Proposal</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2018-project-ideas.html" class="nav-list-link">2018 Project Ideas</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2019-project-ideas.html" class="nav-list-link">2019 Project Ideas</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2020-project-ideas.html" class="nav-list-link">2020 Project Ideas</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2021-project-ideas.html" class="nav-list-link">2021 Project Ideas</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2022-project-ideas.html" class="nav-list-link">2022 Project Ideas</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2023-project-ideas.html" class="nav-list-link">2023 Project Ideas</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/gsoc-2026-project-ideas.html" class="nav-list-link">2026 Project Ideas</a><li class="nav-list-item active"><a href="/docs/development/google-summer-of-code/how-to-apply-to-gsoc.html" class="nav-list-link">How to Apply to GSoC</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/maintainers/" class="nav-list-link">Maintainers</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/maintainers/committer-keys.html" class="nav-list-link">Committer Keys</a><li class="nav-list-item active"><a href="/docs/development/maintainers/committer-rights.html" class="nav-list-link">Committer Rights</a><li class="nav-list-item active"><a href="/docs/development/maintainers/downloads-by-version.html" class="nav-list-link">Downloads by Version</a><li class="nav-list-item active"><a href="/docs/development/maintainers/metasploit-hackathons.html" class="nav-list-link">Metasploit Hackathons</a><li class="nav-list-item active"><a href="/docs/development/maintainers/metasploit-loginpalooza.html" class="nav-list-link">Metasploit Loginpalooza</a><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/maintainers/process/" class="nav-list-link">Process</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/maintainers/process/assigning-labels.html" class="nav-list-link">Assigning Labels</a><li class="nav-list-item active"><a href="/docs/development/maintainers/process/guidelines-for-accepting-modules-and-enhancements.html" class="nav-list-link">Guidelines for Accepting Modules and Enhancements</a><li class="nav-list-item active"><a href="/docs/development/maintainers/process/how-to-deprecate-a-metasploit-module.html" class="nav-list-link">How to deprecate a Metasploit module</a><li class="nav-list-item active"><a href="/docs/development/maintainers/process/landing-pull-requests.html" class="nav-list-link">Landing Pull Requests</a><li class="nav-list-item active"><a href="/docs/development/maintainers/process/adding-release-notes-to-prs.html" class="nav-list-link">Release Notes</a><li class="nav-list-item active"><a href="/docs/development/maintainers/process/rolling-back-merges.html" class="nav-list-link">Rolling back merges</a><li class="nav-list-item active"><a href="/docs/development/maintainers/process/unstable-modules.html" class="nav-list-link">Unstable Modules</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/maintainers/ruby-gems/" class="nav-list-link">Ruby Gems</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/maintainers/ruby-gems/how-to-add-and-update-gems-in-metasploit-framework.html" class="nav-list-link">Adding and Updating</a><li class="nav-list-item active"><a href="/docs/development/maintainers/ruby-gems/merging-metasploit-payload-gem-updates.html" class="nav-list-link">Merging Metasploit Payload Gem Updates</a><li class="nav-list-item active"><a href="/docs/development/maintainers/ruby-gems/using-local-gems.html" class="nav-list-link">Using local Gems</a></ul></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/propsals/" class="nav-list-link">Proposals</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/propsals/bundled-modules-proposal.html" class="nav-list-link">Bundled Modules Proposal</a><li class="nav-list-item active"><a href="/docs/development/propsals/java-meterpreter-feature-parity-proposal.html" class="nav-list-link">Java Meterpreter Feature Parity Proposal</a><li class="nav-list-item active"><a href="/docs/development/propsals/msf6-feature-proposals.html" class="nav-list-link">MSF6 Feature Proposals</a><li class="nav-list-item active"><a href="/docs/development/propsals/metasploit-url-support-proposal.html" class="nav-list-link">Metasploit URL support proposal</a><li class="nav-list-item active"><a href="/docs/development/propsals/payload-rename-justification.html" class="nav-list-link">Payload Rename Justification</a><li class="nav-list-item active"><a href="/docs/development/propsals/uberhandler.html" class="nav-list-link">Uberhandler</a><li class="nav-list-item active"><a href="/docs/development/propsals/work-needed-to-allow-msfdb-to-use-postgresql-common.html" class="nav-list-link">Work needed to allow msfdb to use postgresql common</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/quality/" class="nav-list-link">Quality</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/quality/common-metasploit-module-coding-mistakes.html" class="nav-list-link">Common Metasploit Module Coding Mistakes</a><li class="nav-list-item active"><a href="/docs/development/quality/loading-test-modules.html" class="nav-list-link">Loading Test Modules</a><li class="nav-list-item active"><a href="/docs/development/quality/measuring-metasploit-performance.html" class="nav-list-link">Measuring Metasploit Performance</a><li class="nav-list-item active"><a href="/docs/development/quality/msftidy.html" class="nav-list-link">Msftidy</a><li class="nav-list-item active"><a href="/docs/development/quality/payload-testing.html" class="nav-list-link">Payload Testing</a><li class="nav-list-item active"><a href="/docs/development/quality/style-tips.html" class="nav-list-link">Style Tips</a><li class="nav-list-item active"><a href="/docs/development/quality/using-rubocop.html" class="nav-list-link">Using Rubocop</a><li class="nav-list-item active"><a href="/docs/development/quality/writing-module-documentation.html" class="nav-list-link">Writing Module Documentation</a></ul><li class="nav-list-item active"><a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a><a href="/docs/development/roadmap/" class="nav-list-link">Roadmap</a><ul class="nav-list"><li class="nav-list-item active"><a href="/docs/development/roadmap/2017-roadmap.html" class="nav-list-link">2017 Roadmap</a><li class="nav-list-item active"><a href="/docs/development/roadmap/2017-roadmap-review.html" class="nav-list-link">2017 Roadmap Review</a><li class="nav-list-item active"><a href="/docs/development/roadmap/metasploit-breaking-changes.html" class="nav-list-link">Metasploit Breaking Changes</a><li class="nav-list-item active"><a href="/docs/development/roadmap/metasploit-data-service-enhancements-goliath.html" class="nav-list-link">Metasploit Data Service</a><li class="nav-list-item active"><a href="/docs/development/roadmap/metasploit-5-release-notes.html" class="nav-list-link">Metasploit Framework 5.0 Release Notes</a><li class="nav-list-item active"><a href="/docs/development/roadmap/metasploit-6-release-notes.html" class="nav-list-link">Metasploit Framework 6.0 Release Notes</a><li class="nav-list-item active"><a href="/docs/development/roadmap/metasploit-framework-wish-list.html" class="nav-list-link">Metasploit Framework Wish List</a></ul></ul><li class="nav-list-item active"><a href="/docs/contact.html" class="nav-list-link">Contact</a></ul></nav><footer class="site-footer"> This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.</footer></div><div class="main" id="top"><div id="main-header" class="main-header"><div class="search"><div class="search-input-wrap"> <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search Metasploit Documentation" aria-label="Search Metasploit Documentation" autocomplete="off"> <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label></div><div id="search-results" class="search-results"></div></div><link rel="stylesheet" href="/assets/css/main.css"><nav aria-label="Auxiliary" class="aux-nav"><ul class="aux-nav-list"><li class="aux-nav-list-item"> <a href="//github.com/rapid7/metasploit-framework" class="site-button" target="_blank" rel="noopener noreferrer" > Metasploit Framework on GitHub </a></ul></nav></div><div id="main-content-wrap" class="main-content-wrap"><nav aria-label="Breadcrumb" class="breadcrumb-nav"><ol class="breadcrumb-nav-list"><li class="breadcrumb-nav-list-item"> <a href="/docs/development/">Development</a><li class="breadcrumb-nav-list-item"> <a href="/docs/development/developing-modules/">Developing Modules</a><li class="breadcrumb-nav-list-item"> <a href="/docs/development/developing-modules/external-modules/">External Modules</a><li class="breadcrumb-nav-list-item"> <span>Writing Python Modules</span></ol></nav><div id="main-content" class="main-content" role="main"><h1 id="writing-python-modules-for-metasploit"> <a href="#writing-python-modules-for-metasploit" class="anchor-heading" aria-labelledby="writing-python-modules-for-metasploit"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Writing Python Modules for Metasploit</h1><p>This is an example of how to write a Python module for Metasploit Framework that uses a Python metasploit library to communicate with framework via JSON-RPC over stdin/stdout. External Python modules should support Python versions 3.5 and newer. Python 2.7 is no longer used for external modules.</p><h4 id="execution"> <a href="#execution" class="anchor-heading" aria-labelledby="execution"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Execution</h4><ul><li>Include this line at the top of your module: <code class="language-plaintext highlighter-rouge">#!/usr/bin/env python3</code><li>Ensure your file is marked as executable</ul><h2 id="python-library"> <a href="#python-library" class="anchor-heading" aria-labelledby="python-library"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Python Library</h2><p>The library currently supports a few function calls that can be used to report information to Metasploit Framework. The <code class="language-plaintext highlighter-rouge">metasploit</code> library can be loaded into your Python module by including the following line:</p><div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kn">from</span> <span class="n">metasploit</span> <span class="kn">import</span> <span class="n">module</span>
</code></pre></div></div><p>The location of the <a href="https://github.com/rapid7/metasploit-framework/tree/master/lib/msf/core/modules/external/python">metasploit library</a> is automatically added to the <code class="language-plaintext highlighter-rouge">PYTHONPATH</code> environment variable before the Python module is executed.</p><h2 id="describe-yourself"> <a href="#describe-yourself" class="anchor-heading" aria-labelledby="describe-yourself"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Describe Yourself</h2><p>Metasploit modules include information about authors of the modules, references to other sources with information about the vulnerabilities, descriptions of the modules, options, etc.</p><p>Python modules need to include this metadata information as well. The structure of the data is similar to modules written in Ruby. The following is an example template of metadata information:</p><div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">metadata</span> <span class="o">=</span> <span class="p">{</span>
<span class="sh">'</span><span class="s">name</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">&lt;name&gt;</span><span class="sh">'</span><span class="p">,</span>
<span class="sh">'</span><span class="s">description</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'''</span><span class="s">
&lt;description&gt;
</span><span class="sh">'''</span><span class="p">,</span>
<span class="sh">'</span><span class="s">authors</span><span class="sh">'</span><span class="p">:</span> <span class="p">[</span>
<span class="sh">'</span><span class="s">&lt;author&gt;</span><span class="sh">'</span><span class="p">,</span>
<span class="sh">'</span><span class="s">&lt;author&gt;</span><span class="sh">'</span>
<span class="p">],</span>
<span class="sh">'</span><span class="s">date</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">YYYY-MM-DD</span><span class="sh">'</span><span class="p">,</span>
<span class="sh">'</span><span class="s">license</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">&lt;license&gt;</span><span class="sh">'</span><span class="p">,</span>
<span class="sh">'</span><span class="s">references</span><span class="sh">'</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">url</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">ref</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">&lt;url&gt;</span><span class="sh">'</span><span class="p">},</span>
<span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">cve</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">ref</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">YYYY-#</span><span class="sh">'</span><span class="p">},</span>
<span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">edb</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">ref</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">#</span><span class="sh">'</span><span class="p">},</span>
<span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">aka</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">ref</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">&lt;name&gt;</span><span class="sh">'</span><span class="p">}</span>
<span class="p">],</span>
<span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">&lt;module type&gt;</span><span class="sh">'</span><span class="p">,</span>
<span class="sh">'</span><span class="s">options</span><span class="sh">'</span><span class="p">:</span> <span class="p">{</span>
<span class="sh">'</span><span class="s">&lt;name&gt;</span><span class="sh">'</span><span class="p">:</span> <span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">address</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">description</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">&lt;description&gt;</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">required</span><span class="sh">'</span><span class="p">:</span> <span class="o">&lt;</span><span class="bp">True</span><span class="o">/</span><span class="bp">False</span><span class="o">&gt;</span><span class="p">,</span> <span class="sh">'</span><span class="s">default</span><span class="sh">'</span><span class="p">:</span> <span class="bp">None</span><span class="p">},</span>
<span class="sh">'</span><span class="s">&lt;name&gt;</span><span class="sh">'</span><span class="p">:</span> <span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">string</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">description</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">&lt;description&gt;</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">required</span><span class="sh">'</span><span class="p">:</span> <span class="o">&lt;</span><span class="bp">True</span><span class="o">/</span><span class="bp">False</span><span class="o">&gt;</span><span class="p">,</span> <span class="sh">'</span><span class="s">default</span><span class="sh">'</span><span class="p">:</span> <span class="bp">None</span><span class="p">},</span>
<span class="sh">'</span><span class="s">&lt;name&gt;</span><span class="sh">'</span><span class="p">:</span> <span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">string</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">description</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">&lt;description&gt;</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">required</span><span class="sh">'</span><span class="p">:</span> <span class="o">&lt;</span><span class="bp">True</span><span class="o">/</span><span class="bp">False</span><span class="o">&gt;</span><span class="p">,</span> <span class="sh">'</span><span class="s">default</span><span class="sh">'</span><span class="p">:</span> <span class="bp">None</span><span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div><h3 id="module-type"> <a href="#module-type" class="anchor-heading" aria-labelledby="module-type"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Module Type</h3><p>As shown in the metadata template information, a <code class="language-plaintext highlighter-rouge">type</code> is also include for the module. The module type is used to select an ERB template, which generates a Ruby document for the module. The ERB templates can be found <a href="https://github.com/rapid7/metasploit-framework/tree/master/lib/msf/core/modules/external/templates">here</a>. The following templates are currently available:</p><div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>remote_exploit_cmd_stager
capture_server
dos
single_scanner
multi_scanner
</code></pre></div></div><p>The <code class="language-plaintext highlighter-rouge">remote_exploit_cmd_stager</code> module type is used when writing an exploit for command execution or code injection vulnerabilities and provides the command to inject into the vulnerable code based on the <a href="/docs/development/developing-modules/guides/how-to-use-command-stagers.html">flavor</a> specified for the command stager.</p><p>The <code class="language-plaintext highlighter-rouge">capture_server</code> module type is used when a module is designed to simulate a service to capture credentials for connecting clients.</p><p>The <code class="language-plaintext highlighter-rouge">dos</code> module type is used when the module will send packets to a remote service that will crash the service or put it in an unusable state.</p><p>The <code class="language-plaintext highlighter-rouge">single_scanner</code> module type is used when creating a module to scan hosts without batching.</p><p>The <code class="language-plaintext highlighter-rouge">multi_scanner</code> module type is used for modules that are going to scan hosts in batches. The <code class="language-plaintext highlighter-rouge">batch_size</code> option is registered in the mutli_scanner ERB template with a default of 200.</p><h3 id="options"> <a href="#options" class="anchor-heading" aria-labelledby="options"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Options</h3><p>The <code class="language-plaintext highlighter-rouge">options</code> dictionary in the metadata are the options that will be available in msfconsole when the module is loaded. The options can be required (necessary for the module to run) or not (provide additional functionality).</p><h3 id="communication"> <a href="#communication" class="anchor-heading" aria-labelledby="communication"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Communication</h3><p>To pass the metadata information, as well as the starting function of your Python module, to msfconsole, use the <code class="language-plaintext highlighter-rouge">module.run()</code> function. The <code class="language-plaintext highlighter-rouge">module.run()</code> function takes two arguments, the first is the metadata and the second is the callback function to use when executing the module from msfconsole. The code snippet will look like the following:</p><div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">):</span>
<span class="c1"># Your code here
</span> <span class="k">pass</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="sh">'</span><span class="s">__main__</span><span class="sh">'</span><span class="p">:</span>
<span class="n">module</span><span class="p">.</span><span class="nf">run</span><span class="p">(</span><span class="n">metadata</span><span class="p">,</span> <span class="n">run</span><span class="p">)</span>
</code></pre></div></div><p>When msfconsole sends a <code class="language-plaintext highlighter-rouge">describe</code> request to the Python module, the metadata information is returned. When msfconsole sends a <code class="language-plaintext highlighter-rouge">run</code> request to the module, the callback function, <code class="language-plaintext highlighter-rouge">run</code> in this example, will be called with the arguments provided to msfconsole.</p><p>A <a href="https://github.com/rapid7/metasploit-framework/pull/9739">LogHandler</a> can be setup and used to communicate status information back to framework during execution of the Python module. Here is code snippet that uses the LogHandler:</p><div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kn">import</span> <span class="n">logging</span>
<span class="kn">from</span> <span class="n">metasploit</span> <span class="kn">import</span> <span class="n">module</span>
<span class="n">module</span><span class="p">.</span><span class="n">LogHandler</span><span class="p">.</span><span class="nf">setup</span><span class="p">(</span><span class="n">msg_prefix</span><span class="o">=</span><span class="sh">'</span><span class="s">logging test: </span><span class="sh">'</span><span class="p">)</span>
<span class="n">logging</span><span class="p">.</span><span class="nf">info</span><span class="p">(</span><span class="sh">'</span><span class="s">info</span><span class="sh">'</span><span class="p">)</span>
<span class="n">logging</span><span class="p">.</span><span class="nf">error</span><span class="p">(</span><span class="sh">'</span><span class="s">error</span><span class="sh">'</span><span class="p">)</span>
<span class="n">logging</span><span class="p">.</span><span class="nf">warning</span><span class="p">(</span><span class="sh">'</span><span class="s">warning</span><span class="sh">'</span><span class="p">)</span>
<span class="n">logging</span><span class="p">.</span><span class="nf">debug</span><span class="p">(</span><span class="sh">'</span><span class="s">debug</span><span class="sh">'</span><span class="p">)</span>
</code></pre></div></div><p>The <code class="language-plaintext highlighter-rouge">module.LogHandler.setup()</code> function is used the create a Handler and Formatter that will call <code class="language-plaintext highlighter-rouge">module.log()</code> with the appropriate log level.</p><h2 id="full-example"> <a href="#full-example" class="anchor-heading" aria-labelledby="full-example"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Full Example</h2><div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">#!/usr/bin/env python3
# -*- coding: utf-8 -*-
</span>
<span class="c1"># standard modules
</span><span class="kn">import</span> <span class="n">logging</span>
<span class="c1"># extra modules
</span><span class="n">dependencies_missing</span> <span class="o">=</span> <span class="bp">False</span>
<span class="k">try</span><span class="p">:</span>
<span class="kn">import</span> <span class="n">requests</span>
<span class="k">except</span> <span class="nb">ImportError</span><span class="p">:</span>
<span class="n">dependencies_missing</span> <span class="o">=</span> <span class="bp">True</span>
<span class="kn">from</span> <span class="n">metasploit</span> <span class="kn">import</span> <span class="n">module</span>
<span class="n">metadata</span> <span class="o">=</span> <span class="p">{</span>
<span class="sh">'</span><span class="s">name</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">Python Module Example</span><span class="sh">'</span><span class="p">,</span>
<span class="sh">'</span><span class="s">description</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'''</span><span class="s">
Python communication with msfconsole.
</span><span class="sh">'''</span><span class="p">,</span>
<span class="sh">'</span><span class="s">authors</span><span class="sh">'</span><span class="p">:</span> <span class="p">[</span>
<span class="sh">'</span><span class="s">Jacob Robles</span><span class="sh">'</span>
<span class="p">],</span>
<span class="sh">'</span><span class="s">date</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">2018-03-22</span><span class="sh">'</span><span class="p">,</span>
<span class="sh">'</span><span class="s">license</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">MSF_LICENSE</span><span class="sh">'</span><span class="p">,</span>
<span class="sh">'</span><span class="s">references</span><span class="sh">'</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">url</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">ref</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">https://blog.rapid7.com/2017/12/28/regifting-python-in-metasploit/</span><span class="sh">'</span><span class="p">},</span>
<span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">aka</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">ref</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">Coldstone</span><span class="sh">'</span><span class="p">}</span>
<span class="p">],</span>
<span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">single_scanner</span><span class="sh">'</span><span class="p">,</span>
<span class="sh">'</span><span class="s">options</span><span class="sh">'</span><span class="p">:</span> <span class="p">{</span>
<span class="sh">'</span><span class="s">targeturi</span><span class="sh">'</span><span class="p">:</span> <span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">string</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">description</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">The base path</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">required</span><span class="sh">'</span><span class="p">:</span> <span class="bp">True</span><span class="p">,</span> <span class="sh">'</span><span class="s">default</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">/</span><span class="sh">'</span><span class="p">},</span>
<span class="sh">'</span><span class="s">rhost</span><span class="sh">'</span><span class="p">:</span> <span class="p">{</span><span class="sh">'</span><span class="s">type</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">address</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">description</span><span class="sh">'</span><span class="p">:</span> <span class="sh">'</span><span class="s">Target address</span><span class="sh">'</span><span class="p">,</span> <span class="sh">'</span><span class="s">required</span><span class="sh">'</span><span class="p">:</span> <span class="bp">True</span><span class="p">,</span> <span class="sh">'</span><span class="s">default</span><span class="sh">'</span><span class="p">:</span> <span class="bp">None</span><span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">):</span>
<span class="n">module</span><span class="p">.</span><span class="n">LogHandler</span><span class="p">.</span><span class="nf">setup</span><span class="p">(</span><span class="n">msg_prefix</span><span class="o">=</span><span class="sh">'</span><span class="s">{} - </span><span class="sh">'</span><span class="p">.</span><span class="nf">format</span><span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="sh">'</span><span class="s">rhost</span><span class="sh">'</span><span class="p">]))</span>
<span class="k">if</span> <span class="n">dependencies_missing</span><span class="p">:</span>
<span class="n">logging</span><span class="p">.</span><span class="nf">error</span><span class="p">(</span><span class="sh">'</span><span class="s">Module dependency (requests) is missing, cannot continue</span><span class="sh">'</span><span class="p">)</span>
<span class="k">return</span>
<span class="c1"># Your code here
</span> <span class="k">try</span><span class="p">:</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="p">.</span><span class="nf">get</span><span class="p">(</span><span class="sh">'</span><span class="s">https://{}/{}</span><span class="sh">'</span><span class="p">.</span><span class="nf">format</span><span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="sh">'</span><span class="s">rhost</span><span class="sh">'</span><span class="p">],</span> <span class="n">args</span><span class="p">[</span><span class="sh">'</span><span class="s">targeturi</span><span class="sh">'</span><span class="p">]),</span> <span class="n">verify</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="k">except</span> <span class="n">requests</span><span class="p">.</span><span class="n">exceptions</span><span class="p">.</span><span class="n">RequestException</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="n">logging</span><span class="p">.</span><span class="nf">error</span><span class="p">(</span><span class="sh">'</span><span class="s">{}</span><span class="sh">'</span><span class="p">.</span><span class="nf">format</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
<span class="k">return</span>
<span class="n">logging</span><span class="p">.</span><span class="nf">info</span><span class="p">(</span><span class="sh">'</span><span class="s">{}...</span><span class="sh">'</span><span class="p">.</span><span class="nf">format</span><span class="p">(</span><span class="n">r</span><span class="p">.</span><span class="n">text</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">50</span><span class="p">]))</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="sh">'</span><span class="s">__main__</span><span class="sh">'</span><span class="p">:</span>
<span class="n">module</span><span class="p">.</span><span class="nf">run</span><span class="p">(</span><span class="n">metadata</span><span class="p">,</span> <span class="n">run</span><span class="p">)</span>
</code></pre></div></div><p>The example sends a get request to the given <code class="language-plaintext highlighter-rouge">rhost</code> and <code class="language-plaintext highlighter-rouge">targeturi</code>, then calls <code class="language-plaintext highlighter-rouge">logging.info()</code> on the result to have the output displayed in msfconsole.</p><h3 id="debugging-python-modules"> <a href="#debugging-python-modules" class="anchor-heading" aria-labelledby="debugging-python-modules"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Debugging Python modules</h3><p>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:</p><div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ PYTHONPATH=./lib/msf/core/modules/external/python:$PYTHONPATH python3 ./modules/auxiliary/scanner/wproxy/att_open_proxy.py
</code></pre></div></div><p>The Python module will wait for stdin to receive JSON-RPC input. Entering the request to run the module:</p><pre><code class="language-jsonl">{ "jsonrpc": "2.0", "id": "1337", "method": "run", "params": { "rhosts": ["127.0.0.1"], "rport": "49152" } }
</code></pre><p>You will see the JSON-RPC responses printed to stdout:</p><pre><code class="language-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')"}}
</code></pre><p>You can pipe the JSON-RPC request as well for automation purposes:</p><div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>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
</code></pre></div></div><p>The Python external modules can be run directly with command line options:</p><div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ 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&amp;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
</code></pre></div></div><p>For example:</p><div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>PYTHONPATH=./lib/msf/core/modules/external/python:$PYTHONPATH python3 ./modules/auxiliary/scanner/wproxy/att_open_proxy.py --rhosts 127.0.0.1 --rport 49152
</code></pre></div></div><p>For exploit modules, the payload is encoded encoded using Base64 and specified in a top level <code class="language-plaintext highlighter-rouge">payload_encoded</code> key, implemented <a href="https://github.com/rapid7/metasploit-framework/blob/668735e4185968405c0073465f9aafbf62930538/lib/msf/core/modules/external/templates/remote_exploit.erb#L36-L39">here</a>. Below is an example of the (<a href="https://github.com/rapid7/metasploit-framework/pull/15217">now deleted</a>) <a href="https://github.com/rapid7/metasploit-framework/blob/6dd298ebb76a1617e24da5e4c73e43a46b226a23/modules/exploits/windows/smb/ms17_010_eternalblue_win8.py">ms17_010_eternalblue_win8.py</a> module running:</p><div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ 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"}}
</code></pre></div></div><p>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:</p><div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kn">import</span> <span class="n">pdb</span><span class="p">;</span> <span class="n">pdb</span><span class="p">.</span><span class="n">pry</span>
</code></pre></div></div><h2 id="coding-with-style"> <a href="#coding-with-style" class="anchor-heading" aria-labelledby="coding-with-style"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Coding with Style</h2><p>All the Python code in Metasploit aims to be <a href="https://www.python.org/dev/peps/pep-0008/">PEP 8</a> compliant. The biggest differences coming from Metasploit’s Ruby style:</p><ul><li>Two lines between functions (but not class methods)<li>Two lines between different types of code (like imports and the metadata, see above)<li>Four spaces for indenting</ul><p>Some coding choices to think about when writing your module:</p><ul><li>Prefer <code class="language-plaintext highlighter-rouge">"foo {}".format('bar')</code> over interpolation with <code class="language-plaintext highlighter-rouge">%</code><li>Keep your callback methods short and readable. If it gets cluttered, break out sub-tasks into well-named functions<li>Variable names should be descriptive, readable, and short (<a href="http://journal.stuffwithstuff.com/2016/06/16/long-names-are-long">a guide</a>)<li>If you really need Python3 features in your module, use <code class="language-plaintext highlighter-rouge">#!/usr/bin/env python3</code> for the shebang<li>If you have a lot of legacy code in 2.7 or need a 2.7 library, use <code class="language-plaintext highlighter-rouge">#!/usr/bin/env python2.7</code> (macOS in particular does not ship with a <code class="language-plaintext highlighter-rouge">python2</code> executable by default)<li>If possible, have your module compatible with both and use <code class="language-plaintext highlighter-rouge">#!/usr/bin/env python</code></ul><h2 id="potentially-common-questions"> <a href="#potentially-common-questions" class="anchor-heading" aria-labelledby="potentially-common-questions"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> (Potentially) Common Questions</h2><h3 id="why-doesnt-the-module-appear-when-i-search-for-it-in-msfconsole"> <a href="#why-doesnt-the-module-appear-when-i-search-for-it-in-msfconsole" class="anchor-heading" aria-labelledby="why-doesnt-the-module-appear-when-i-search-for-it-in-msfconsole"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Why doesn’t the module appear when I search for it in msfconsole?</h3><p>The module may have errors and fail to load inside of msfconsole. Check the framework log file, <code class="language-plaintext highlighter-rouge">~/.msf4/logs/framework.log</code>, for error messages. Also, <strong>if the module is not marked as executable, then it will not show up when you search for it in msfconsole</strong>.</p><h3 id="why-is-the-output-from-the-python-module-not-showing-up-in-msfconsole"> <a href="#why-is-the-output-from-the-python-module-not-showing-up-in-msfconsole" class="anchor-heading" aria-labelledby="why-is-the-output-from-the-python-module-not-showing-up-in-msfconsole"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Why is the output from the Python module not showing up in msfconsole?</h3><p>The external modules communicate with framework via JSON-RPC. If your Python module contains <code class="language-plaintext highlighter-rouge">print</code> statements, framework may not recognize those as JSON-RPC requests. Use the <code class="language-plaintext highlighter-rouge">LogHandler</code> or <code class="language-plaintext highlighter-rouge">module.log()</code> to send status information, which will be displayed in msfconsole.</p><h2 id="additional-resources"> <a href="#additional-resources" class="anchor-heading" aria-labelledby="additional-resources"><svg viewBox="0 0 16 16" aria-hidden="true"><use xlink:href="#svg-link"></use></svg></a> Additional Resources</h2><p><a href="https://blog.rapid7.com/2017/12/28/regifting-python-in-metasploit/">Rapid7 Blog: Regifting Python in Metasploit</a></p><p><a href="https://blog.rapid7.com/2018/09/05/external-metasploit-modules-the-gift-that-keeps-on-slithering/">Rapid7 Blog: External Metasploit Modules: The Gift That Keeps On Slithering</a></p><p><a href="https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/modules/external/python/">Metasploit Python library</a></p><p><a href="https://github.com/rapid7/metasploit-framework/tree/master/lib/msf/core/modules/external/templates">ERB Templates</a></p><hr><footer><p><a href="#top" id="back-to-top">Back to top</a></p><p class="text-small text-grey-dk-000 mb-0"> <a href="https://github.com/rapid7/metasploit-framework/tree/master/docs/metasploit-framework.wiki/Writing-External-Python-Modules.md" id="edit-this-page">Edit this page on GitHub</a></p></footer></div></div><div class="search-overlay"></div></div><script type="text/javascript" src="/assets/js/toggle_mode.js"></script> <script> var config = { theme: 'default', logLevel: 'fatal', securityLevel: 'strict', startOnLoad: true, arrowMarkerAbsolute: false, er: { diagramPadding: 20, layoutDirection: 'TB', minEntityWidth: 100, minEntityHeight: 75, entityPadding: 15, stroke: 'gray', fill: 'honeydew', fontSize: 12, useMaxWidth: true, }, flowchart:{ diagramPadding: 8, htmlLabels: true, curve: 'basis', }, sequence: { diagramMarginX: 50, diagramMarginY: 10, actorMargin: 50, width: 150, height: 65, boxMargin: 10, boxTextMargin: 5, noteMargin: 10, messageMargin: 35, messageAlign: 'center', mirrorActors: true, bottomMarginAdj: 1, useMaxWidth: true, rightAngles: false, showSequenceNumbers: false, }, gantt: { titleTopMargin: 25, barHeight: 20, barGap: 4, topPadding: 50, leftPadding: 75, fontSize: 11, gridLineStartPadding: 35, fontFamily: '\'Open Sans\', sans-serif', numberSectionStyles: 4, axisFormat: '%Y-%m-%d', topAxis: false, }, }; mermaid.initialize(config); window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid')); </script>
Reference in New Issue View Git Blame Copy Permalink