AGENTS.md

1# AI Agent Instructions for Metasploit Framework
2 
3## Project Overview
4 
5Metasploit Framework is an open-source penetration testing and exploitation framework written in Ruby. It provides infrastructure for developing, testing, and executing exploit code against remote targets.
6 
7## Project Structure
8 
9- `modules/` — Metasploit modules (exploits, auxiliary, post, payloads, encoders, evasion, nops)
10- `lib/msf/` — Core framework library code
11- `lib/rex/` — Rex (Ruby Exploitation) library
12- `lib/metasploit/` — Metasploit namespace libraries
13- `data/` — Data files used by modules (wordlists, templates, binaries)
14- `spec/` — RSpec test suite
15- `tools/` — Developer and operational tools
16- `plugins/` — msfconsole plugins
17- `scripts/` — Example automation scripts
18- `documentation/modules/` — Markdown documentation for Metasploit modules
19 
20## Coding Conventions
21 
22- Ruby (see `.ruby-version` for the current version). Minimum supported: 3.1+
23- Follow the project's `.rubocop.yml` configuration — run `rubocop` on changed files before submitting
24- Run `ruby tools/dev/msftidy.rb <module_file_path>` to catch common module issues
25- `# frozen_string_literal: true` — add to new **library** files (`lib/`); use `String.new` where a mutable string is needed. Do NOT add to module files or spec files (the framework extensively mutates string buffers via instance variables, and the RuboCop cop `Style/FrozenStringLiteralComment` is disabled project-wide). Existing files that already have it are fine to leave
26- No enforced line length limit, but keep code readable
27- Use `%q{}` for long multi-line strings (curly braces preferred for module descriptions)
28- Multiline block comments are acceptable for embedded code snippets/payloads
29- Don't use `get_`/`set_` prefixes for accessor methods in new code
30- Method parameter names must be at least 2 characters (exception for well-known crypto abbreviations)
31 
32## Module Structure Templates
33 
34### Exploit Module Template
35 
36New exploit modules should follow this canonical structure and ordering:
37 
38```ruby
39##
40# This module requires Metasploit: https://metasploit.com/download
41# Current source: https://github.com/rapid7/metasploit-framework
42##
43 
44class MetasploitModule < Msf::Exploit::Remote
45  Rank = ExcellentRanking
46 
47  # 1. Protocol mixins first
48  include Msf::Exploit::Remote::HttpClient
49  # 2. Utility/feature mixins second
50  include Msf::Exploit::FileDropper
51  # 3. Reporting mixins (if needed)
52  # include Msf::Auxiliary::Report
53  # 4. AutoCheck ALWAYS LAST — must be prepend, not include
54  prepend Msf::Exploit::Remote::AutoCheck
55 
56  def initialize(info = {})
57    super(
58      update_info(
59        info,
60        'Name' => 'Vendor Product Vulnerability Type',
61        'Description' => %q{
62          Description of the vulnerability and what this module does.
63        },
64        'Author' => [
65          'Discoverer Name', # Vulnerability discovery
66          'Module Author'    # Metasploit module
67        ],
68        'License' => MSF_LICENSE,
69        'References' => [
70          ['CVE', '2024-XXXXX'],
71          ['URL', 'https://example.com/advisory']
72        ],
73        'Targets' => [
74          [
75            'Automatic',
76            {
77              'Platform' => ['linux'], # or 'win', 'osx', 'unix', 'php', 'python', 'java'
78              'Arch' => [ARCH_CMD], # or ARCH_X86, ARCH_X64, ARCH_PHP, ARCH_JAVA, ARCH_PYTHON, ARCH_ARMLE, ARCH_AARCH64, ARCH_MIPSLE — see rex-arch gem for full list
79              'Type' => :cmd # or :dropper, :psh_stager — determines payload delivery
80            }
81          ]
82        ],
83        'DefaultTarget' => 0,
84        'DisclosureDate' => '2024-01-01',
85        'Notes' => {
86          'Stability' => [], # e.g. CRASH_SAFE, CRASH_SERVICE_RESTARTS
87          'SideEffects' => [], # e.g. IOC_IN_LOGS, ARTIFACTS_ON_DISK
88          'Reliability' => [] # e.g. REPEATABLE_SESSION
89        }
90      )
91    )
92  end
93 
94  def check
95    # Always return CheckCode with a reason string
96    CheckCode::Safe('Target is not vulnerable')
97  end
98 
99  def exploit
100    # Exploitation logic
101  end
102end
103```
104 
105### Auxiliary Module Template
106 
107Auxiliary modules use `def run` (not `exploit`) and inherit from `Msf::Auxiliary`:
108 
109```ruby
110class MetasploitModule < Msf::Auxiliary
111  include Msf::Exploit::Remote::HttpClient
112  include Msf::Auxiliary::Report
113  prepend Msf::Exploit::Remote::AutoCheck
114 
115  def initialize(info = {})
116    super(
117      update_info(
118        info,
119        'Name' => 'Vendor Product Scanner/Gatherer',
120        'Description' => %q{
121          Description of what this module discovers or does.
122        },
123        'Author' => ['Author Name'],
124        'License' => MSF_LICENSE,
125        'References' => [['CVE', '2024-XXXXX']],
126        'Notes' => {
127          'Stability' => [], # e.g. CRASH_SAFE
128          'SideEffects' => [], # e.g. IOC_IN_LOGS
129          'Reliability' => [] # e.g. REPEATABLE_SESSION
130        }
131      )
132    )
133 
134    register_options([
135      OptString.new('TARGETURI', [true, 'Base path', '/'])
136    ])
137  end
138 
139  def check
140    CheckCode::Safe('Target is not affected')
141  end
142 
143  def run
144    # Main logic — use report_service, report_vuln, print_good, etc.
145  end
146end
147```
148 
149### Post Module Template
150 
151Post modules inherit from `Msf::Post`, require a session, and declare compatible session types:
152 
153```ruby
154class MetasploitModule < Msf::Post
155  include Msf::Post::File
156  include Msf::Post::Linux::System
157 
158  def initialize(info = {})
159    super(
160      update_info(
161        info,
162        'Name' => 'Platform Subsystem Gather/Action',
163        'Description' => %q{
164          Description of what this post module does on the target.
165        },
166        'Author' => ['Author Name'],
167        'License' => MSF_LICENSE,
168        'Platform' => ['linux'], # or 'win', 'osx', 'unix', 'bsd', 'solaris'
169        'SessionTypes' => ['meterpreter', 'shell'], # or just ['meterpreter'] if shell won't work
170        'Notes' => {
171          'Stability' => [], # e.g. CRASH_SAFE
172          'SideEffects' => [], # e.g. ARTIFACTS_ON_DISK, CONFIG_CHANGES
173          'Reliability' => []
174        }
175      )
176    )
177  end
178 
179  def run
180    # Use create_process, file_exist?, read_file, etc.
181    # Access session via `session` method
182  end
183end
184```
185 
186### Notes Hash Reference
187 
188The `Notes` hash declares the module's operational characteristics:
189 
190| Key | Values | Meaning |
191|-----|--------|---------|
192| `Stability` | `CRASH_SAFE`, `CRASH_SERVICE_RESTARTS`, `CRASH_SERVICE_DOWN`, `CRASH_OS_RESTARTS`, `CRASH_OS_DOWN` | Impact on target stability |
193| `SideEffects` | `IOC_IN_LOGS`, `ARTIFACTS_ON_DISK`, `CONFIG_CHANGES`, `ACCOUNT_LOCKOUTS`, `SCREEN_EFFECTS`, `AUDIO_EFFECTS`, `PHYSICAL_EFFECTS` | Observable traces left on target |
194| `Reliability` | `REPEATABLE_SESSION`, `FIRST_ATTEMPT_FAIL`, `UNRELIABLE_SESSION`, `EVENT_DEPENDENT` | How reliably the module succeeds |
195 
196See also: [`lib/msf/core/constants.rb`](lib/msf/core/constants.rb) for the full list of valid values with descriptions.
197 
198**Which module types require Notes:**
199 
200| Module Type | Notes Required? | Enforced By |
201|-------------|----------------|-------------|
202| Exploit | **Yes** | msftidy + rubocop (`Lint/ModuleEnforceNotes`) |
203| Auxiliary | **Yes** | rubocop (`Lint/ModuleEnforceNotes`) |
204| Post | **Yes** | rubocop (`Lint/ModuleEnforceNotes`) |
205| Evasion | No | — |
206| Payload | No | — |
207| Encoder | No | — |
208| Nop | No | — |
209 
210The same `Stability`, `SideEffects`, and `Reliability` constants apply uniformly — there are no type-specific values. Payloads, encoders, and nops don't use Notes because they don't independently interact with targets.
211 
212### Metadata Source Reference
213 
214The inline comments in the templates above list common values but are **not exhaustive**. Consult these source files for the full set:
215 
216| Field | Source File | Notes |
217|-------|------------|-------|
218| Platform | [`lib/msf/core/module/platform.rb`](lib/msf/core/module/platform.rb) | Class hierarchy — use the lowercase short name (e.g. `'linux'`, `'win'`, `'osx'`) |
219| Arch | [`rex-arch` gem](https://github.com/rapid7/rex-arch/blob/master/lib/rex/arch.rb) | Constants like `ARCH_CMD`, `ARCH_X86`, `ARCH_X64`, `ARCH_PHP` etc. |
220| Stability / SideEffects / Reliability | [`lib/msf/core/constants.rb`](lib/msf/core/constants.rb) | All valid Notes hash values with descriptions |
221| Rank | [`lib/msf/core/constants.rb`](lib/msf/core/constants.rb) | `ManualRanking` through `ExcellentRanking` |
222| CheckCode | [`lib/msf/core/exploit.rb`](lib/msf/core/exploit.rb) (line ~52) | `Vulnerable`, `Appears`, `Safe`, `Detected`, `Unknown`, `Unsupported` |
223 
224### Mixin Ordering
225 
226Follow this order for includes and prepends in module classes:
227 
2281. **Protocol mixins** — `Msf::Exploit::Remote::HttpClient`, `RubySMB`, `Msf::Exploit::Remote::Udp`, etc.
2292. **Utility/feature mixins** — `Msf::Exploit::FileDropper`, `Msf::Exploit::CmdStager`, `Msf::Exploit::EXE`, etc.
2303. **Reporting mixins** — `Msf::Auxiliary::Report`
2314. **Post mixins** (if needed) — `Msf::Post::File`, `Msf::Post::Linux::Priv`, etc.
2325. **`prepend Msf::Exploit::Remote::AutoCheck`** — always last, after all includes
233 
234AutoCheck must use `prepend`, not `include` (the module raises `NotImplementedError` if included). It wraps the `exploit`/`run` method to automatically call `check` before exploitation.
235 
236### Module Development
237 
238#### Metadata and Structure
239 
240- Prefer writing modules in Ruby. Go and Python modules are accepted, but their external runtimes don't support the full framework API (e.g. network pivoting). Ruby modules do not have this limitation
241- Prefer using hash over an array for return values, and use kwargs for reusable APIs for future extensions
242- Before writing a new module, check that there is not an existing module or open pull request that already covers the same functionality
243- Each module should be in its own file under the appropriate `modules/` subdirectory. In some scenarios adding module actions or targets is preferred
244- Exploits require a `DisclosureDate` field
245- Exploits, auxiliary, and post modules require `Notes` with `Stability`, `SideEffects`, and `Reliability`
246- License new code with `MSF_LICENSE` (the project default, defined in `lib/msf/core/constants.rb`)
247- Module descriptions or documentation should list the range of vulnerable versions and the fixed version of the affected software, when known
248- Module descriptions should only use ASCII characters
249- New modules require an associated markdown file in the `documentation/modules` folder with the same structure, including steps to set up the vulnerable environment for testing. If a Dockerfile or docker-compose file is used for the test environment, include the setup commands in the markdown rather than committing separate Docker files. The Scenarios section must be filled out by a human at all times. Follow `documentation/modules/module_doc_template.md` as a template
250- If there's only one `ACTION` in the exploit, it can likely be omitted
251 
252#### Payloads and Targets
253 
254- When possible don't set a default payload (`DefaultOptions` with `'PAYLOAD'`) in modules — let the framework choose the most appropriate payload automatically
255- Define bad characters instead of explicitly base-64 encoding payloads
256- Don't check the number of sessions at the end of an exploit and report success based on that — not all payloads open sessions
257- Don't submit any kind of opaque binary blob — everything must include source code and build instructions
258 
259**Payload selection guidance:**
260 
261| Scenario | Approach |
262|----------|----------|
263| Only command execution available (no file write) | Use `ARCH_CMD` payloads |
264| Only HTTP(S) outbound (curl/wget available) | Use fetch payload (`Msf::Exploit::Remote::HttpServer` + fetch handler) |
265| File write possible on target | Use dropper/EXE payload (`Msf::Exploit::EXE`) |
266| Full command stager needed (multi-step upload) | Use `Msf::Exploit::CmdStager` — but prefer fetch when only download mechanisms are available |
267 
268#### File and Network Operations
269 
270- When overriding `cleanup`, always call `super` to ensure the parent mixin chain cleans up connections and sessions properly
271- When opening a file, make sure the file exists first
272- Don't print host information like `#{ip}:#{port}` because it doesn't handle IPv6 addresses — use `#{Rex::Socket.to_authority(ip, port)}`
273- Use the TEST-NET-1 range for example / non-routeable IP addresses in unit tests and spec files: `192.0.2.0`. Local/private IPs are fine in module documentation scenarios
274 
275#### Output and Reporting
276 
277- All `print_*` calls should start with a capital letter
278- Call `report_service` when a service can be reported
279- Call `report_vuln` when a vulnerability can be reported
280- When creating a fake account / username use the `Faker` gem (e.g. `Faker::Internet.username`) not `Rex::Text.rand_text_alphanumeric`
281 
282#### Session and Post-Exploitation
283 
284- Use `create_process(executable, args: [], time_out: 15, opts: {})` instead of the deprecated `cmd_exec` with separate arguments
285- Use `Msf::OptionalSession` for modules that work both with and without an existing session (e.g. local exploits that can also run standalone)
286- Use the module mixin APIs — don't reinvent the wheel
287 
288#### Internationalisation Considerations
289 
290- When checking for a string in a response — will it always be in English?
291- Ensure hardcoded strings being regex'ed will be consistent across multiple versions
292 
293### Check Methods
294 
295- `check` methods must only return `CheckCode` values (e.g. `CheckCode::Vulnerable`, `CheckCode::Safe`) — never raise exceptions or call `fail_with`
296- When writing a `check` method, verify it does not produce false positives when run against unrelated software or services
297- Prefer using `Rex::Version` for version checks
298- Use `fail_with(Failure::UnexpectedReply, '...')` (and other `Failure::*` constants) to bail out of `exploit`/`run` methods — don't use `raise` or bare `return` for error conditions
299- `get_version` methods should return a REX version
300- `CheckCode::Vulnerable` is only used when the vulnerability has been exploited
301- `CheckCode::Appears` is only used when the application's version has been checked
302- Always provide a human-readable reason string when returning a CheckCode, e.g. `CheckCode::Safe("Target is running patched version #{version}")` — never return a bare constant or empty call
303- Use specific regular expressions or `res.get_html_document` for version extraction with CSS selectors. Don't use generic selectors like `href .*` to grab the version — be more precise
304- Catch exceptions that may be raised and ensure a valid CheckCode is returned
305- Research and determine a minimum version where the application is vulnerable; mark prior versions as safe
306- Check helper methods used by both `#check` and `#exploit` (or `#run`) — ensure there is no condition (exception, return, etc.) where `#check` could return something other than a CheckCode
307- Prefer `prepend Msf::Exploit::Remote::AutoCheck` over manually calling `check` inside `exploit` — this lets the framework handle check-before-exploit automatically
308 
309### Library Code
310 
311When writing or modifying code in `lib/`:
312 
313#### Error Handling
314- Use specific error classes (`Rex::RuntimeError`, `Rex::ConnectionError`, `ArgumentError`, `Rex::TimeoutError`) — never `raise "bare string"` which makes targeted rescue impossible
315- Use `rescue StandardError => e` or a more specific class — never bare `rescue` (it discards the exception object, making debugging impossible) and never `rescue Exception` (it catches `SignalException` and `SystemExit`, hiding Ctrl-C and kill signals)
316- Propagate errors with context: `raise Rex::ConnectionError, "Failed to connect to #{host}: #{e.message}"`
317 
318#### Documentation and Style
319- Add YARD `@param` and `@return` tags to all public methods
320- Add `# frozen_string_literal: true` to new library files
321- Avoid `get_`/`set_` prefixes for accessor-style methods in new code (Ruby convention: use the attribute name directly, e.g. `def version` not `def get_version`)
322- Link to the specification or RFC when implementing binary/protocol parsers
323 
324#### Quality
325- Write RSpec tests for any library changes — tests live in `spec/` mirroring the `lib/` structure
326- Follow [Better Specs](https://www.betterspecs.org/) conventions
327- Keep PRs focused — small fixes are easier to review
328- Any new hash cracking implementations require adding a test hash to `tools/dev/hash_cracker_validator.rb` and ensuring that passes without error
329 
330### Testing
331 
332- Tests live in `spec/` mirroring the `lib/` structure
333- Run a single spec file: `bundle exec rspec spec/path/to/spec.rb`
334- Run a single example by line: `bundle exec rspec spec/path/to/spec.rb:42`
335- Run the full suite: `bundle exec rake spec` (slow — prefer targeted runs during development)
336- Module functional tests live under `spec/modules/` and test end-to-end behaviour
337- Always run specs relevant to your change before submitting
338 
339### Preferred Libraries
340 
341- Use the `RubySMB` library for SMB modules
342- Use `Rex::Stopwatch.elapsed_time` to track elapsed time
343- Use the `Rex::MIME::Message` class for MIME messages instead of hardcoding XML
344- When creating random variable names prefer `Rex::RandomIdentifier::Generator` and specify the runtime language used. This avoids generating language keywords that would break the script
345- Use `Msf::Exploit::SQLi` when exploiting SQL injection vulnerabilities
346 
347## Common Patterns
348 
349### Options Registration
350 
351```ruby
352register_options([
353  OptString.new('TARGETURI', [true, 'Base path to the application', '/']),
354  OptInt.new('TIMEOUT', [true, 'Request timeout in seconds', 10]),
355  OptBool.new('SSL', [false, 'Use SSL/TLS', false])
356])
357 
358register_advanced_options([
359  OptString.new('UserAgent', [false, 'Custom User-Agent header'])
360])
361```
362 
363- Use `SCREAMING_SNAKE_CASE` for standard option names and `CamelCase` for advanced option names
364- Access options via `datastore['OPTION_NAME']`
365 
366### Console Output
367 
368- Use `print_status`, `print_good`, `print_error`, `print_warning` for console output
369- Use `vprint_*` variants for verbose-only output (shown when user sets `VERBOSE true`)
370 
371### HTTP Response Handling
372 
373```ruby
374res = send_request_cgi(
375  'method' => 'GET',
376  'uri' => normalize_uri(target_uri.path, 'api', 'version')
377)
378 
379fail_with(Failure::Unreachable, 'Target did not respond') unless res
380fail_with(Failure::UnexpectedReply, "Unexpected status: #{res.code}") unless res.code == 200
381 
382json = res.get_json_document
383fail_with(Failure::UnexpectedReply, 'Response is not valid JSON') if json.empty?
384 
385# For HTML parsing:
386html = res.get_html_document
387version = html.at_css('meta[name="version"]')&.[]('content')
388```
389 
390- Always use `res.get_json_document` — never `JSON.parse(res.body)`
391- Use `res.get_html_document` with CSS selectors for HTML parsing
392- Check `res` for nil (target didn't respond) before accessing `.code` or `.body`
393- Use `fail_with(Failure::*, 'reason')` for error conditions in `exploit`/`run`
394 
395### Network Operations
396 
397- Use `send_request_cgi` for HTTP requests in modules
398- Use `connect` / `disconnect` for TCP socket operations
399- Use the `srvhost` method to access the server host — don't use `datastore['SRVHOST']` directly (enforced by `Lint/DatastoreSrvhostUsage` cop)
400 
401## Legacy Patterns (Migration Guidance)
402 
403These patterns exist in older code but should not be used in new modules or library code. When touching existing code that uses these patterns, prefer modernizing it:
404 
405| Legacy Pattern | Modern Replacement | Notes |
406|---------------|-------------------|-------|
407| `HttpFingerprint = { :pattern => [...] }` | Implement a `check` method + `prepend AutoCheck` | HttpFingerprint is a passive fingerprinting mechanism that predates the check API |
408| `cmd_exec("command #{user_input}")` | `create_process("command", args: [user_input])` | String interpolation in cmd_exec is a command injection risk; create_process separates executable from arguments by design |
409| `cmd_exec(cmd, args_string, timeout)` | `create_process(cmd, args: args_array, time_out: timeout)` | Enforced by `Lint/DetectOutdatedCmdExecApi` rubocop cop |
410| `DefaultOptions => { 'PAYLOAD' => '...' }` | Remove — let the framework choose automatically | Only acceptable when the module genuinely only works with a single specific payload |
411| `include Msf::Exploit::Remote::AutoCheck` | `prepend Msf::Exploit::Remote::AutoCheck` | Include raises NotImplementedError; prepend is required |
412| Bare `rescue` in library code | `rescue StandardError => e` | Bare rescue discards the exception object; `rescue Exception` is worse — it catches signals/exits |
413| `raise "error message"` in library code | `raise Rex::RuntimeError, "message"` | Specific classes enable targeted error handling |
414| Manual `check` call inside `exploit` | `prepend AutoCheck` + separate `check` method | Let the framework handle check-before-exploit |
415 
416### Modernizing Existing Modules
417 
418When updating an existing module, the lowest-effort improvement is adding AutoCheck:
419 
420```ruby
421# If the module already has a `def check` method, just add this line
422# after the other includes:
423prepend Msf::Exploit::Remote::AutoCheck
424```
425 
426This single addition gives users the ability to verify vulnerability before exploitation, with automatic abort if the target is not vulnerable (overridable with `set ForceExploit true`).
427 
428## Before Submitting
429 
430- Work on a topic branch — don't commit directly to `master`
431- Follow the [50/72 rule](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) for Git commit messages (50 char subject, 72 char body wrap)
432- Ensure `rubocop` and `msftidy` pass on any changed files with no new offenses
433- Ensure `ruby tools/dev/msftidy_docs.rb <documentation_file>` passes on any changed documentation markdown docs with no new offenses
434- Include console output (especially `msfconsole` demonstrations) in your pull request when the changes have observable effects
435- Include verification steps so reviewers can test your changes
436- Reference associated issues in your pull request description (e.g., `See #1234`)
437 
438## What NOT to Do
439 
440- Don't submit untested code — all code must be manually verified
441- Don't include sensitive information (IPs, credentials, API keys, hashes of credentials) in code or docs
442- Don't include more than one module per pull request
443- Don't add new scripts to `scripts/` — use post modules instead
444- Don't use `pack`/`unpack` with invalid directives (enforced by linter)
445