io.github.cyanheadsPublished by GitHub account cyanheadsv0.3.0Updated Oct 30, 2026
Offline methodology engine for authorized penetration testing, CTF, and security research.
Offline penetration-testing methodology engine that gives an assistant ATT&CK lookups, OWASP test playbooks, HTTP response analysis and payload templates.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.cyanheads%2Fpentest-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"pentest": {
"type": "http",
"url": "https://pentest.caseyjhand.com/mcp"
}
}
}Offline methodology engine and payload workshop for authorized penetration testing, CTF, security research, and education via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://pentest.caseyjhand.com/mcp
Authorized use only. This server is designed for penetration testers, red teamers, CTF players, security researchers, and students working on systems they own or have explicit written authorization to test. Users are solely responsible for ensuring their testing is lawful and appropriately scoped. Unauthorized access to computer systems is illegal — this server does not and cannot enforce authorization on your behalf.
Dual-audience design. Every offensive technique is paired with detection indicators and mitigations. Blue teamers, developers, and anyone building detection coverage will find the methodology and ATT&CK data as useful as the red team workflows.
An offline methodology engine for authorized penetration testing, CTFs, and security research, built on MITRE ATT&CK, the OWASP Testing Guide, and annotated payload templates. Generate a phased test plan, map techniques to a target, analyze HTTP responses for leaks, and generate or encode payloads, each paired with detection and mitigation context.
pentest_get_guide toolvector: auth_bypass, idor, ssrf, xss, sqli, xxe, path_traversal, cors, csrf, open_redirect, deserialization, race_condition, ssti, command_injection, or jwt_attack; phase: all (default), recon, enumeration, exploitation, or post_exploitationdetection and mitigation, with owasp_references, attack_technique_ids, and context-derived nextToolSuggestionstarget_context (stack, waf, recon_notes) narrows the playbookpentest_analyze_response toolresponse_headers (≤20,000 characters), response_body (≤10,000 characters), or both; optional status_code (100–599) and context (≤2,000 characters). Missing both response fields returns no_inputcategory, severity (info/low/medium/high), detection, and remediation, ordered by severity descendingfingerprints (server_software, framework, language, database, cloud_provider, other) and nextToolSuggestions support follow-up callspentest_lookup_technique toolT1190, T1059.001) or keyword; include_subtechniques defaults to truedetection (summary, data_sources, indicators), mitigations, procedure examples, and attack_versionno_match when the ID or keyword resolves to nothingpentest_lookup_group toolG0007), software ID (S0002), or name/keyword; returns no_match when nothing resolvestype distinguishes group from software; results include aliases, description (≤800 characters), and attack_versiontechniques_used returns up to 20 techniques with procedure context and technique_id for pentest_lookup_techniquepentest_map_techniques toolstack, services, auth_type (jwt/session_cookie/api_key/oauth2/basic_auth/ntlm/kerberos/none/unknown), or os (linux/windows/macos/unknown); otherwise returns no_profileranked_techniques carries relevance_score, relevance_rationale, detection_opportunity, mitigation_summary, and optional pentest_guide_vector; owasp_test_cases returns up to 10 caseslimit caps techniques at 1–50 (default 15); enrichment (truncated, shown, cap) discloses the cappentest_generate_payloads toolcategory: xss, sqli, ssrf, xxe, path_traversal, ssti, command_injection, open_redirect, csrf, deserialization, jwt, ldap_injection, nosql_injection, or http_header; injection_context: html_attribute, html_body, js_string, js_template, js_script_block, url_parameter, url_path, sql_where, sql_integer, xml_element, xml_attribute, http_header, json_value, cookie_value, file_name, or genericcount caps templates at 1–20 (default 5); each carries detection_signature and mitigation, with optional encoding applied to every templatewaf_profile: cloudflare, aws_waf, modsecurity_crs, imperva, akamai, f5_bigip_asm, nginx_modsecurity, fortinet_fortiwaf, none (default), or unknown; profiles other than none add waf_bypass_notepentest_encode_payload toolpayload accepts up to 10,000 characters; chain applies 1–6 steps left to right from url, double_url, html_entity, unicode, hex, base64, js_escape, null_byte, mixed_case, or comment_breakintermediate_steps and detection_note; explain (default true) adds decode_path and bypass_rationaleencoding_error when a transform failsBuilt on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
Methodology-specific:
scripts/refresh-attack.ts and indexed in memory by ID/keyword; fails fast with an actionable error if the data file is missingreadOnlyHint: true, openWorldHint: false — deterministic output from a bounded embedded datasetAgent-friendly output:
authorized_use_reminder rendered as the first line of content[] on every guide/payload/encoding response — consistent framing regardless of which surface a client forwardsdetection and remediationattack_version echoed on every ATT&CK-backed response so callers can reason about data vintagenextToolSuggestions pre-filled with arguments derived from the current context, reducing agent planning overheadskill://pentest-guide/SKILL.mdThe server embeds MITRE ATT&CK Enterprise data (~20 MB JSON) fetched by a one-time script into a gitignored path. Self-hosters and Docker builders must run this step before the server will start:
This downloads the latest ATT&CK Enterprise JSON from the MITRE GitHub release endpoint, writes it to src/data/attack/enterprise.json (gitignored), and updates src/data/attack/version.ts with a version string such as Enterprise v16.1. The version file is committed; the JSON is not (too large for git history).
The Dockerfile handles this automatically — the build stage runs scripts/refresh-attack.ts before the TypeScript compile, so docker build produces a self-contained image.
If you clone the repo and skip this step, attack-service will fail fast at startup with an actionable error message pointing to scripts/refresh-attack.ts.
Run the script quarterly (or before each release) to pull the latest ATT&CK version.
Connect to the hosted instance:
Or run it locally:
For other clients, add this to the MCP config file:
No API keys required. For Docker or a source build, see Running the server.
No API keys required. The server is fully offline at runtime.
See .env.example for the full list of optional overrides.
With PENTEST_ENABLE_PAYLOAD_GENERATION=false, the two payload tools are absent from MCP discovery and calls.
Requires Bun v1.4.0 or higher (or Node.js v24+), with ATT&CK data seeded before startup.
Build and run:
Run checks and tests:
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/pentest-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them. The ATT&CK data refresh runs automatically in the build stage.
See CLAUDE.md for development guidelines and architectural rules. The short version:
ctx.fail contractctx.log for request-scoped logging and keep request handling stateless and deterministicsrc/mcp-server/tools/index.tsauthorized_use_reminder is a required output field on every tool that produces methodology or payload content — render it as the first line of every content[] response in format()detection and remediation required on response findingsIssues are welcome. Run checks and tests before submitting:
Apache-2.0 — see LICENSE for details.
Source: README.md at commit 0015795
Pentest Guide
Return an authorized-testing methodology for a selected vector and optional target context. The playbook covers reconnaissance, enumeration, exploitation, and post-exploitation phases with objectives, techniques, detection signals, mitigations, common pitfalls, references, and context-derived tool suggestions across 15 vectors.
phasevectorrequiredtarget_contextPentest Analyze Response
Analyze an HTTP response from authorized probing for information leakage, fingerprinting signals, and related exposure. Structured findings cover version disclosures, stack traces, debug headers, internal paths, authentication patterns, CORS configuration, detection signals, remediation, and associated methodology vectors.
contextstatus_coderesponse_bodyresponse_headersPentest Lookup Technique
Look up a MITRE ATT&CK technique by exact ID or keyword. Results include tactics, platforms, description, detection data, public procedure examples, mitigations, related sub-techniques, and dataset version.
queryrequiredinclude_subtechniquesPentest Lookup Group
Look up a MITRE ATT&CK threat group or software entry by ID, name, or keyword. Results include ATT&CK identity, aliases, type, description, and associated techniques with procedure-level context from public ATT&CK reporting.
queryrequiredPentest Map Techniques
Rank ATT&CK techniques and OWASP test cases against an authorized target profile of technology stack, exposed services, authentication type, and operating system. Results include profile-specific relevance, detection opportunities, mitigations, and associated methodology vectors.
oslimitstackservicesauth_typePentest Generate Payloads
Generate context-specific payload templates for authorized systems. Each template includes its vulnerability category, context rationale, WAF/IDS detection signature, mitigation, optional WAF research note, and optional encoded variant.
countcategoryrequiredencodingwaf_profileinjection_contextrequiredPentest Encode
Transform a payload string through an ordered encoding chain for authorized filter research. Results include the final value, intermediate values, optional decode path and rationale, and detection guidance. All transforms are local; no live probing occurs.
chainrequiredexplainpayloadrequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
bun run scripts/refresh-attack.tsclaude mcp add --transport http pentest-mcp-server https://pentest.caseyjhand.com/mcpclaude mcp add pentest-mcp-server -- npx -y @cyanheads/pentest-mcp-server{ "mcpServers": { "pentest-mcp-server": { "command": "npx", "args": ["-y", "@cyanheads/pentest-mcp-server"] } }}git clone https://github.com/cyanheads/pentest-mcp-server.gitcd pentest-mcp-server && bun installcp .env.example .env# Seed ATT&CK data (first time, or to update)bun run scripts/refresh-attack.ts
# Buildbun run rebuild
# Runbun run start:stdio# orbun run start:httpbun run devcheck # Lint, format, typecheck, security auditbun run test # Vitest test suitebun run lint:mcp # Validate MCP definitions# Build — ATT&CK data is fetched during the build stagedocker build -t pentest-mcp-server .docker run --rm -p 3010:3010 pentest-mcp-serverbun run devcheckbun run test