@cyanheads/pentest-mcp-server
by cyanheads
README.md
<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">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/pentest-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/pentest-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/pentest-mcp-server/releases/latest/download/pentest-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=pentest-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvcGVudGVzdC1tY3Atc2VydmVyIl19) [](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)
[](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.
---
## Overview
Offline penetration-testing methodology engine: MITRE ATT&CK techniques and threat groups, OWASP Testing Guide methodology, and annotated payload templates for authorized penetration testing, CTF, and security research. Generate a phased testing playbook, map techniques to a target profile, analyze HTTP responses for leakage, and generate or encode payload templates from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
### Tools
| Tool | Description |
|:-----|:------------|
| `pentest_guide` | Step-by-step authorized-testing methodology playbook for a chosen attack vector, phase-filterable, with detection and mitigation per technique. |
| `pentest_analyze_response` | Analyzes raw HTTP response headers/body from authorized probing for leakage, fingerprinting, and misconfiguration. |
| `pentest_lookup_technique` | Looks up a MITRE ATT&CK technique by ID or keyword, with detection data, mitigations, and procedure examples. |
| `pentest_lookup_group` | Looks up a MITRE ATT&CK threat group or software entry by ID or name, with aliases and technique usage. |
| `pentest_map_techniques` | Ranks ATT&CK techniques and OWASP test cases against a target profile (stack, services, auth type, OS). |
| `pentest_generate_payloads` | Generates annotated payload templates for a vulnerability category and injection context, with optional WAF bypass variants and encoding. |
| `pentest_encode` | Applies an ordered encoding chain to a payload string with decode-path tracing. |
## Capability reference
### `pentest_guide` <sub>tool</sub>
- 15 attack vectors via `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` filter: `all` (default), `recon`, `enumeration`, `exploitation`, or `post_exploitation`
- Every technique carries `detection` and `mitigation`; response also includes `owasp_references` (WSTG IDs) and `attack_technique_ids` for cross-referencing
- `authorized_use_reminder` rendered as the first line of every response
- `nextToolSuggestions` pre-filled with payload-generator and ATT&CK-lookup calls derived from the methodology context
---
### `pentest_analyze_response` <sub>tool</sub>
- Accepts `response_headers` (≤20,000 chars), `response_body` (≤10,000 chars), `status_code` (100–599), and freeform `context` (≤2,000 chars) — at least one of headers or body is required
- Detects 10 finding categories (version disclosure, stack traces, internal paths, debug headers, technology fingerprints, auth patterns, CORS misconfiguration, missing security headers, interesting fields, error messages), each with `severity` (`info`/`low`/`medium`/`high`)
- Each finding carries `detection` and `remediation`; results are ordered by severity descending
- `fingerprints` block (`server_software`, `framework`, `language`, `database`, `cloud_provider`, `other`) ready for use as target context in `pentest_guide` or `pentest_map_techniques`
- Typed `no_input` error when neither `response_headers` nor `response_body` is supplied
- `nextToolSuggestions` pre-filled from detected fingerprints and findings
---
### `pentest_lookup_technique` <sub>tool</sub>
- Accepts an exact ATT&CK ID (`T1190`, `T1059.001`) or a keyword; ID lookup is exact, keyword falls back to best-match search
- Returns tactics, platforms, description, detection (`summary`, `data_sources`, `indicators`), mitigations, and procedure examples from public ATT&CK reporting
- `include_subtechniques` (default `true`) toggles sub-technique inclusion
- `attack_version` echoes the embedded ATT&CK dataset version (e.g. "Enterprise v19.1") on every response
- Typed `no_match` error when the ID or keyword resolves to nothing
---
### `pentest_lookup_group` <sub>tool</sub>
- Accepts an exact ATT&CK group ID (`G0007`) or software ID (`S0002`), or a name/keyword (`APT28`, `Mimikatz`)
- `type` discriminates `group` (intrusion set) from `software` (malware/tool); `aliases` lists known alternate names
- `techniques_used` returns up to 20 techniques with procedure-level context, each linking to `pentest_lookup_technique` by `technique_id`
- `description` truncated to 800 characters
- Typed `no_match` error when the ID or name resolves to nothing
---
### `pentest_map_techniques` <sub>tool</sub>
- Profile inputs: `stack` (array), `services` (array), `auth_type` (`jwt`/`session_cookie`/`api_key`/`oauth2`/`basic_auth`/`ntlm`/`kerberos`/`none`/`unknown`), `os` (`linux`/`windows`/`macos`/`unknown`) — at least one required
- Relevance scoring adds points for platform, stack, service, and auth-type matches; each result's `relevance_rationale` lists exactly which criteria matched
- `limit` caps `ranked_techniques` at 1–50 (default 15); enrichment (`truncated`, `shown`, `cap`) discloses when results were capped
- Each ranked technique carries `detection_opportunity`, `mitigation_summary`, and an optional `pentest_guide_vector` for follow-up
- `owasp_test_cases` returns up to 10 relevant OWASP Testing Guide test cases
- Typed `no_profile` error when no profile field is supplied
---
### `pentest_generate_payloads` <sub>tool</sub>
- 14 payload categories (`xss`, `sqli`, `ssrf`, `xxe`, `path_traversal`, `ssti`, `command_injection`, `open_redirect`, `csrf`, `deserialization`, `jwt`, `ldap_injection`, `nosql_injection`, `http_header`) × 16 injection contexts (`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` (`cloudflare`, `aws_waf`, `modsecurity_crs`, `imperva`, `akamai`, `f5_bigip_asm`, `nginx_modsecurity`, `fortinet_fortiwaf`, `none` default, `unknown`) adds bypass variants referencing public research when set
- Optional `encoding` chain applied to each returned template; `count` caps results at 1–20 (default 5)
- Each payload carries `detection_signature` and `mitigation`; `waf_bypass_note` present only when `waf_profile` isn't `none`
- Templates are annotated placeholders, not live weaponized strings — `authorized_use_reminder` rendered first in every response
---
### `pentest_encode` <sub>tool</sub>
- `payload` string up to 10,000 characters; `chain` is an ordered list of 1–6 encoding steps applied left to right
- 10 encoding types: `url`, `double_url`, `html_entity`, `unicode`, `hex`, `base64`, `js_escape`, `null_byte`, `mixed_case`, `comment_break`
- `intermediate_steps` traces the value after each chain step; `explain` (default `true`) adds `decode_path` and `bypass_rationale`
- `detection_note` on every response — how defenders detect encoded variants
- Pure deterministic transforms, no live probing; typed `encoding_error` when a step produces invalid output
---
## Features
Built on [`@cyanheads/mcp-ts-core`](https://github.com/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:
- Fully offline at runtime — no external API calls, no credentials required; all data loaded at startup, zero I/O during request handling
- MITRE ATT&CK Enterprise embedded at build time via `scripts/refresh-attack.ts` and indexed in memory by ID/keyword; fails fast with an actionable error if the data file is missing
- OWASP Testing Guide methodology and payload template library curated as structured TypeScript modules, one per vector/category
- WAF bypass variants keyed by WAF product and attack vector, referencing public research
- All tools annotated `readOnlyHint: true`, `openWorldHint: false` — deterministic output from a bounded embedded dataset
Agent-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 forwards
- `detection` and `mitigation` fields required (non-optional) on every technique, finding, and payload — defenders always get usable context alongside offense technique
- `attack_version` echoed on every ATT&CK-backed response so callers can reason about data vintage
- `nextToolSuggestions` pre-filled with arguments derived from the current context, reducing agent planning overhead
---
## Build-time data step
The 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:**
```sh
bun run scripts/refresh-attack.ts
```
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.
---
## Getting started
### Public Hosted Instance
A public instance is available at `https://pentest.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:
```json
{
"mcpServers": {
"pentest-mcp-server": {
"type": "streamable-http",
"url": "https://pentest.caseyjhand.com/mcp"
}
}
}
```
### Self-Hosted / Local
Add the following to your MCP client configuration file.
```json
{
"mcpServers": {
"pentest-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/pentest-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
Or with npx (no Bun required):
```json
{
"mcpServers": {
"pentest-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/pentest-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
Or with Docker:
```json
{
"mcpServers": {
"pentest-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"ghcr.io/cyanheads/pentest-mcp-server:latest"
]
}
}
}
```
For Streamable HTTP, set the transport and start the server:
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp
```
### Prerequisites
- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
- ATT&CK data seeded — run `bun run scripts/refresh-attack.ts` once after cloning (Docker builds handle this automatically).
### Installation
1. **Clone the repository:**
```sh
git clone https://github.com/cyanheads/pentest-mcp-server.git
```
2. **Navigate into the directory:**
```sh
cd pentest-mcp-server
```
3. **Install dependencies:**
```sh
bun install
```
4. **Seed the ATT&CK data:**
```sh
bun run scripts/refresh-attack.ts
```
5. **Configure environment:**
```sh
cp .env.example .env
# edit .env if needed — no required vars beyond transport defaults
```
---
## Configuration
No API keys required. The server is fully offline at runtime.
| Variable | Description | Default |
|:---------|:------------|:--------|
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
| `MCP_LOG_LEVEL` | Log level: `debug`, `info`, `notice`, `warning`, `error`. | `info` |
| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
| `OTEL_ENABLED` | Enable OpenTelemetry instrumentation (spans, metrics, completion logs). | `false` |
See [`.env.example`](./.env.example) for the full list of optional overrides.
---
## Running the server
### Local development
- **Build and run:**
```sh
# Seed ATT&CK data (first time, or to update)
bun run scripts/refresh-attack.ts
# Build
bun run rebuild
# Run
bun run start:stdio
# or
bun run start:http
```
- **Run checks and tests:**
```sh
bun run devcheck # Lint, format, typecheck, security audit
bun run test # Vitest test suite
bun run lint:mcp # Validate MCP definitions
```
### Docker
```sh
# Build — ATT&CK data is fetched during the build stage
docker build -t pentest-mcp-server .
docker run --rm -p 3010:3010 pentest-mcp-server
```
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.
---
## Project structure
| Directory / File | Purpose |
|:-----------------|:--------|
| `src/index.ts` | `createApp()` entry point — registers tools and initializes services. |
| `src/services/attack/` | MITRE ATT&CK service — loads and indexes the embedded enterprise JSON at startup. |
| `src/services/methodology/` | OWASP Testing Guide methodology service — vector branches for `pentest_guide`. |
| `src/services/payload/` | Payload template service — keyed by category and injection context. |
| `src/services/encoding/` | Encoding chain executor — pure TypeScript transforms. |
| `src/services/response-analysis/` | Pattern library for information leakage and fingerprinting detection. |
| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`) — one file per tool. |
| `src/data/attack/` | `enterprise.json` (gitignored, fetched by `scripts/refresh-attack.ts`) + committed `version.ts`. |
| `src/data/owasp/` | Curated OWASP TG v4.2 methodology content as TypeScript modules. |
| `src/data/payloads/` | Annotated payload templates by vulnerability category. |
| `src/data/waf-bypass/` | WAF bypass variants keyed by product and attack vector. |
| `src/data/encodings/` | Encoding transform functions. |
| `src/data/patterns/` | Regex patterns and metadata for response leakage detection. |
| `scripts/refresh-attack.ts` | Downloads ATT&CK Enterprise JSON and updates the version string. Run once after cloning, then quarterly. |
| `tests/` | Unit and integration tests mirroring `src/`. |
| `docs/design.md` | Design document — tool surface, data strategy, and architectural decisions. |
---
## Development guide
See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
- Handlers throw and the framework catches; catch only to translate an owned operational failure into a declared `ctx.fail` contract
- Use `ctx.log` for request-scoped logging and keep request handling stateless and deterministic
- Register new tools via the barrel in `src/mcp-server/tools/index.ts`
- External source boundary: validate raw data, normalize to a domain type, then return the output schema; never fabricate missing fields
- `authorized_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()`
- Every technique, finding, and payload object has required (non-optional) `detection` and `mitigation` fields — this is a schema contract, not documentation guidance
---
## Contributing
Issues are welcome. Run checks and tests before submitting:
```sh
bun run devcheck
bun run test
```
---
## License
Apache-2.0 — see [LICENSE](LICENSE) for details.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessResponsive