@cyanheads/pentest-mcp-server 0.1.7 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/AGENTS.md +14 -8
  2. package/CLAUDE.md +14 -8
  3. package/Dockerfile +5 -1
  4. package/README.md +69 -88
  5. package/changelog/0.1.x/0.1.6.md +0 -2
  6. package/changelog/0.1.x/0.1.8.md +11 -0
  7. package/changelog/0.1.x/0.1.9.md +27 -0
  8. package/changelog/template.md +9 -26
  9. package/dist/index.js +3 -0
  10. package/dist/index.js.map +1 -1
  11. package/package.json +21 -11
  12. package/server.json +3 -3
package/AGENTS.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** pentest-mcp-server
4
- **Version:** 0.1.7
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
- **Engines:** Bun ≥1.3.0, Node ≥24.0.0
4
+ **Version:** 0.1.9
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
6
+ **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` / `@modelcontextprotocol/client` ^2.0.0 (via framework)
8
- **Zod:** ^4.4.3
8
+ **Zod:** ^4.6.5
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
11
11
 
@@ -213,9 +213,9 @@ scripts/
213
213
 
214
214
  ## Skills
215
215
 
216
- Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
216
+ Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool.
217
217
 
218
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
218
+ **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
219
219
 
220
220
  Available skills:
221
221
 
@@ -253,7 +253,7 @@ Available skills:
253
253
  | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
254
254
  | `api-workers` | Cloudflare Workers runtime |
255
255
 
256
- **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
256
+ **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
257
257
 
258
258
  When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
259
259
 
@@ -292,7 +292,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
292
292
 
293
293
  **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
294
294
 
295
- **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
295
+ **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
296
296
 
297
297
  ---
298
298
 
@@ -323,6 +323,12 @@ security: false # optional — true flags security fi
323
323
 
324
324
  ---
325
325
 
326
+ ## Publishing
327
+
328
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
329
+
330
+ ---
331
+
326
332
  ## Imports
327
333
 
328
334
  ```ts
package/CLAUDE.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** pentest-mcp-server
4
- **Version:** 0.1.7
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.3`
6
- **Engines:** Bun ≥1.3.0, Node ≥24.0.0
4
+ **Version:** 0.1.9
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
6
+ **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` / `@modelcontextprotocol/client` ^2.0.0 (via framework)
8
- **Zod:** ^4.4.3
8
+ **Zod:** ^4.6.5
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
11
11
 
@@ -213,9 +213,9 @@ scripts/
213
213
 
214
214
  ## Skills
215
215
 
216
- Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
216
+ Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool.
217
217
 
218
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
218
+ **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
219
219
 
220
220
  Available skills:
221
221
 
@@ -253,7 +253,7 @@ Available skills:
253
253
  | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
254
254
  | `api-workers` | Cloudflare Workers runtime |
255
255
 
256
- **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
256
+ **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
257
257
 
258
258
  When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
259
259
 
@@ -292,7 +292,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
292
292
 
293
293
  **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
294
294
 
295
- **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
295
+ **README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
296
296
 
297
297
  ---
298
298
 
@@ -323,6 +323,12 @@ security: false # optional — true flags security fi
323
323
 
324
324
  ---
325
325
 
326
+ ## Publishing
327
+
328
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
329
+
330
+ ---
331
+
326
332
  ## Imports
327
333
 
328
334
  ```ts
package/Dockerfile CHANGED
@@ -4,7 +4,11 @@
4
4
  # This stage installs all dependencies (including dev), builds the TypeScript
5
5
  # source code into JavaScript, and prepares the production assets.
6
6
  # ==============================================================================
7
- FROM oven/bun:1.4.0 AS build
7
+ # TypeScript compilation and data preparation are architecture-neutral. Running
8
+ # them on the native build platform avoids invoking Bun through QEMU during a
9
+ # cross-platform build; the production stage still targets each requested image
10
+ # architecture.
11
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
8
12
 
9
13
  WORKDIR /usr/src/app
10
14
 
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-0.1.7-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/)
10
+ [![Version](https://img.shields.io/badge/Version-0.1.9-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.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -33,134 +33,115 @@
33
33
 
34
34
  ---
35
35
 
36
- ## Tools
36
+ ## Overview
37
37
 
38
- Seven tools spanning the full authorized-testing workflow — from initial scoping through response analysis and payload generation:
38
+ 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.
39
+
40
+ ### Tools
39
41
 
40
42
  | Tool | Description |
41
43
  |:-----|:------------|
42
- | `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. |
43
- | `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. |
44
- | `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. |
45
- | `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. |
46
- | `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. |
47
- | `pentest_generate_payloads` | Generates annotated payload templates for authorized testing. Each template includes why it works in the injection context, detection signatures, and mitigations. |
48
- | `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. |
44
+ | `pentest_guide` | Step-by-step authorized-testing methodology playbook for a chosen attack vector, phase-filterable, with detection and mitigation per technique. |
45
+ | `pentest_analyze_response` | Analyzes raw HTTP response headers/body from authorized probing for leakage, fingerprinting, and misconfiguration. |
46
+ | `pentest_lookup_technique` | Looks up a MITRE ATT&CK technique by ID or keyword, with detection data, mitigations, and procedure examples. |
47
+ | `pentest_lookup_group` | Looks up a MITRE ATT&CK threat group or software entry by ID or name, with aliases and technique usage. |
48
+ | `pentest_map_techniques` | Ranks ATT&CK techniques and OWASP test cases against a target profile (stack, services, auth type, OS). |
49
+ | `pentest_generate_payloads` | Generates annotated payload templates for a vulnerability category and injection context, with optional WAF bypass variants and encoding. |
50
+ | `pentest_encode` | Applies an ordered encoding chain to a payload string with decode-path tracing. |
49
51
 
50
- ### `pentest_guide`
52
+ ## Capability reference
51
53
 
52
- Instruction tool. Returns a structured attack methodology playbook for the given vector and optional target context.
54
+ ### `pentest_guide` <sub>tool</sub>
53
55
 
54
- - 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`
56
+ - 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`
55
57
  - Optional `target_context` (`stack`, `waf`, `recon_notes`) narrows the playbook to stack-specific techniques and WAF-bypass-aware variants
56
- - Phase filtering: `all`, `recon`, `enumeration`, `exploitation`, `post_exploitation`
57
- - Every technique entry includes detection indicators and recommended mitigations — usable as a blue team planning aid
58
- - `nextToolSuggestions` pre-filled with payload generator and ATT&CK lookup calls from the methodology context
59
- - `authorized_use_reminder` field rendered as the first line of every response so the framing reaches all clients
60
- - OWASP Testing Guide test case IDs and ATT&CK technique IDs included for cross-referencing
58
+ - `phase` filter: `all` (default), `recon`, `enumeration`, `exploitation`, or `post_exploitation`
59
+ - Every technique carries `detection` and `mitigation`; response also includes `owasp_references` (WSTG IDs) and `attack_technique_ids` for cross-referencing
60
+ - `authorized_use_reminder` rendered as the first line of every response
61
+ - `nextToolSuggestions` pre-filled with payload-generator and ATT&CK-lookup calls derived from the methodology context
61
62
 
62
63
  ---
63
64
 
64
- ### `pentest_analyze_response`
65
-
66
- Bridge tool. Paste raw HTTP output from authorized probing; get structured findings.
65
+ ### `pentest_analyze_response` <sub>tool</sub>
67
66
 
68
- - Accepts `response_headers` (raw HTTP headers), `response_body` (up to 10,000 chars), `status_code`, and freeform `context`
69
- - Detects: version disclosure, stack traces, internal paths, debug headers, technology fingerprints, auth patterns, CORS misconfigurations, missing security headers, interesting fields, error messages
70
- - Each finding carries: category, severity (`info`/`low`/`medium`/`high`), what was detected, why it matters, how a defender would detect exploitation, and remediation
71
- - Technology fingerprinting summary (`server_software`, `framework`, `language`, `database`, `cloud_provider`) ready for use as `target_context` in `pentest_guide` or `pentest_map_techniques`
72
- - `nextToolSuggestions` pre-filled from fingerprints and findings
67
+ - 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
68
+ - 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`)
69
+ - Each finding carries `detection` and `remediation`; results are ordered by severity descending
70
+ - `fingerprints` block (`server_software`, `framework`, `language`, `database`, `cloud_provider`, `other`) ready for use as target context in `pentest_guide` or `pentest_map_techniques`
71
+ - Typed `no_input` error when neither `response_headers` nor `response_body` is supplied
72
+ - `nextToolSuggestions` pre-filled from detected fingerprints and findings
73
73
 
74
74
  ---
75
75
 
76
- ### `pentest_lookup_technique`
76
+ ### `pentest_lookup_technique` <sub>tool</sub>
77
77
 
78
- Single-record ATT&CK lookup. Accepts exact IDs (`T1190`, `T1059.001`) or keyword search.
79
-
80
- - Full technique record: name, tactics, description, target platforms
81
- - Detection context: summary, ATT&CK data sources (log sources, sensors), concrete behavioral indicators
82
- - Mitigations: ATT&CK mitigation IDs, names, and descriptions
83
- - Real-world procedure examples from public threat intelligence reporting
84
- - Sub-technique inclusion toggle (`include_subtechniques`, default `true`)
85
- - ATT&CK dataset version string in every response so callers know the data vintage
78
+ - Accepts an exact ATT&CK ID (`T1190`, `T1059.001`) or a keyword; ID lookup is exact, keyword falls back to best-match search
79
+ - Returns tactics, platforms, description, detection (`summary`, `data_sources`, `indicators`), mitigations, and procedure examples from public ATT&CK reporting
80
+ - `include_subtechniques` (default `true`) toggles sub-technique inclusion
81
+ - `attack_version` echoes the embedded ATT&CK dataset version (e.g. "Enterprise v19.1") on every response
82
+ - Typed `no_match` error when the ID or keyword resolves to nothing
86
83
 
87
84
  ---
88
85
 
89
- ### `pentest_lookup_group`
90
-
91
- ATT&CK threat group and software lookup. Accepts exact IDs (`G0007`, `S0002`) or name/keyword search (`APT28`, `Mimikatz`).
86
+ ### `pentest_lookup_group` <sub>tool</sub>
92
87
 
93
- - Covers both intrusion sets (threat groups, G-prefix) and software entries (malware and tools, S-prefix)
94
- - Returns: name, type (`group` or `software`), aliases, description, and up to 20 techniques used with procedure-level context
95
- - Technique entries link directly to `pentest_lookup_technique` for full detection and mitigation context
96
- - Equally useful for defenders building detection coverage around specific adversary tradecraft
88
+ - Accepts an exact ATT&CK group ID (`G0007`) or software ID (`S0002`), or a name/keyword (`APT28`, `Mimikatz`)
89
+ - `type` discriminates `group` (intrusion set) from `software` (malware/tool); `aliases` lists known alternate names
90
+ - `techniques_used` returns up to 20 techniques with procedure-level context, each linking to `pentest_lookup_technique` by `technique_id`
91
+ - `description` truncated to 800 characters
92
+ - Typed `no_match` error when the ID or name resolves to nothing
97
93
 
98
94
  ---
99
95
 
100
- ### `pentest_map_techniques`
96
+ ### `pentest_map_techniques` <sub>tool</sub>
101
97
 
102
- Discovery and ranking tool. Takes a target profile, returns prioritized testing scope.
103
-
104
- - 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)
105
- - 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
106
- - Each ranked technique includes: relevance rationale, detection opportunity, mitigation summary, and the `pentest_guide` vector for follow-up
107
- - OWASP test cases mapped to the profile alongside ATT&CK techniques
108
- - Configurable result count (1–50, default 15)
98
+ - 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
99
+ - Relevance scoring adds points for platform, stack, service, and auth-type matches; each result's `relevance_rationale` lists exactly which criteria matched
100
+ - `limit` caps `ranked_techniques` at 1–50 (default 15); enrichment (`truncated`, `shown`, `cap`) discloses when results were capped
101
+ - Each ranked technique carries `detection_opportunity`, `mitigation_summary`, and an optional `pentest_guide_vector` for follow-up
102
+ - `owasp_test_cases` returns up to 10 relevant OWASP Testing Guide test cases
103
+ - Typed `no_profile` error when no profile field is supplied
109
104
 
110
105
  ---
111
106
 
112
- ### `pentest_generate_payloads`
113
-
114
- Context-aware payload template generator for authorized testing. Returns annotated templates — not live weaponized strings.
107
+ ### `pentest_generate_payloads` <sub>tool</sub>
115
108
 
116
- - Fourteen payload categories: `xss`, `sqli`, `ssrf`, `xxe`, `path_traversal`, `ssti`, `command_injection`, `open_redirect`, `csrf`, `deserialization`, `jwt`, `ldap_injection`, `nosql_injection`, `http_header`
117
- - 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`
118
- - 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
119
- - Optional encoding chain applied at generation time; up to 20 variants per request
120
- - Each template annotated with: vulnerability class, detection signature, mitigation, and WAF bypass notes
121
- - `authorized_use_reminder` rendered as the first line of every response
109
+ - 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`)
110
+ - `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
111
+ - Optional `encoding` chain applied to each returned template; `count` caps results at 1–20 (default 5)
112
+ - Each payload carries `detection_signature` and `mitigation`; `waf_bypass_note` present only when `waf_profile` isn't `none`
113
+ - Templates are annotated placeholders, not live weaponized strings — `authorized_use_reminder` rendered first in every response
122
114
 
123
115
  ---
124
116
 
125
- ### `pentest_encode`
117
+ ### `pentest_encode` <sub>tool</sub>
126
118
 
127
- Pure transformation utility. Applies an ordered encoding chain to a payload string.
128
-
129
- - Ten encoding types: `url`, `double_url`, `html_entity`, `unicode`, `hex`, `base64`, `js_escape`, `null_byte`, `mixed_case`, `comment_break`
130
- - Chains up to 6 steps applied left-to-right; intermediate values returned for tracing
131
- - Optional step-by-step decode explanation (`explain`, default `true`): how a WAF or server would reverse each layer
132
- - Bypass rationale: why the encoding combination might evade common filter patterns
133
- - `detection_note` included in every response — how defenders detect encoded payload variants — preserving the dual-audience framing
134
- - No live probing — mathematically deterministic transforms only
119
+ - `payload` string up to 10,000 characters; `chain` is an ordered list of 1–6 encoding steps applied left to right
120
+ - 10 encoding types: `url`, `double_url`, `html_entity`, `unicode`, `hex`, `base64`, `js_escape`, `null_byte`, `mixed_case`, `comment_break`
121
+ - `intermediate_steps` traces the value after each chain step; `explain` (default `true`) adds `decode_path` and `bypass_rationale`
122
+ - `detection_note` on every response — how defenders detect encoded variants
123
+ - Pure deterministic transforms, no live probing; typed `encoding_error` when a step produces invalid output
135
124
 
136
125
  ---
137
126
 
138
127
  ## Features
139
128
 
140
- Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
141
-
142
- - Declarative tool definitions — one file per tool, framework handles registration and validation
143
- - Unified error handling — handlers throw, framework catches, classifies, and formats
144
- - Structured logging with optional OpenTelemetry tracing
145
- - STDIO and Streamable HTTP transports
129
+ 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.
146
130
 
147
- Pentest-specific:
131
+ Methodology-specific:
148
132
 
149
- - **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
150
- - **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
151
- - **OWASP Testing Guide methodology** curated as structured TypeScript modules covering reconnaissance through post-exploitation phases
152
- - **Payload template library** curated and annotated TypeScript modules, one file per vulnerability category, adapted to injection context
153
- - **WAF bypass knowledge** keyed by WAF product and attack vector, referencing public research
154
- - **Encoding chain engine** — pure TypeScript transforms with full decode-path tracing
133
+ - Fully offline at runtime — no external API calls, no credentials required; all data loaded at startup, zero I/O during request handling
134
+ - 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
135
+ - OWASP Testing Guide methodology and payload template library curated as structured TypeScript modules, one per vector/category
136
+ - WAF bypass variants keyed by WAF product and attack vector, referencing public research
155
137
  - All tools annotated `readOnlyHint: true`, `openWorldHint: false` — deterministic output from a bounded embedded dataset
156
138
 
157
139
  Agent-friendly output:
158
140
 
159
- - `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
160
- - `detection_note` and `mitigation` fields required on every technique, finding, and payload — never optional — so defenders always receive usable context alongside offense technique
161
- - Transparent relevance scoring in `pentest_map_techniques` — documented criteria, no opaque composite scores
162
- - `nextToolSuggestions` pre-filled with arguments from the current methodology context — reduces agent planning overhead
163
- - ATT&CK dataset version string on every technique result — callers can reason about data vintage
141
+ - `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
142
+ - `detection` and `mitigation` fields required (non-optional) on every technique, finding, and payload — defenders always get usable context alongside offense technique
143
+ - `attack_version` echoed on every ATT&CK-backed response so callers can reason about data vintage
144
+ - `nextToolSuggestions` pre-filled with arguments derived from the current context, reducing agent planning overhead
164
145
 
165
146
  ---
166
147
 
@@ -264,7 +245,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
264
245
 
265
246
  ### Prerequisites
266
247
 
267
- - [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
248
+ - [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
268
249
  - ATT&CK data seeded — run `bun run scripts/refresh-attack.ts` once after cloning (Docker builds handle this automatically).
269
250
 
270
251
  ### Installation
@@ -396,7 +377,7 @@ See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rule
396
377
 
397
378
  ## Contributing
398
379
 
399
- Issues and pull requests are welcome. Run checks and tests before submitting:
380
+ Issues are welcome. Run checks and tests before submitting:
400
381
 
401
382
  ```sh
402
383
  bun run devcheck
package/changelog/0.1.x/0.1.6.md CHANGED
@@ -22,5 +22,3 @@ security: false
22
22
 
23
23
  - `@types/node` `^25.9.3 → ^26.0.0`
24
24
  - `vitest` `^4.1.8 → ^4.1.9`
25
- </content>
26
- </invoke>
package/changelog/0.1.x/0.1.8.md ADDED
@@ -0,0 +1,11 @@
1
+ ---
2
+ summary: "Run architecture-neutral Docker build work on the native builder for reliable multi-architecture images"
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.8 — 2026-08-21
8
+
9
+ ## Fixed
10
+
11
+ - **Multi-architecture Docker builds** — TypeScript compilation and ATT&CK data preparation now run on `BUILDPLATFORM`, avoiding Bun execution through QEMU while preserving target-specific runtime images.
package/changelog/0.1.x/0.1.9.md ADDED
@@ -0,0 +1,27 @@
1
+ ---
2
+ summary: "Adopt mcp-ts-core 0.13.6, declare an explicit stateless session mode, and migrate the skill tree to framework-skills/"
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.1.9 — 2026-09-20
8
+
9
+ ## Changed
10
+
11
+ - **Stateless session mode declared in code** (#12) — `createApp({ sessionMode: 'stateless' })` states the server's posture at the source. This server holds no per-session state and calls `ctx.requestInput` nowhere, so it declares `stateless` in code; an operator who sets `MCP_SESSION_MODE` explicitly still overrides that declaration.
12
+ - **`.env.example` session block** (#12) — now ships the active, uncommented `MCP_SESSION_MODE=stateless` line, replacing a commented `MCP_SESSION_MODE=stateful` whose note omitted the schema's actual `auto` default. The Docker image's `ENV MCP_SESSION_MODE="stateless"` is unchanged and now matches the documented default rather than overriding it.
13
+ - **Skill tree moved `skills/` → `framework-skills/`** — a plugin-shipping server no longer hands its development skills to every installing agent (mcp-ts-core 0.13.0).
14
+ - **Bun engines floor `>=1.4.0`** — `package.json` `engines.bun` raised to match the Docker images, which already pin Bun 1.4.0 (mcp-ts-core 0.12.9).
15
+ - **Build scripts** — `build`/`rebuild` pass `--project tsconfig.build.json` explicitly (mcp-ts-core#440); `package.json` gained a `funding` field.
16
+ - **Documentation** — README leads with an Overview and a per-tool capability reference; Bun badge updated to v1.4.0.
17
+ - **Repository metadata** — `manifest.json` `author.name` corrected to `cyanheads` to match the plugin manifests; `.claude-plugin/plugin.json` gained its schema reference and keywords; added the CodeQL workflow and refreshed the issue templates and contribution guide.
18
+
19
+ ## Dependencies
20
+
21
+ - `@cyanheads/mcp-ts-core` `^0.12.3` → `^0.13.6`
22
+ - `zod` `^4.4.3` → `^4.6.5`
23
+ - `@biomejs/biome` `^2.5.9` → `^2.5.14` (dev)
24
+ - `@types/node` `^26.2.0` → `^26.6.1` (dev)
25
+ - `ignore` `^7.0.6` → `^7.0.9` (dev)
26
+ - `tsc-alias` `^1.9.2` → `^1.9.5` (dev)
27
+ - `vitest` `^4.1.11` → `^5.0.1` (dev, major)
package/changelog/template.md CHANGED
@@ -6,8 +6,8 @@
6
6
 
7
7
  # Required. One-line GitHub Release-style headline. 350 character cap — a
8
8
  # ceiling, not a target. Default short and scannable. Don't pad, don't stitch
9
- # unrelated changes with commas/semicolons into an inventory — pick the
10
- # headline, like a tag's theme line. Quotes required: unquoted YAML treats
9
+ # unrelated changes with commas/semicolons into an inventory — pick the one
10
+ # headline the release is about. Quotes required: unquoted YAML treats
11
11
  # `: ` inside the value as a key separator and fails GitHub's strict parser.
12
12
  summary: ""
13
13
 
@@ -117,30 +117,13 @@ security: false
117
117
  in that unrelated item's metadata.
118
118
 
119
119
  TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
120
- via `gh release create --notes-from-tag`. The tag is a derivative of this
121
- changelog entry — a condensed, scannable version, not a copy. Format:
122
-
123
- <theme — omit version number, GitHub prepends it>
124
- ← blank line
125
- <1-2 sentence context: what this release does>
126
- ← blank line
127
- Dependency bumps: ← section header
128
- ← blank line
129
- - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6 ← bullet
130
- ← blank line
131
- Changed: ← only sections with entries
132
- ← blank line
133
- - `format()` output includes `query` in text mode
134
- ← blank line
135
- Added:
136
- ← blank line
137
- - `manifest.json` scaffolded for MCPB bundle support
138
- - Install badges (Claude Desktop, Cursor, VS Code)
139
- ← blank line
140
- <N> tests pass; `bun run devcheck` clean. ← footer
141
-
142
- Never a flat comma-separated string. Always structured markdown with
143
- sections. The tag must scan well as a rendered GitHub Release page.
120
+ via `gh release create --notes-from-tag`. It is a condensed digest of this
121
+ entry, never a copy, and its format is owned by the `release-and-publish`
122
+ skill (step 4, "Create the annotated tag"): a short subject line without the
123
+ version, flat headline bullets — no Keep-a-Changelog section headers, no
124
+ gates line — at most one deps line, issue backlinks, and the changelog link
125
+ last. In release-PR mode the `git-wrapup` skill authors those bullets as the
126
+ PR body's `## Changes` and the tag copies them.
144
127
  -->
145
128
 
146
129
  ## Added
package/dist/index.js CHANGED
@@ -20,6 +20,9 @@ await createApp({
20
20
  'Every technique is paired with detection and mitigation context — equally useful for defenders. ' +
21
21
  'All tools are read-only and deterministic. No external API calls at runtime. ' +
22
22
  'AUTHORIZED USE ONLY: all output is scoped to systems the tester owns or has explicit written authorization to test.',
23
+ // Every tool reads embedded data and no handler calls ctx.requestInput, so there is
24
+ // no per-session state to keep. MCP_SESSION_MODE still overrides when it is set.
25
+ sessionMode: 'stateless',
23
26
  setup() {
24
27
  initAttackService();
25
28
  initMethodologyService();
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,2DAA2D,CAAC;AAExG,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,oBAAoB;IAC3B,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,YAAY,EACV,uGAAuG;QACvG,kGAAkG;QAClG,+EAA+E;QAC/E,qHAAqH;IACvH,KAAK;QACH,iBAAiB,EAAE,CAAC;QACpB,sBAAsB,EAAE,CAAC;QACzB,kBAAkB,EAAE,CAAC;QACrB,mBAAmB,EAAE,CAAC;QACtB,2BAA2B,EAAE,CAAC;IAChC,CAAC;CACF,CAAC,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,2DAA2D,CAAC;AAExG,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,oBAAoB;IAC3B,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,YAAY,EACV,uGAAuG;QACvG,kGAAkG;QAClG,+EAA+E;QAC/E,qHAAqH;IACvH,oFAAoF;IACpF,iFAAiF;IACjF,WAAW,EAAE,WAAW;IACxB,KAAK;QACH,iBAAiB,EAAE,CAAC;QACpB,sBAAsB,EAAE,CAAC;QACzB,kBAAkB,EAAE,CAAC;QACrB,mBAAmB,EAAE,CAAC;QACtB,2BAA2B,EAAE,CAAC;IAChC,CAAC;CACF,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cyanheads/pentest-mcp-server",
3
- "version": "0.1.7",
3
+ "version": "0.1.9",
4
4
  "description": "Offline methodology engine and payload workshop for authorized penetration testing, CTF, security research, and education via MCP. STDIO or Streamable HTTP.",
5
5
  "mcpName": "io.github.cyanheads/pentest-mcp-server",
6
6
  "type": "module",
@@ -20,8 +20,8 @@
20
20
  "server.json"
21
21
  ],
22
22
  "scripts": {
23
- "build": "bun run scripts/build.ts",
24
- "rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
23
+ "build": "bun run scripts/build.ts --project tsconfig.build.json",
24
+ "rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts --project tsconfig.build.json",
25
25
  "clean": "bun run scripts/clean.ts",
26
26
  "devcheck": "bun run scripts/devcheck.ts",
27
27
  "audit:refresh": "rm -f bun.lock && bun install && bun audit",
@@ -73,27 +73,37 @@
73
73
  "url": "https://github.com/cyanheads/pentest-mcp-server/issues"
74
74
  },
75
75
  "license": "Apache-2.0",
76
+ "funding": [
77
+ {
78
+ "type": "github",
79
+ "url": "https://github.com/sponsors/cyanheads"
80
+ },
81
+ {
82
+ "type": "buy_me_a_coffee",
83
+ "url": "https://www.buymeacoffee.com/cyanheads"
84
+ }
85
+ ],
76
86
  "packageManager": "bun@1.4.0",
77
87
  "engines": {
78
- "bun": ">=1.3.0",
88
+ "bun": ">=1.4.0",
79
89
  "node": ">=24.0.0"
80
90
  },
81
91
  "publishConfig": {
82
92
  "access": "public"
83
93
  },
84
94
  "dependencies": {
85
- "@cyanheads/mcp-ts-core": "^0.12.3",
95
+ "@cyanheads/mcp-ts-core": "^0.13.6",
86
96
  "pino-pretty": "^13.1.3",
87
- "zod": "^4.4.3"
97
+ "zod": "^4.6.5"
88
98
  },
89
99
  "devDependencies": {
90
- "@biomejs/biome": "^2.5.9",
100
+ "@biomejs/biome": "^2.5.14",
91
101
  "@socketsecurity/bun-security-scanner": "^1.1.2",
92
- "@types/node": "^26.2.0",
102
+ "@types/node": "^26.6.1",
93
103
  "depcheck": "^1.4.7",
94
- "ignore": "^7.0.6",
95
- "tsc-alias": "^1.9.2",
104
+ "ignore": "^7.0.9",
105
+ "tsc-alias": "^1.9.5",
96
106
  "typescript": "^7.0.2",
97
- "vitest": "^4.1.11"
107
+ "vitest": "^5.0.1"
98
108
  }
99
109
  }
package/server.json CHANGED
@@ -6,7 +6,7 @@
6
6
  "url": "https://github.com/cyanheads/pentest-mcp-server",
7
7
  "source": "github"
8
8
  },
9
- "version": "0.1.7",
9
+ "version": "0.1.9",
10
10
  "remotes": [
11
11
  {
12
12
  "type": "streamable-http",
@@ -19,7 +19,7 @@
19
19
  "registryBaseUrl": "https://registry.npmjs.org",
20
20
  "identifier": "@cyanheads/pentest-mcp-server",
21
21
  "runtimeHint": "bun",
22
- "version": "0.1.7",
22
+ "version": "0.1.9",
23
23
  "packageArguments": [
24
24
  {
25
25
  "type": "positional",
@@ -48,7 +48,7 @@
48
48
  "registryBaseUrl": "https://registry.npmjs.org",
49
49
  "identifier": "@cyanheads/pentest-mcp-server",
50
50
  "runtimeHint": "bun",
51
- "version": "0.1.7",
51
+ "version": "0.1.9",
52
52
  "packageArguments": [
53
53
  {
54
54
  "type": "positional",