Writing Modules

A guide to writing new Metasploit modules. The reference code is under packages/metasploit-framework. The referenced commit is listed in Metasploit Operations Notes.

This guide assumes you will use existing payloads from exploits rather than write payload modules themselves.

Reading order

1. Use this page to choose a module type and review the decision table.
2. Read Shared Steps from top to bottom for the purpose and implementation of each step.
3. Read the page for your module type for entry methods and examples.
4. Consult Mixins and APIs, Helper Functions, and send_request_cgi as needed.

Purpose	Page
Shared steps, one at a time	Shared Steps
Exploit	Exploit
Auxiliary	Auxiliary
Post	Post
Mixins and APIs	Mixins and APIs
Helper functions	Helper Functions
HTTP requests	send_request_cgi

Module locations

Location	Purpose
~/.msf4/modules/exploits/...	Custom exploit
~/.msf4/modules/auxiliary/...	Custom auxiliary module
~/.msf4/modules/post/...	Custom post module
packages/metasploit-framework/modules/...	Upstream reference code

loadpath /path/to/extra/modules
reload_lib -a

The following templates are useful references:

• modules/exploits/example.rb — TCP exploit
• modules/exploits/example_webapp.rb — HTTP / web application exploit
• modules/exploits/example_linux_priv_esc.rb — local privilege escalation
• modules/auxiliary/example.rb — auxiliary
• modules/post/multi/general/execute.rb — post module

Module types

Type	Example base class	Entry method	Payload
exploit	Msf::Exploit::Remote / Msf::Exploit::Local	check (optional), exploit	Used
auxiliary	Msf::Auxiliary	run, or run_host for a scanner	Not used
post	Msf::Post	run (SESSION required)	Not used (runs in an existing session)
payload	(Not written here)	—	Is itself a payload

Use an exploit for code that opens a new session, an auxiliary module for code that does not, and a post module for work in an existing session.

Shared steps

#	Step	What to do	Details
1	Type and path	Choose exploit, auxiliary, or post and its directory	Type and Location
2	Base class and mixins	Add communication and execution behavior through inheritance and include	Base Classes and Mixins
3	update_info	Metadata such as Name, Platform, Targets, and Notes	update_info
4	register_options	Inputs that users set with set	register_options
5	Entry method	check / exploit / run / run_host	Entry Methods
6	Saving results	report_*, store_loot, and credential APIs	Saving Results
7	Cleanup	Schedule removal of placed files and related cleanup	Cleanup

Where to go for each task

Find the relevant page from a common task.

Task	Suggested type	Read first
Log in over HTTP and retrieve configuration or files	auxiliary	Auxiliary + send_request_cgi
Scan banners or versions across many hosts	auxiliary + Scanner	Scanner
Try username and password lists	auxiliary + AuthBrute	AuthBrute
Return a shell through HTTP command injection	exploit	Exploit + CmdStager
Open a session through a TCP binary vulnerability	exploit + Tcp	Tcp + Exploit
Serve a trap page to a browser	exploit + HttpServer	HttpServer
Run commands or interact over SSH	exploit or auxiliary	SSH
Operate or authenticate over SMB	auxiliary / exploit + SMB	SMB
Enumerate from an existing shell or Meterpreter session	post	Post + Post Mixins
Upgrade a shell to Meterpreter	post (an existing module also works)	Post / operations: SSH/WinRM
Escalate privileges locally from an existing session	exploit (local)	Exploit
Check only whether a vulnerability exists	check in exploit / auxiliary	Entry Methods + AutoCheck
Save retrieved hashes or configuration in the database	Report with any module type	Saving Results
Remove an uploaded web shell later	exploit + FileDropper	Cleanup
Set up only a listener handler	Existing exploit/multi/handler	Operations: Handlers and Listeners (no custom module needed)

If unsure, ask three questions: Will this open a new session? Is there already a session? Does it need a payload? Then return to Type and Location.