Copilot instructions

1---
2applyTo: "modules/**/*.rb"
3---
4 
5# Module Development Instructions
6 
7## Structure Order
8 
91. Header comment block
102. `class MetasploitModule < Msf::Exploit::Remote` (or `Msf::Auxiliary`, `Msf::Post`)
113. `Rank = ExcellentRanking` (exploits only)
124. Protocol mixins (`include Msf::Exploit::Remote::HttpClient`, etc.)
135. Utility mixins (`include Msf::Exploit::FileDropper`, etc.)
146. `prepend Msf::Exploit::Remote::AutoCheck` — ALWAYS LAST
157. `def initialize` with `update_info`
168. `def check` (when possible)
179. `def exploit` or `def run`
18 
19## Required Metadata
20 
21- `'Name'` — Vendor Product Vulnerability Type
22- `'Description'` — use `%q{}` for multi-line
23- `'Author'` — array with role comments
24- `'License'` — `MSF_LICENSE`
25- `'References'` — `[['CVE', '...'], ['URL', '...']]`
26- `'DisclosureDate'` — required for exploits
27- `'Notes'` — required with `Stability`, `SideEffects`, `Reliability`
28 
29## Notes Hash Values
30 
31Required for **exploits, auxiliary, and post** modules (enforced by rubocop). Not required for payloads, encoders, nops, or evasion.
32 
33- **Stability:** `CRASH_SAFE`, `CRASH_SERVICE_RESTARTS`, `CRASH_SERVICE_DOWN`, `CRASH_OS_RESTARTS`, `CRASH_OS_DOWN`
34- **SideEffects:** `IOC_IN_LOGS`, `ARTIFACTS_ON_DISK`, `CONFIG_CHANGES`, `ACCOUNT_LOCKOUTS`, `SCREEN_EFFECTS`
35- **Reliability:** `REPEATABLE_SESSION`, `FIRST_ATTEMPT_FAIL`, `UNRELIABLE_SESSION`, `EVENT_DEPENDENT`
36 
37Valid values with descriptions: [`lib/msf/core/constants.rb`](../../lib/msf/core/constants.rb). Platform classes: [`lib/msf/core/module/platform.rb`](../../lib/msf/core/module/platform.rb).
38 
39## Payload Selection
40 
41- Command execution only → `ARCH_CMD` payloads
42- Only HTTP outbound (curl/wget) → fetch payload
43- File write possible → dropper/EXE (`Msf::Exploit::EXE`)
44- Multi-step upload → `Msf::Exploit::CmdStager` (but prefer fetch when possible)
45 
46## Do NOT
47 
48- Set `DefaultOptions => { 'PAYLOAD' => '...' }` unless platform-locked
49- Use `cmd_exec` with string interpolation — use `create_process(exe, args: [])`
50- Use `HttpFingerprint` — implement a proper `check` method instead
51- Use `include` for AutoCheck — must be `prepend`
52- Return bare `CheckCode::Safe` without a reason string
53- Use `JSON.parse(res.body)` — use `res.get_json_document`
54- Print `"#{ip}:#{port}"` — use `Rex::Socket.to_authority(ip, port)`
55 
56## Auxiliary Modules
57 
58- Inherit from `Msf::Auxiliary` (not `Msf::Exploit::Remote`)
59- Use `def run` (not `def exploit`)
60- Use `report_service` / `report_vuln` for findings
61 
62## Post Modules
63 
64- Inherit from `Msf::Post`
65- Declare `'SessionTypes' => ['meterpreter', 'shell']`
66- Use `create_process` for command execution (not `cmd_exec` with args)
67- Use `Msf::OptionalSession` for modules that work with or without sessions
68