## 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_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 - 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 **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](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:** 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). | `/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:** # 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`](./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 ## License Apache-2.0 — see [LICENSE](LICENSE) for details.

标签：自动化攻击