Skip to content
Back to search

pentest-mcp

NOT for educational purposes: An MCP server for professional penetration testers including STDIO/HTTP/SSE support, nmap, go/dirbuster, nikto, JtR, hashcat, wordlist building, and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dmontgomery40--pentest-mcp/badge.svg)](/listings/dmontgomery40--pentest-mcp)

HTML

<a href="/listings/dmontgomery40--pentest-mcp"><img src="/api/listings/dmontgomery40--pentest-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

npm install -g pentest-mcp

Run locally (stdio)

pentest-mcp

Launch bundled MCP Inspector (no separate install)

pentest-mcp inspector

You can forward Inspector flags directly:

pentest-mcp inspector --help

Run over network (Streamable HTTP)

MCP_TRANSPORT=http MCP_SERVER_HOST=0.0.0.0 MCP_SERVER_PORT=8000 pentest-mcp

Run legacy SSE mode (deprecated)

MCP_TRANSPORT=sse MCP_SERVER_PORT=8001 pentest-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 344 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Pentest MCP
  2. [![smithery badge](https://smithery.ai/badge/@DMontgomery40/pentest-mcp)](https://smithery.ai/server/@DMontgomery40/pentest-mcp)
  3. [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/fa558a10-f45c-4668-9bb6-15630dd51f27)
  4. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/dmontgomery40-pentest-mcp-badge.png)](https://mseep.ai/app/dmontgomery40-pentest-mcp)
  5. Pentest MCP is a TypeScript MCP server for authorized security assessments. It gives a human researcher or a tool-using assessment agent one scoped interface for discovery, validation, capture, credential checks, local audit, evidence retrieval, and report preparation. Each active tool call is tied to an engagement and a durable record. The server checks the declared targets and time window; the researcher verifies findings before publication.
  6. ## October 2026 workflow
  7. 1. Create an engagement from signed authorization and rules of engagement, then save the assessment plan. The operator chooses a stable `engagementId`.
  8. 2. A researcher or fresh Codex process in the managed assessment container connects to the Pentest MCP server. It sees the complete catalog, while the plan's exact `allowedToolNames` list permits only selected calls. Active tools also pass the engagement target and time gate.
  9. 3. Review `recordId` values and correlated scope decisions with `listEngagementRecords` and `getEngagementRecord`. Records persist across restarts. Import external research with `recordResearchActivity`; the import does not replace MCP tool use.
  10. 4. Draft a report from the complete evidence ledger, inspect candidate findings against source records, and publish only analyst-verified findings. Retrieve Markdown or JSON later with `getClientReport`.
  11. The declared-target check is an operational guardrail, not a complete network boundary. DNS changes, redirects, Nmap scripts, Nuclei templates, and other third-party tool behavior can create secondary traffic. Review tool configuration and keep network controls aligned with the engagement's rules.
  12. ### Agentic assessment uses the MCP tools
  13. The assessment stage is a **tool-using agent session**. `runAgentAssessment` supports local Codex or Claude in a dedicated account profile, Codex in a pinned container, a loopback OpenAI-compatible server such as llama.cpp or Ollama, and OpenRouter. CLI workers receive a locked, single-engagement Pentest MCP server and discover the full catalog. Guarded API models receive only the exact plan allowlist intersected with the worker catalog. Every requested action still reaches the same worker-side plan, target, parent-status, and time checks before a handler starts. Optional `hostileModelProtection` adds duplicate-action, token-accounting, and finish-reason circuit breakers and defaults to false. An interrupted run with a durable start receipt and no terminal receipt blocks replay; `reconcileAgentAssessment` requires an operator to confirm that the prior process stopped, records reviewer and rationale, and revokes the prior worker scope when it is still available. The returned `toolCounts`, `importedRecordIds`, and `importMapRecordId` identify recorded actions and imported evidence. A run with no successful assessment-tool call fails.
  14. `draftAssessmentReport` is a later, context-quarantined report-writing step; a draft alone does not show that Pentest MCP helped the assessment. OpenAI, Anthropic, OpenRouter, OpenAI-compatible, local Codex, local Claude, container Codex, and configured SSH profiles can draft from a bounded evidence packet without scanner tools. `local-agent` accepts self-hosted CLI profiles and loopback OpenAI-compatible profiles while rejecting hosted providers before context is sent. The [guarded model guide](docs/guarded-models.md) gives llama.cpp and OpenRouter profiles, enforced stop conditions, audit fields, and hostile-model deployment boundaries. The [container assessment guide](docs/container-assessment.md) gives CLI profile fields, real acceptance command, and isolation limits. The [agentic workflow](docs/agentic-assessment-workflow.md) covers scope, evidence review, Daybreak/Glasswing access, and Faxbot planning.
  15. Release acceptance uses `scripts/run-real-acceptance.mjs`. It has no default target or authorization and refuses to pass unless installed Nmap and ProjectDiscovery HTTPX create successful evidence records. With `--profile`, the managed agent must invoke both through Pentest MCP. With `--report-profile`, a separate report context must produce the saved draft. Test doubles remain in automated tests only and are never shipped as acceptance receipts.
  16. ## Quick start
  17. Requires Node.js 22.19.0 or newer and the host binaries for the tools you intend to use. The Docker image includes the listed tools; native installations must provide them in `PATH`.
  18. ```bash
  19. npm install -g pentest-mcp
  20. pentest-mcp
  21. ```
  22. Stdio is the default for local MCP clients. `pentest-mcp inspector` starts the bundled MCP Inspector against this server over stdio; Inspector flags can be forwarded, for example `pentest-mcp inspector --help`.
  23. Set `PENTEST_DATA_DIR` to choose the local evidence directory. Otherwise the server uses `$XDG_DATA_HOME/pentest-mcp` when that variable is set, or `~/.pentest-mcp`. Evidence and report files are stored with private directory and file permissions. Treat raw outputs, hashes, captured traffic, and reports as client-sensitive data; control access, retention, and backups accordingly.
  24. ### Register an engagement
  25. Call `createEngagement` before scanning. Use dates, targets, and references from the actual signed authorization; the values below are illustrative.
  26. ```json
  27. {
  28. "tool": "createEngagement",
  29. "arguments": {
  30. "engagementId": "client-2026-10",
  31. "authorizationReference": "Signed SoW section 4, approved 2026-10-24",
  32. "notBefore": "2026-10-25T09:00:00-06:00",
  33. "expiresAt": "2026-10-26T18:00:00-06:00",
  34. "allowedTargets": ["app.example.com", "192.0.2.0/28"],
  35. "excludedTargets": ["192.0.2.7"],
  36. "testingWindows": [
  37. {
  38. "start": "2026-10-25T09:00:00-06:00",
  39. "end": "2026-10-25T17:00:00-06:00"
  40. }
  41. ]
  42. }
  43. }
  44. ```
  45. Allowed targets accept exact hosts, CIDRs, wildcard subdomains, and HTTP(S) URL prefixes. Exclusions take precedence. All timestamps need an explicit timezone. `getEngagement` and `listEngagements` inspect stored registrations. `closeEngagement` revokes later execution, aborts managed assessments running in the same server process, and causes a separate managed runner to stop when it observes the parent registry closure.
  46. ### Run and review
  47. Use the same `engagementId` for active tools. The default non-root container supports a TCP connect scan; SYN and OS detection need additional privileges that are not granted by default.
  48. ```json
  49. {
  50. "tool": "nmapScan",
  51. "arguments": {
  52. "engagementId": "client-2026-10",
  53. "target": "app.example.com",
  54. "scanTechnique": "Connect",
  55. "serviceVersionDetection": true
  56. }
  57. }
  58. ```
  59. A successful tool response includes a `recordId` for its stored evidence. Retrieve only the records you need:
  60. ```json
  61. {
  62. "tool": "listEngagementRecords",
  63. "arguments": {
  64. "engagementId": "client-2026-10",
  65. "limit": 50
  66. }
  67. }
  68. ```
  69. `listEngagementRecords` returns summaries and accepts `limit` and `offset` for paging through older records. `getEngagementRecord` takes both `engagementId` and `recordId` and returns stored evidence when permitted. Credential tools return counts and output digests. New unauthenticated Gobuster/Nikto records retain private scanner output and findings for owner-scoped reads; older scanner records remain redacted. Nmap XML and bounded ffuf/Nuclei machine output are retained alongside summaries. A record's `outcome` is `succeeded`, `failed`, or `cancelled`, with a start time and duration when tracked; subprocess failures create an audit record rather than a successful scan result. A preflight scope refusal starts no command. For authenticated HTTP, engagement and evidence access is scoped to the verified token owner; stdio data is local to the server installation.
  70. ### Give the agent a client-specific plan
  71. `saveAssessmentPlan` stores objectives, human-readable allowed and prohibited methods, exact `allowedToolNames`, data handling, stop conditions, report audience, work ownership, and model data policy as a versioned evidence record. `getAssessmentPlan` reads the latest version. The managed worker receives the full catalog but the server rejects any call omitted from `allowedToolNames` before its handler runs, leaving a failed audit receipt. When a plan exists, its allowlist also gates direct manual MCP calls to the 14 assessment methods; denials are audited before the handler or command runs. Direct calls on legacy engagements without a plan keep their previous behavior and still pass engagement scope gates. This plan cannot expand `createEngagement` targets or time. An external-client plan needs a provider client-work approval reference before model drafting, and `no-model` permits only the deterministic draft. See the [plan schema and example](docs/agentic-assessment-workflow.md#assessment-plan-example).
  72. After a plan with `modelDataPolicy: "local-agent"` or `"approved-provider"` and nonempty `allowedToolNames` is recorded, launch the tool-using run:
  73. ```json
  74. {
  75. "tool": "runAgentAssessment",
  76. "arguments": {
  77. "engagementId": "client-2026-10",
  78. "profileId": "daybreak-cli-assessment",
  79. "timeoutSeconds": 900
  80. }
  81. }
  82. ```
  83. The response includes a run ID, status, model, `toolCounts`, imported evidence IDs, `importMapRecordId`, and an ID for unreviewed model output. If the model, MCP child, or an assessment tool fails, inspect the retained failure and any imported records before retrying. If only a start receipt exists after a process interruption, verify that the old process stopped and call `reconcileAgentAssessment` with that run ID, the reviewer identity, and the reason for the decision. The server will not silently replay the run. A process that finishes without a successful assessment-tool call is rejected; its bounded output is retained privately with a failed outcome and linked hash for diagnosis, never as verified finding evidence. A completed agent process does not make its observations confirmed findings. The worker blocks engagement creation, closure, plan changes, recursive assessment launches, reconciliation, and report publication.
  84. ### Ask for useful wordlist clues
  85. Call `generateWordlist` with `engagementId` and omit `baseWords` when the MCP client supports form elicitation. The server asks the authorized operator for known names and aliases, organization or product terms, dates, location or address terms, and prefix or suffix patterns. They may skip unknown categories or decline. The prompt excludes current passwords and patient data. If the client lacks form elicitation, the tool returns the questions so the assistant can ask and retry with explicit `baseWords`, `dates`, `locationWords`, and `customPatterns`. The private wordlist record retains input counts and a SHA-256 digest rather than the supplied words or a sample of the list. Wordlist creation does not authorize password attempts; `hydraBruteforce`, `runJohnTheRipper`, and `runHashcat` must also fit the engagement methods.
  86. ### Produce an evidence-backed report
  87. `createClientReport` requires a registered engagement, client, title, assessment type, summary, and explicit `recordIds`. Use `[]` only when no tool evidence should be attached. Select the evidence records for each report deliberately; the server never silently chooses a limited subset. Audit, scope-gate, and report-workflow records cannot be attached as vulnerability evidence. Supply analyst-confirmed findings with severity, impact, remediation, verifier, timestamp, and evidence references. Scanner output remains an observation until a researcher verifies it. A report with an empty `findings` array explicitly says no analyst-verified vulnerability findings were included.
  88. ```json
  89. {
  90. "tool": "createClientReport",
  91. "arguments": {
  92. "engagementId": "client-2026-10",
  93. "client": "Example Client",
  94. "title": "External Assessment",
  95. "assessmentType": "External network",
  96. "summary": "Assessment activity and verified outcomes are summarized below.",
  97. "recordIds": [],
  98. "findings": [],
  99. "recommendations": ["Review the evidence index and validate remediation with a retest."],
  100. "methodology": "Authorized, scoped enumeration and manual verification.",
  101. "limitations": ["The example has no attached scan records."]
  102. }
  103. }
  104. ```
  105. Replace `recordIds` with IDs from this engagement and add verified findings only after manual review. Each finding can include `evidenceRecordIds`, `externalEvidence`, affected assets, reproduction steps, references, CWE, CVSS vector, and retest status. Optional `scopeOfWork` text adds report context; it does not change executable scope. The report includes scope details from the registered engagement, verified severity counts, a completeness checklist, an evidence index with raw-output SHA-256 hashes, and limitations. Raw scanner output is kept in private evidence records rather than copied into the client-facing Markdown.
  106. `listClientReports` takes `engagementId`. `getClientReport` takes `engagementId` and `reportId`, with `format` set to `markdown` or `json`. The Markdown report is also available as the `mcp://pentest/clientReport/{reportId}` resource.
  107. For an agent-assisted report, call `draftAssessmentReport` after assessment records exist. Omit `profileId` for a deterministic evidence inventory or select a configured **draft** profile for model-written observations. `local-agent` permits CLI profiles and loopback `openai-compatible` profiles; `approved-provider` permits a configured API or CLI profile, including OpenRouter. Both receive bounded scope, plan and evidence summaries and may suggest unverified candidates. Under `metadata-only`, the model receives structural counts, tool names, evidence IDs and digests without client or plan prose, target names, authorization reference, evidence summaries or observations; candidate vulnerabilities are rejected. `publishAgentReport` requires a reviewer and explicit verified findings with evidence IDs and never promotes candidates automatically.
  108. ## Tool inventory
  109. | Work | Tools |
  110. | --- | --- |
  111. | Engagement lifecycle | `createEngagement`, `getEngagement`, `listEngagements`, `closeEngagement` |
  112. | Discovery and validation | `nmapScan`, `gobuster`, `nikto`, `subfinderEnum`, `httpxProbe`, `ffufScan`, `nucleiScan` |
  113. | Capture and credential checks | `trafficCapture`, `hydraBruteforce`, `runJohnTheRipper`, `runHashcat`, `generateWordlist` |
  114. | Local audit and extraction | `privEscAudit`, `extractionSweep` |
  115. | Scope, agent, and report workflow | `saveAssessmentPlan`, `getAssessmentPlan`, `listAgentProfiles`, `runAgentAssessment`, `reconcileAgentAssessment`, `recordResearchActivity`, `draftAssessmentReport`, `listAgentReportDrafts`, `getAgentReportDraft`, `publishAgentReport` |
  116. | Evidence and direct reports | `listEngagementRecords`, `getEngagementRecord`, `createClientReport`, `listClientReports`, `getClientReport` |
  117. | Runtime and scan control | `getRuntimeStatus`, `listActiveScans`, `cancelScan` |
  118. Gobuster and Nikto accept Basic Auth and cookie values only as literal command arguments in the installed CLI versions, so the MCP tools reject those fields, URL userinfo, and query strings. Their immediate responses and report drafts include counts but not scanner text; new successful records retain private raw output and finding details for the engagement owner. Failed runs retain output digests. Use an operator-reviewed execution method outside these tools when authenticated scanning is required. Historical Gobuster/Nikto records are redacted on MCP reads and report drafting; previously stored files should be handled under the engagement's retention policy.
  119. `trafficCapture` needs network capabilities and access to the interface being captured. In Docker, use the explicit Linux capture profile below. `privEscAudit` is available only over local stdio; inside a container it audits that container, so run the server natively when the authorized target is the host itself. Hashcat GPU acceleration also depends on host hardware and device passthrough, which the default container does not configure.
  120. `runHashcat` can use Hashcat 8's bundled PCFG attack and custom hash recipes when version 8 is installed on the execution host; v8-only requests are rejected on older runtimes. It also accepts OpenCL/backend device IDs; FPGA bcrypt requires Hashcat 8, Linux, a compatible bridge, and a supported board. The Dockerfile builds the signed 8.0.0 source release and includes CPU OpenCL, while the default container does not pass through GPU or FPGA hardware. See [Hashcat usage](HASHCAT_USAGE.md) for inputs, version checks, and evidence handling.
  121. `getRuntimeStatus` reports the active transport, remote execution gate, command limits, Nuclei template readiness, and expected binary availability. `listActiveScans` lists Nmap scans for one engagement; `cancelScan` needs that engagement ID and a returned scan ID. The server also warns at startup when expected host commands are missing. A missing binary or failed command is a tool error, not evidence that a target is clean. Keep tool output and test limitations with the engagement record.
  122. Nuclei requires an absolute `MCP_NUCLEI_TEMPLATES_DIR` containing operator-reviewed,
  123. signed HTTP templates. The server does not accept caller-selected template paths.
  124. It selects HTTP templates, excludes Interactsh templates, disables redirects,
  125. headless execution, automatic probing, stdin targets, and update checks. Its
  126. target also needs host-wide authorization, because templates may contact other
  127. ports on that host. Template review and a network egress policy remain necessary:
  128. an HTTP template can specify another destination. The bundled template library
  129. is available for review but is not selected automatically.
  130. ## Transport and authentication
  131. - `stdio` is the default local transport.
  132. - `http` uses Streamable HTTP at `/mcp` with a `/health` endpoint. Direct local use binds to `127.0.0.1` by default.
  133. - Legacy `sse` is disabled because its shared session cannot isolate clients.
  134. For HTTP use, configure bearer verification first (see the example below):
  135. ```bash
  136. MCP_AUTH_ENABLED=true MCP_TRANSPORT=http MCP_SERVER_HOST=127.0.0.1 MCP_SERVER_PORT=8000 pentest-mcp
  137. ```
  138. Every `/mcp` HTTP request, including loopback requests, requires configured bearer authentication. With authentication disabled, `/mcp` returns 401; `/health` remains available. Local stdio uses the OS-controlled parent process and inherited pipes as its trust boundary; do not expose those pipes to untrusted clients.
  139. A non-loopback HTTP listener requires `MCP_AUTH_ENABLED=true`, an exact
  140. `MCP_ALLOWED_ORIGINS` list, `MCP_OIDC_ISSUER`, `MCP_AUTH_AUDIENCE`, and an HTTPS
  141. `MCP_PUBLIC_BASE_URL`. Issuer and audience are required for authenticated HTTP
  142. even when a reverse proxy publishes a loopback-bound listener. Bearer tokens
  143. must be verified through an OIDC JWKS URL or introspection endpoint. A request
  144. that supplies an `Origin` header is rejected unless it matches the allowed
  145. list. Put remote access behind TLS and an explicit network policy.
  146. Authenticated HTTP scanner execution has a separate default-off gate:
  147. `MCP_REMOTE_EXECUTION_ENABLED=true`. Enable it only for a dedicated, trusted
  148. deployment with the engagement's authorization and access policy in place.
  149. When false, authenticated clients cannot launch assessment commands, and
  150. cannot start `runAgentAssessment` or a model-backed `draftAssessmentReport`.
  151. Bearer tokens need the `read` scope for discovery and evidence retrieval,
  152. `write` for engagement and report changes, and `execute` for scanners and
  153. command cancellation. Each tool checks its own required scope; batched calls
  154. need every scope they use. The scope names can be mapped to provider-specific
  155. tokens with `MCP_AUTH_READ_SCOPE`, `MCP_AUTH_WRITE_SCOPE`, and
  156. `MCP_AUTH_EXECUTE_SCOPE`. The old `MCP_AUTH_SCOPES` setting is ignored.
  157. All tool input files, including local John and Hashcat inputs, may read only wordlists
  158. generated for that token owner or files under an operator-configured absolute
  159. `MCP_SHARED_WORDLIST_DIR`. Mount a shared directory read-only in Docker. Hash
  160. cracking, host packet capture, and host privilege audit remain local stdio tools. John accepts only one `--wordlist=ABSOLUTE_PATH` and one `--format=NAME`; configuration, external code, session, and output overrides are rejected. Hashcat accepts bounded inline masks and charsets, approved wordlist/rules files, and typed numeric parameters. Session, restore, loopback, raw options, and caller-selected output paths are disabled. Both crackers run in private temporary working directories that are removed afterward.
  161. ```bash
  162. MCP_TRANSPORT=http
  163. MCP_SERVER_HOST=127.0.0.1
  164. MCP_SERVER_PORT=8000
  165. MCP_AUTH_ENABLED=true
  166. MCP_AUTH_MODE=bearer
  167. MCP_ALLOWED_ORIGINS=https://research.example.com
  168. MCP_PUBLIC_BASE_URL=https://research.example.com
  169. MCP_OIDC_ISSUER=https://issuer.example.com
  170. MCP_OIDC_JWKS_URL=https://issuer.example.com/.well-known/jwks.json
  171. MCP_AUTH_AUDIENCE=pentest-mcp
  172. MCP_AUTH_READ_SCOPE=read
  173. MCP_AUTH_WRITE_SCOPE=write
  174. MCP_AUTH_EXECUTE_SCOPE=execute
  175. MCP_REMOTE_EXECUTION_ENABLED=true
  176. ```
  177. `MCP_OIDC_INTROSPECTION_URL` can be used instead of JWKS, with `MCP_OAUTH_CLIENT_ID` and `MCP_OAUTH_CLIENT_SECRET` when the provider requires them. Legacy `MCP_OAUTH_*` aliases remain accepted but should be migrated. The Docker HTTP profile always enables authentication, including when it publishes only to loopback.
  178. ## Operational limits
  179. - `MCP_COMMAND_TIMEOUT_MS` and `MCP_COMMAND_OUTPUT_LIMIT_BYTES` bound command execution and captured output. A timed-out, nonzero-exit, or truncated command must be reviewed as incomplete. Tracked subprocess failures are recorded with a failed or cancelled `outcome` and appear as such in the report evidence index.
  180. - MCP request cancellation and closing an engagement abort active tracked commands. A managed assessment also checks the authoritative parent engagement before every MCP tool dispatch and polls it while Codex runs; closure cancels the container run and closes its worker scope. Scanner subprocesses use the captured scope deadline, including for Nmap, and recheck engagement status immediately before launch.
  181. - `rawOptions` and scanner features that can override declared targets are restricted, but externally maintained templates and scripts still need operator review.
  182. - Reports are analyst-authored; the server does not infer vulnerability severity from an open port or a scanner template match.
  183. - There is no automatic ticket sync, cloud upload, or proof that the declared authorization reference is valid.
  184. ## Docker
  185. The Compose image below runs the Pentest MCP server. The managed Codex assessment uses a **different** pinned image and Docker context; follow the [container assessment guide](docs/container-assessment.md) for that worker. Its Codex container has bridge networking for model access, while the scanner MCP child runs on the host. Neither side has a destination egress allowlist here, so apply host and VM network policy before client testing.
  186. Docker Compose defaults to a local stdio service with no published port. It runs
  187. as an unprivileged user, drops Linux capabilities, and persists scan records,
  188. reports, and the scan journal in the host data directory. Prepare that private
  189. directory before starting the container:
  190. ```bash
  191. cp .env.example .env
  192. mkdir -p .pentest-data
  193. chmod 700 .pentest-data
  194. docker compose run --build --rm -T pentest-mcp
  195. ```
  196. The host directory is `PENTEST_DATA_HOST_DIR` (default `./.pentest-data`),
  197. mounted at the container's `PENTEST_DATA_DIR=/var/lib/pentest-mcp`. On Linux,
  198. make the host directory writable by container UID 1000 before the first run
  199. (for example, `sudo chown 1000:1000 .pentest-data`). Compose will refuse to
  200. auto-create a missing bind path. Protect and back up this directory as client
  201. evidence; it is excluded from Git and the Docker build context.
  202. ### HTTP access
  203. The HTTP profile is opt-in and publishes to `127.0.0.1` by default. It always
  204. enables bearer authentication. In `.env`, configure exact
  205. `MCP_ALLOWED_ORIGINS`, `MCP_OIDC_ISSUER`, `MCP_AUTH_AUDIENCE`, an HTTPS
  206. `MCP_PUBLIC_BASE_URL`, and either `MCP_OIDC_JWKS_URL` or
  207. `MCP_OIDC_INTROSPECTION_URL`. Set OAuth client credentials if introspection
  208. requires them. The server fails startup if these listener and verifier
  209. requirements are missing. Keep `MCP_REMOTE_EXECUTION_ENABLED=false` until
  210. this is a dedicated trusted scanner deployment, then explicitly set it to
  211. `true` to permit authenticated scanner calls.
  212. ```bash
  213. chmod 600 .env
  214. docker compose --profile http up --build pentest-mcp-http
  215. ```
  216. The endpoint is `http://127.0.0.1:8000/mcp` unless you change
  217. `MCP_SERVER_PORT`. Compose uses that same port inside and outside the
  218. container. Compose binds the service to `0.0.0.0` inside its network namespace,
  219. so the HTTPS public base URL and identity settings are required even when the
  220. published host port remains on loopback. For remote clients, keep the Compose
  221. listener on loopback and put a TLS reverse proxy with access controls in front
  222. of it. Set
  223. `MCP_BIND_ADDRESS` to a non-loopback address only when that address and its
  224. firewall policy are intentional; bearer tokens must travel over TLS.
  225. ### Network capture and custom wordlists
  226. The default container can scan targets on its Docker network but cannot capture
  227. host interface traffic. On a Linux host, the separate capture profile opts in
  228. to host networking plus `NET_RAW` and `NET_ADMIN` for `tcpdump`:
  229. ```bash
  230. docker compose --profile capture run --build --rm -T pentest-mcp-capture
  231. ```
  232. That profile can observe the host network namespace and should be used only
  233. when the engagement allows packet capture. Docker Desktop does not provide the
  234. same host interface access. To use private wordlists without adding them to
  235. the image, attach a read-only host directory to a one-off run:
  236. ```bash
  237. docker compose run --rm -T --volume /absolute/wordlists:/app/custom-wordlists:ro pentest-mcp
  238. ```
  239. To enable reviewed, signed Nuclei HTTP templates in Compose, set
  240. `MCP_NUCLEI_TEMPLATES_HOST_DIR` in `.env` to an absolute host directory and use
  241. the opt-in override file. It mounts that directory read-only at
  242. `/reviewed-nuclei`:
  243. ```bash
  244. docker compose -f docker-compose.yml -f docker-compose.nuclei.yml run --build --rm -T pentest-mcp
  245. ```
  246. The Docker image installs:
  247. - `nmap`, `john`, `hashcat`, `gobuster`, `nikto`, `ffuf`, `hydra`, `sqlmap`, `tcpdump`
  248. - `subfinder`, `httpx` + `httpx-toolkit` alias, `nuclei`
  249. ## Required Host Tools (non-Docker runs)
  250. Ensure the binaries are in `PATH`:
  251. ```bash
  252. which nmap john hashcat gobuster nikto subfinder httpx-toolkit ffuf nuclei hydra sqlmap tcpdump
  253. ```
  254. If `httpx-toolkit` is not installed, a validated ProjectDiscovery `httpx` binary is accepted as fallback.
  255. ## MCP assessment contract
  256. The October 2026 server declares `@modelcontextprotocol/sdk@^1.32.2` and exposes the tool inventory above over stdio or authenticated Streamable HTTP. Tools have Zod schemas and MCP annotations. An assessment CLI should load the **entire catalog**, then select a method based on the engagement plan, available binaries, and observed results. It must treat tool output and target content as untrusted data. An MCP transport connection is not itself evidence of a test: the durable record and matching scope decision are the acceptance evidence.
  257. The server's target gate checks declared inputs before execution. It cannot prove that a third-party tool will never make secondary requests. Keep the agent's OS identity, filesystem mounts, credentials, outbound network policy, and the scanner's own configuration aligned with the signed scope. For a client engagement, separate the scope author, assessment agent, and report reviewer so the agent does not inherit repository-building conversations or another client's context.
  258. Keep client-specific deployment inventories, authorization gaps, host details, and evidence locations in private engagement storage outside the public repository and model-builder context. The [Daybreak and Glasswing note](docs/research/daybreak-glasswing-2026-10-25.md) identifies current program and client-work access requirements. An API key or CLI model label by itself is not a grant to run a customer assessment.
  259. ## Security notice
  260. Use the server only on systems covered by explicit written authorization. Keep evidence and client data private, and validate findings before reporting them.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.