pentest-mcp-server

---

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

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.

Tools

Tool	Description
pentest_get_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_payload	Applies an ordered encoding chain to a payload string with decode-path tracing.

Capability reference

pentest_get_guide _tool

• vector: 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_exploitation
• Playbook techniques carry detection and mitigation, with owasp_references, attack_technique_ids, and context-derived nextToolSuggestions
• Optional target_context (stack, waf, recon_notes) narrows the playbook

---

pentest_analyze_response _tool

• Supply response_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_input
• Findings carry category, severity (info/low/medium/high), detection, and remediation, ordered by severity descending
• fingerprints (server_software, framework, language, database, cloud_provider, other) and nextToolSuggestions support follow-up calls

---

pentest_lookup_technique _tool

• Supply an ATT&CK ID (T1190, T1059.001) or keyword; include_subtechniques defaults to true
• Returns tactics, platforms, description, detection (summary, data_sources, indicators), mitigations, procedure examples, and attack_version
• Returns no_match when the ID or keyword resolves to nothing

---

pentest_lookup_group _tool

• Supply an ATT&CK group ID (G0007), software ID (S0002), or name/keyword; returns no_match when nothing resolves
• type distinguishes group from software; results include aliases, description (≤800 characters), and attack_version
• techniques_used returns up to 20 techniques with procedure context and technique_id for pentest_lookup_technique

---

pentest_map_techniques _tool

• Supply at least one of stack, services, auth_type (jwt/session_cookie/api_key/oauth2/basic_auth/ntlm/kerberos/none/unknown), or os (linux/windows/macos/unknown); otherwise returns no_profile
• ranked_techniques carries relevance_score, relevance_rationale, detection_opportunity, mitigation_summary, and optional pentest_guide_vector; owasp_test_cases returns up to 10 cases
• limit caps techniques at 1–50 (default 15); enrichment (truncated, shown, cap) discloses the cap

---

pentest_generate_payloads _tool

• category: 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 generic
• count caps templates at 1–20 (default 5); each carries detection_signature and mitigation, with optional encoding applied to every template
• waf_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_note

---

pentest_encode_payload _tool

• payload 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_break
• Returns intermediate_steps and detection_note; explain (default true) adds decode_path and bypass_rationale
• Returns encoding_error when a transform fails

---

Features

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

• 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
• Techniques and payloads require detection and mitigation context; response findings require detection and remediation
• 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:

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.4.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
PENTEST_ENABLE_PAYLOAD_GENERATION	Enable pentest_generate_payloads and pentest_encode_payload; when false they are hidden from clients.	true
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
OTEL_ENABLED	Enable OpenTelemetry instrumentation (spans, metrics, completion logs).	false
LOG_TOOL_FAILURE_PAYLOADS	Log failed-call arguments and results (key names redacted; free-form values can still contain secrets).	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP log export destination.	—

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.

---

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_get_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.
scripts/copy-attack.ts	Copies the seeded ATT&CK dataset into dist/ after compilation.
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 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()
• Keep detection and mitigation context required on techniques and payloads, and detection and remediation required on response findings

---

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

---

License

Apache-2.0 — see LICENSE for details.