Enhance contributing documentation with module structure templates and guidelines

.github/copilot-instructions.md

@@ -1,3 +1,5 @@
 # Copilot Instructions
 
 Refer to [AGENTS.md](../AGENTS.md) in the repository root for all project conventions, coding standards, and AI agent guidelines.
+
+Path-scoped instructions in `.github/instructions/` provide file-type-specific guidance for modules, library code, tests, and documentation.

.github/instructions/documentation.instructions.md

@@ -0,0 +1,24 @@
+---
+applyTo: "documentation/**/*.md"
+---
+
+# Module Documentation Instructions
+
+## Template
+
+Follow `documentation/modules/module_doc_template.md` for structure.
+
+## Required Sections
+
+1. **Introduction** — what the module does, what vulnerability it exploits
+2. **Vulnerable Application** — affected versions, fixed version, setup instructions
+3. **Verification Steps** — numbered steps to reproduce/verify
+4. **Scenarios** — must be filled out by a human with real console output
+
+## Rules
+
+- Run `ruby tools/dev/msftidy_docs.rb <file>` before submitting
+- Module descriptions should only use ASCII characters
+- Include the range of vulnerable versions and the fixed version when known
+- Do NOT include sensitive information (real IPs, credentials, API keys)
+- Local/private IPs are acceptable in scenario examples

.github/instructions/library.instructions.md

@@ -0,0 +1,44 @@
+---
+applyTo: "lib/**/*.rb"
+---
+
+# Library Code Instructions
+
+## Error Handling
+
+- Use specific error classes: `Rex::RuntimeError`, `Rex::ConnectionError`, `Rex::TimeoutError`, `ArgumentError`
+- NEVER `raise "bare string"` — makes targeted rescue impossible
+- NEVER bare `rescue` — it discards the exception object, making debugging impossible
+- NEVER `rescue Exception` — it catches `SignalException` and `SystemExit` (hides Ctrl-C and kill signals)
+- Always: `rescue StandardError => e` or more specific
+- Propagate with context: `raise Rex::ConnectionError, "Failed to connect to #{host}: #{e.message}"`
+
+## Documentation
+
+- Add YARD `@param` and `@return` tags to ALL public methods
+- Link to RFC/spec when implementing binary or protocol parsers
+- Add `# frozen_string_literal: true` to new files
+
+## Naming
+
+- Do NOT use `get_`/`set_` prefixes for accessor-style methods (use `def version` not `def get_version`)
+- Method parameter names must be at least 2 characters
+
+## Patterns
+
+- Use `Rex::Stopwatch.elapsed_time` for timing
+- Use `Rex::MIME::Message` for MIME (not hardcoded XML)
+- Use `Rex::RandomIdentifier::Generator` for random variable names (specify target language)
+- Use `RubySMB` library for SMB operations
+
+## Testing
+
+- ALL library changes require RSpec tests in `spec/` mirroring `lib/` structure
+- Follow [Better Specs](https://www.betterspecs.org/) conventions
+- Run: `bundle exec rspec spec/path/to/spec.rb` or `:42` for single example
+
+## Quality
+
+- Keep PRs focused — small fixes are easier to review
+- When overriding `cleanup`, always call `super`
+- Hash cracking implementations require test hash in `tools/dev/hash_cracker_validator.rb`

.github/instructions/modules.instructions.md

@@ -0,0 +1,68 @@
+---
+applyTo: "modules/**/*.rb"
+---
+
+# Module Development Instructions
+
+## Structure Order
+
+1. `# frozen_string_literal: true`
+2. Header comment block
+3. `class MetasploitModule < Msf::Exploit::Remote` (or `Msf::Auxiliary`, `Msf::Post`)
+4. `Rank = ExcellentRanking` (exploits only)
+5. Protocol mixins (`include Msf::Exploit::Remote::HttpClient`, etc.)
+6. Utility mixins (`include Msf::Exploit::FileDropper`, etc.)
+7. `prepend Msf::Exploit::Remote::AutoCheck` — ALWAYS LAST
+8. `def initialize` with `update_info`
+9. `def check` (when possible)
+10. `def exploit` or `def run`
+
+## Required Metadata
+
+- `'Name'` — Vendor Product Vulnerability Type
+- `'Description'` — use `%q{}` for multi-line
+- `'Author'` — array with role comments
+- `'License'` — `MSF_LICENSE`
+- `'References'` — `[['CVE', '...'], ['URL', '...']]`
+- `'DisclosureDate'` — required for exploits
+- `'Notes'` — required with `Stability`, `SideEffects`, `Reliability`
+
+## Notes Hash Values
+
+Required for **exploits, auxiliary, and post** modules (enforced by rubocop). Not required for payloads, encoders, nops, or evasion.
+
+- **Stability:** `CRASH_SAFE`, `CRASH_SERVICE_RESTARTS`, `CRASH_SERVICE_DOWN`, `CRASH_OS_RESTARTS`, `CRASH_OS_DOWN`
+- **SideEffects:** `IOC_IN_LOGS`, `ARTIFACTS_ON_DISK`, `CONFIG_CHANGES`, `ACCOUNT_LOCKOUTS`, `SCREEN_EFFECTS`
+- **Reliability:** `REPEATABLE_SESSION`, `FIRST_ATTEMPT_FAIL`, `UNRELIABLE_SESSION`, `EVENT_DEPENDENT`
+
+Valid 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).
+
+## Payload Selection
+
+- Command execution only → `ARCH_CMD` payloads
+- Only HTTP outbound (curl/wget) → fetch payload
+- File write possible → dropper/EXE (`Msf::Exploit::EXE`)
+- Multi-step upload → `Msf::Exploit::CmdStager` (but prefer fetch when possible)
+
+## Do NOT
+
+- Set `DefaultOptions => { 'PAYLOAD' => '...' }` unless platform-locked
+- Use `cmd_exec` with string interpolation — use `create_process(exe, args: [])`
+- Use `HttpFingerprint` — implement a proper `check` method instead
+- Use `include` for AutoCheck — must be `prepend`
+- Return bare `CheckCode::Safe` without a reason string
+- Use `JSON.parse(res.body)` — use `res.get_json_document`
+- Print `"#{ip}:#{port}"` — use `Rex::Socket.to_authority(ip, port)`
+
+## Auxiliary Modules
+
+- Inherit from `Msf::Auxiliary` (not `Msf::Exploit::Remote`)
+- Use `def run` (not `def exploit`)
+- Use `report_service` / `report_vuln` for findings
+
+## Post Modules
+
+- Inherit from `Msf::Post`
+- Declare `'SessionTypes' => ['meterpreter', 'shell']`
+- Use `create_process` for command execution (not `cmd_exec` with args)
+- Use `Msf::OptionalSession` for modules that work with or without sessions

.github/instructions/tests.instructions.md

@@ -0,0 +1,37 @@
+---
+applyTo: "spec/**/*_spec.rb"
+---
+
+# RSpec Test Instructions
+
+## Conventions
+
+- Follow [Better Specs](https://www.betterspecs.org/)
+- Mirror `lib/` structure: `lib/msf/core/exploit/remote/http_client.rb` → `spec/lib/msf/core/exploit/remote/http_client_spec.rb`
+- Use `described_class` instead of repeating the class name
+- One expectation per example when practical
+- Use `let` and `let!` for setup, `before` for side effects
+
+## Running Tests
+
+- Single file: `bundle exec rspec spec/path/to/spec.rb`
+- Single example: `bundle exec rspec spec/path/to/spec.rb:42`
+- Full suite: `bundle exec rake spec` (slow — avoid during development)
+
+## Test Data
+
+- Use TEST-NET-1 (`192.0.2.0/24`) for example IP addresses — never real IPs
+- Use `Rex::Text.rand_text_alphanumeric` for random test data
+- Use the `Faker` gem (e.g. `Faker::Internet.username`) for usernames/accounts
+
+## Module Specs
+
+- Module functional tests live in `spec/modules/`
+- Test end-to-end behaviour including `check` and `exploit`/`run` methods
+
+## What to Test
+
+- Public API methods — inputs, outputs, edge cases
+- Error handling paths — verify correct exception classes raised
+- Protocol parsing — round-trip encode/decode
+- Version comparison logic — boundary conditions