feat: Rapid7 parity + MCP-spec modernization (v3.1.0) - #20
Merged
Conversation
Phase 1 of official-parity-and-mcp-modernization. Adds six read-only workspace DB tools mirroring the official Rapid7 MCP: list_hosts, list_services, list_vulnerabilities, list_notes, list_credentials, list_loot. Backed by a shared _db_intel() helper (workspace scoping, msgpack byte normalization via _decode_rpc, and a _db_connected probe) that returns a structured "database_unavailable" error instead of raising when no DB is attached. health_check now reports database_connected. Adds tests/test_db_intel.py. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ety gate Phase 1 completion + Phase 2 of official-parity-and-mcp-modernization: - check_vulnerability: runs a module's non-destructive `check` only (never fires the exploit / delivers a payload / opens a session), mapping the result to a structured state (vulnerable / safe / unsupported / unknown). - get_module_results: retrieves status + output for an async execution by uuid, with a structured not-found error for unknown ids. - Safety controls: state-changing tools (run_exploit, run_auxiliary_module, run_post_module, generate_payload, send_session_command, terminate_session, start_listener, stop_job, kill_all_handler_jobs) are gated behind a default-off dangerous-actions flag (--allow-dangerous / MSF_MCP_ALLOW_DANGEROUS) plus a configurable rate limiter (--rate-limit / MSF_MCP_RATE_LIMIT). health_check now reports the safety posture. Tests enable dangerous actions via conftest. Adds tests/test_check_and_results.py and tests/test_safety_controls.py. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 3 (annotations) of official-parity-and-mcp-modernization. Introduces a single TOOL_ANNOTATIONS taxonomy and an annotated_tool decorator so every tool advertises MCP hints (readOnlyHint / destructiveHint / idempotentHint / openWorldHint). The destructive set is the authoritative classification shared with the @dangerous_tool safety gate. Adds tests/test_annotations.py. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… confirm
Phase 3 (groups 6-7) of official-parity-and-mcp-modernization:
- Structured output: FastMCP already emits an output schema + structured content
for the Dict-returning tools while preserving the text representation; locked
in with tests/test_structured_output.py.
- Resources: msf://server/info (identity, safety posture, tool taxonomy) and a
msf://module/{module} documentation template.
- Elicitation: optional confirmation (--confirm-dangerous / MSF_MCP_CONFIRM_DANGEROUS)
for destructive tools via ctx.elicit, with a gate fallback when the client
cannot elicit; decline yields a structured cancelled result.
Adds tests/test_resources_and_elicitation.py.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…kage)
Phase 4 of official-parity-and-mcp-modernization. Attempted lifting the cap to
allow 3.4.x: fastmcp 3.4.5 fails to import ("cannot import name 'FastMCP' from
'fastmcp'") even after a clean reinstall, so the <3.4.0 cap is retained and the
rationale documented at the pin. Within the cap the resolver now uses fastmcp
3.3.1 (annotations, structured output, and elicitation all verified; full suite
green). Regenerates poetry.lock and sbom.json.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… a method) Live validation against a real msfrpcd surfaced 'bool object is not callable': on pymetasploit3 module objects, `.check` is a boolean indicating whether the module implements a check (not the method). Fix check_vulnerability to short -circuit unsupported modules via that flag and invoke the check through the module.check RPC (moduletype, modulename, options). Updated unit tests to model the real API. Verified end-to-end against msfrpcd (returns a structured check_state with no session created). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…rsion bump - Add docs/MCP_API.md: full tool/resource reference, safety model, MCP spec conformance, and a comparison with the official Rapid7 MCP. - README: install via PyPI first (pip install metasploit-mcp) with source as the dev alternative; document the default-off safety posture and --allow-dangerous; add the new tools and MCP-protocol features; update the Claude Desktop config. - Bump version to 3.1.0 across pyproject, server.json, and the in-package __version__ (fixing a 3.0.0 drift); add the 3.1.0 CHANGELOG section; regen SBOM. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…archive change Reverse the safety posture: this is an offensive-security tool whose full toolset has always been available, so defaulting dangerous actions to OFF would regress existing users. Dangerous tools are now ENABLED by default; harden a deployment with --safe-mode (or MSF_MCP_ALLOW_DANGEROUS=false) for read-only tools, and the rate limit is OFF by default (opt in via --rate-limit). This intentionally inverts the official Rapid7 server's default-off posture. - server.py: default DANGEROUS_ACTIONS_ENABLED=True, RATE_LIMIT_PER_MIN=0; gate message now references safe mode. - __init__.py: add --safe-mode; --allow-dangerous retained (now the default). - Update spec, README, docs/MCP_API.md, and CHANGELOG to the enabled-by-default posture; add default-posture tests. - Archive the completed official-parity-and-mcp-modernization OpenSpec change; sync its 5 capability specs into openspec/specs/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the full
official-parity-and-mcp-modernizationOpenSpec change end-to-end, validated against a real Metasploit instance.New capabilities
Parity with the official Rapid7 MCP
list_hosts,list_services,list_vulnerabilities,list_notes,list_credentials,list_loot— workspace-scoped, degrade to a structureddatabase_unavailableerror when no DB is attached.check_vulnerability— runs a module's non-destructivecheckonly (never exploits / delivers a payload / opens a session); structuredvulnerable｜safe｜unsupported｜unknownstate.get_module_results— retrieve status/output of an async run by UUID.Safety (default-safe posture)
--allow-dangerous/MSF_MCP_ALLOW_DANGEROUS.--rate-limit/MSF_MCP_RATE_LIMIT).health_checkreportsdatabase_connectedand thesafetyposture.MCP protocol modernization
readOnly/destructive/idempotent/openWorld) on all 24 tools, from one taxonomy shared with the safety gate.structuredContent, text fallback preserved).msf://server/info,msf://module/{module}.--confirm-dangerous) with gate fallback.<3.4.0(3.4.x fails to import; 3.3.x used & verified). Rationale documented at the pin.Real-Metasploit validation
Ran against a live
msfrpcd+ database. Verified:health_check(db connected, safety posture),list_exploits, a realrun_auxiliary_moduleport scan whose results flowed intolist_services, all six DB-intel tools,check_vulnerability(real check → structured state, no session),generate_payload(real msfvenom ELF), the safety gate (blocks when off, read-only still works), and themsf://server/inforesource.Docs & packaging
pip install metasploit-mcp), source as the dev path; documented safety posture; Claude Desktop config updated.pyproject/server.json/__version__(fixes a 3.0.0 drift); CHANGELOG + SBOM updated.Verification
black,sbom --checkclean.test_db_intel,test_check_and_results,test_safety_controls,test_annotations,test_structured_output,test_resources_and_elicitation.Follow-ups (tracked)
get_module_resultsfor an unknown UUID returnsrunningon real MSF (it doesn't distinguish unknown from pending); the not-found path covers empty responses.mypyfrom advisory to blocking once the pre-existing backlog is cleared.🤖 Generated with Claude Code