Skip to content
BreachPilot

Exploit MCP Server

Permissive exploitation surface at mcp_exploit_server.py:1-224. Separate from mcp_server.py (defensive) — this server provides full terminal, exploit-db, Metasploit, payload, credential, AD/Kerberos, session, domain, recon, and research tools. All tools are gated at the MCP tool layer (target-IP allowlist lock), not in the server shim (mcp_exploit_server.py:7 docstring).

Server Identity

  • FastMCP name: AI Exploitation Tools (mcp_exploit_server.py:76-77)
  • Instructions: long permissive prompt listing terminal, Metasploit, payload, research, file, opsec, and cracking guidance (mcp_exploit_server.py:78-123)
  • json_response=True (mcp_exploit_server.py:124)
  • Transports: stdio (default) or http (mcp_exploit_server.py:192-219)
  • Default HTTP port: 8001 (mcp_exploit_server.py:197)
  • Workspace: exploit_workspace default (mcp_exploit_server.py:177), resolved and mkdir -p plus _ensure_workspace_dirs (mcp_exploit_server.py:128-129)

Factory

create_mcp_server(search, nvd, researcher, workspace, config) (mcp_exploit_server.py:68-173):

workspace.mkdir(parents=True, exist_ok=True)
_ensure_workspace_dirs(workspace)  # plans/exploits/modules/campaigns
require_allowlist = make_require_allowlist(workspace, config)
audit_tool = make_audit_tool(workspace)
ctx = ToolContext(workspace, config, search, nvd, researcher, audit_tool, require_allowlist)
for registrar in collect_tools():
    registrar(mcp, ctx=ctx)
# then plugin factories via PLUGIN_REGISTRY.mcp_tool_factories (best-effort)

ToolContext (tools/mcp_tools/registry.py:102-111) is frozen dataclass workspace, config, search, nvd, researcher, audit_tool, require_allowlist. Families import from tools.mcp_tools.registry import * and use ctx.

Shared services are built by tools/mcp_shared.build_search / build_cve_search / build_researcher and threaded via ctx.

Registry Discovery — Single-Source Registration

Adding a new exploit MCP tool requires one file edit: add @audit_tool or @require_allowlist() function in tools/mcp_tools/<family>.py. No manual list edit in mcp_exploit_server.py (mcp_exploit_server.py:145-157 comment).

Flow:

  1. collect_tools() (tools/mcp_tools/registry.py:391-405) calls _discover_tool_registrars() + _validate_mcp_tool_decorators().
  2. _discover_tool_registrars() (tools/mcp_tools/registry.py:311-342) walks tools.mcp_tools via pkgutil.iter_modules, imports each submodule (skips registry), and collects every callable named register_*_tools. Result cached in _TOOL_REGISTRARS after first call. Explicit @register_tool_family entries are merged.
  3. _validate_mcp_tool_decorators() (tools/mcp_tools/registry.py:345-388) parses each tools/mcp_tools/*.py with ast and verifies every function decorated with @mcp.tool also has audit_tool or require_allowlist (substring match on ast.unparse(decorator) lowercased). Offenders raise RuntimeError listing file:line name so CI fails.
  4. mcp_exploit_server.py iterates registrars, warns on per-family exception (mcp_exploit_server.py:153-157) — one bad family never breaks the rest.
  5. Plugin factories (PLUGIN_REGISTRY.mcp_tool_factories) are best-effort after that (mcp_exploit_server.py:159-171).

Adding a new family: create tools/mcp_tools/foo.py with def register_foo_tools(mcp, ctx): ... — no edit to mcp_exploit_server.py or registry.py.

Patch points retained for tests (mcp_exploit_server.py:50-51):

  • mcp_exploit_server._run_with_pgrp_timeout (proxied via tools/mcp_tools/registry._run_with_pgrp_timeout shim)
  • mcp_exploit_server._get_model_router

Workspace / Audit Helpers

Re-exported for back-compat (mcp_exploit_server.py:55-63):

  • _find_file, _resolve_workspace_file, _attempt_dir, make_require_allowlist, make_audit_tool — all from tools/mcp_shared / tools/kernel/*.

CLI Entrypoint

parse_args (mcp_exploit_server.py:191-203) and main (mcp_exploit_server.py:206-220):

  • --config config.yaml, --workspace exploit_workspace, --transport stdio|http, --host 127.0.0.1, --port 8001, --allow-public-bind
  • Loads config, loads API keys, builds search/NVD/researcher, calls create_mcp_server, then mcp.run(transport="stdio") or run_http_server(mcp, host, port, allow_public_bind).
  • run_http_server (mcp_exploit_server.py:180-188) delegates to tools.mcp_shared.run_mcp_http_server (shared loopback + bearer gate).

Current Families (20 registrars)

Discovered by collect_tools() (20 as of this doc):

ad, assessment_state, attack_modules, cracking, credentials, domain, metasploit, mitre, parallel_agents, payloads, peer_models, poc_verifier, recon, replay_simulator, research, runtime_skills, sessions, terminal, web_scan, workspace

Each family doc under docs/mcp/tool-families/ lists exact exported tool names.

  • docs/mcp/registration.md — decorator contract and AST validation detail
  • docs/mcp/security.md — allowlist lock and audit
  • docs/mcp/lifecycle.md — boot sequence and env propagation
  • docs/mcp/tool-families/*.md — per-family tables
source: repo docs (build sync)Edit this page on GitHub →