@cyanheads/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">

</div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: 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; intermediate values returned for tracing
• Optional step-by-step decode explanation (explain, default true): how a WAF or server would reverse each layer
• Bypass rationale: why the encoding combination might evade common filter patterns
• detection_note included in every response — how defenders detect encoded payload variants — preserving the dual-audience framing
• No live probing — mathematically deterministic transforms only

---

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — one file per tool, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

Pentest-specific:

• Fully offline at runtime — no external API calls, no credentials required. All data loaded at startup from embedded modules; zero I/O during request handling
• MITRE ATT&CK Enterprise embedded at build time via scripts/refresh-attack.ts; in-memory indexed by ID and keyword at startup. Fast-fails with a clear message if the data file is missing
• OWASP Testing Guide methodology curated as structured TypeScript modules covering reconnaissance through post-exploitation phases
• Payload template library curated and annotated TypeScript modules, one file per vulnerability category, adapted to injection context
• WAF bypass knowledge keyed by WAF product and attack vector, referencing public research
• Encoding chain engine — pure TypeScript transforms with full decode-path tracing
• 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 across all MCP clients regardless of which surface (structured or text) the client forwards
• detection_note and mitigation fields required on every technique, finding, and payload — never optional — so defenders always receive usable context alongside offense technique
• Transparent relevance scoring in pentest_map_techniques — documented criteria, no opaque composite scores
• nextToolSuggestions pre-filled with arguments from the current methodology context — reduces agent planning overhead
• ATT&CK dataset version string on every technique result — callers can reason about data vintage

---

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:

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:

{
  "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.

{
  "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):

{
  "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:

{
  "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:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 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:

git clone https://github.com/cyanheads/pentest-mcp-server.git

2. Navigate into the directory:

cd pentest-mcp-server

3. Install dependencies:

bun install

4. Seed the ATT&CK data:

bun run scripts/refresh-attack.ts

5. Configure environment:

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 for the full list of optional overrides.

---

Running the server

Local development

• Build and run:

  # 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:

  bun run devcheck   # Lint, format, typecheck, security audit
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions
  

Docker

# 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 for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools via the barrel in src/mcp-server/tools/definitions/index.ts
• 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 and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

---

License

Apache-2.0 — see LICENSE for details.