pentest-mcp-server

<div align="center">
  <h1>@cyanheads/pentest-mcp-server</h1>
  <p><b>Offline methodology engine and payload workshop for authorized penetration testing, CTF, security research, and education via MCP. STDIO or Streamable HTTP.</b>
  <div>7 Tools</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.8-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pentest-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pentest-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pentest-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/pentest-mcp-server/releases/latest/download/pentest-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=pentest-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvcGVudGVzdC1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22pentest-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fpentest-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://pentest.caseyjhand.com/mcp](https://pentest.caseyjhand.com/mcp)

</div>

---

> **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.

---

## Tools

Seven tools spanning the full authorized-testing workflow — from initial scoping through response analysis and payload generation:

| Tool | Description |
|:-----|:------------|
| `pentest_guide` | Returns a step-by-step methodology playbook for the given attack vector, scoped to authorized testing. Each phase covers what to look for, tools, detection indicators for defenders, and mitigations. |
| `pentest_analyze_response` | Analyzes a raw server response (headers + body) from authorized probing for information leakage, fingerprinting signals, and exploitation opportunities — each finding paired with remediation. |
| `pentest_lookup_technique` | Looks up a MITRE ATT&CK technique by ID or keyword. Returns description, tactics, detection data sources, behavioral indicators, mitigations, and real-world procedure examples. |
| `pentest_lookup_group` | Looks up a MITRE ATT&CK threat group or software entry by ID or name. Returns aliases, type (group vs. software), description, and the techniques it uses with procedure context. |
| `pentest_map_techniques` | Given a target profile (stack, services, auth type, OS), returns ranked ATT&CK techniques and OWASP test cases most relevant to that authorized engagement. |
| `pentest_generate_payloads` | Generates annotated payload templates for authorized testing. Each template includes why it works in the injection context, detection signatures, and mitigations. |
| `pentest_encode` | Applies an encoding chain to a payload string (URL, double-URL, HTML entity, Unicode, hex, Base64, and more). Returns step-by-step decode explanation and bypass rationale. |

### `pentest_guide`

Instruction tool. Returns a structured attack methodology playbook for the given vector and optional target context.

- Fifteen attack vectors via a single `vector` enum: `auth_bypass`, `idor`, `ssrf`, `xss`, `sqli`, `xxe`, `path_traversal`, `cors`, `csrf`, `open_redirect`, `deserialization`, `race_condition`, `ssti`, `command_injection`, `jwt_attack`
- Optional `target_context` (`stack`, `waf`, `recon_notes`) narrows the playbook to stack-specific techniques and WAF-bypass-aware variants
- Phase filtering: `all`, `recon`, `enumeration`, `exploitation`, `post_exploitation`
- Every technique entry includes detection indicators and recommended mitigations — usable as a blue team planning aid
- `nextToolSuggestions` pre-filled with payload generator and ATT&CK lookup calls from the methodology context
- `authorized_use_reminder` field rendered as the first line of every response so the framing reaches all clients
- OWASP Testing Guide test case IDs and ATT&CK technique IDs included for cross-referencing

---

### `pentest_analyze_response`

Bridge tool. Paste raw HTTP output from authorized probing; get structured findings.

- Accepts `response_headers` (raw HTTP headers), `response_body` (up to 10,000 chars), `status_code`, and freeform `context`
- Detects: version disclosure, stack traces, internal paths, debug headers, technology fingerprints, auth patterns, CORS misconfigurations, missing security headers, interesting fields, error messages
- Each finding carries: category, severity (`info`/`low`/`medium`/`high`), what was detected, why it matters, how a defender would detect exploitation, and remediation
- Technology fingerprinting summary (`server_software`, `framework`, `language`, `database`, `cloud_provider`) ready for use as `target_context` in `pentest_guide` or `pentest_map_techniques`
- `nextToolSuggestions` pre-filled from fingerprints and findings

---

### `pentest_lookup_technique`

Single-record ATT&CK lookup. Accepts exact IDs (`T1190`, `T1059.001`) or keyword search.

- Full technique record: name, tactics, description, target platforms
- Detection context: summary, ATT&CK data sources (log sources, sensors), concrete behavioral indicators
- Mitigations: ATT&CK mitigation IDs, names, and descriptions
- Real-world procedure examples from public threat intelligence reporting
- Sub-technique inclusion toggle (`include_subtechniques`, default `true`)
- ATT&CK dataset version string in every response so callers know the data vintage

---

### `pentest_lookup_group`

ATT&CK threat group and software lookup. Accepts exact IDs (`G0007`, `S0002`) or name/keyword search (`APT28`, `Mimikatz`).

- Covers both intrusion sets (threat groups, G-prefix) and software entries (malware and tools, S-prefix)
- Returns: name, type (`group` or `software`), aliases, description, and up to 20 techniques used with procedure-level context
- Technique entries link directly to `pentest_lookup_technique` for full detection and mitigation context
- Equally useful for defenders building detection coverage around specific adversary tradecraft

---

### `pentest_map_techniques`

Discovery and ranking tool. Takes a target profile, returns prioritized testing scope.

- Profile inputs: `stack` (array of components), `services` (exposed interfaces), `auth_type` (jwt/session\_cookie/api\_key/oauth2/basic\_auth/ntlm/kerberos/none/unknown), `os` (linux/windows/macos/unknown)
- Transparent relevance scoring: 1 point per matching platform, 2 per matching service, 2 for auth type match — criteria documented in each result row so rankings are verifiable
- Each ranked technique includes: relevance rationale, detection opportunity, mitigation summary, and the `pentest_guide` vector for follow-up
- OWASP test cases mapped to the profile alongside ATT&CK techniques
- Configurable result count (1–50, default 15)

---

### `pentest_generate_payloads`

Context-aware payload template generator for authorized testing. Returns annotated templates — not live weaponized strings.

- Fourteen payload categories: `xss`, `sqli`, `ssrf`, `xxe`, `path_traversal`, `ssti`, `command_injection`, `open_redirect`, `csrf`, `deserialization`, `jwt`, `ldap_injection`, `nosql_injection`, `http_header`
- Sixteen injection contexts for precision targeting: `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`, `generic`
- WAF profile variants: `cloudflare`, `aws_waf`, `modsecurity_crs`, `imperva`, `akamai`, `f5_bigip_asm`, `nginx_modsecurity`, `fortinet_fortiwaf`, `none`, `unknown` — bypass variants reference public research per WAF product
- Optional encoding chain applied at generation time; up to 20 variants per request
- Each template annotated with: vulnerability class, detection signature, mitigation, and WAF bypass notes
- `authorized_use_reminder` rendered as the first line of every response

---

### `pentest_encode`

Pure transformation utility. Applies an ordered encoding chain to a payload string.

- Ten encoding types: `url`, `double_url`, `html_entity`, `unicode`, `hex`, `base64`, `js_escape`, `null_byte`, `mixed_case`, `comment_break`
- Chains up to 6 steps applied left-to-right; interme