@integsec/agentic-pentest-proxy 0.3.4 → 0.3.5

package/docs/images/tui-out-of-scope.svg

@@ -0,0 +1,25 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1140" height="530" viewBox="0 0 1140 530">
+<rect width="1140" height="530" rx="16" fill="#0b1220"/>
+<rect x="1" y="1" width="1138" height="528" rx="15" fill="none" stroke="#26364f" stroke-width="2"/>
+<circle cx="32" cy="31" r="7" fill="#ff718a"/><circle cx="56" cy="31" r="7" fill="#f7c977"/><circle cx="80" cy="31" r="7" fill="#51d6a0"/>
+<text x="570" y="38" text-anchor="middle" fill="#a9bad0" font-family="Cascadia Code, Consolas, monospace" font-size="16">Out-of-scope target blocked</text>
+<line x1="20" y1="60" x2="1120" y2="60" stroke="#26364f"/>
+<text x="42" y="95" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐</tspan></text>
+<text x="42" y="119" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#dce7f4">│ DEMO-001 | Example Labs | tester@example.test                                                                │</tspan></text>
+<text x="42" y="143" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</tspan></text>
+<text x="42" y="167" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐</tspan></text>
+<text x="42" y="191" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#dce7f4">│ ✓ Allowed: 5   ✗ Blocked: 2   Total: 7                                                                       │</tspan></text>
+<text x="42" y="215" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#8190a5">│ Targets: 192.0.2.10 (2)  app.example.test (2)  192.0.2.11 (1)                                                │</tspan></text>
+<text x="42" y="239" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#8190a5">│ Tools: nmap_scan (3)  httpx (2)  nuclei (2)                                                                  │</tspan></text>
+<text x="42" y="263" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</tspan></text>
+<text x="42" y="287" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐</tspan></text>
+<text x="42" y="311" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#dce7f4">│  LIVE FEED                                                                                                   │</tspan></text>
+<text x="42" y="335" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#51d6a0">│ 14:30:02 [scanner-scoped] ✓ ALLOWED nmap_scan → 192.0.2.10 (12ms)                                            │</tspan></text>
+<text x="42" y="359" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#51d6a0">│ 14:30:05 [scanner-scoped] ✓ ALLOWED httpx → app.example.test (22ms)                                          │</tspan></text>
+<text x="42" y="383" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#51d6a0">│ 14:30:09 [scanner-scoped] ✓ ALLOWED nuclei → app.example.test (34ms)                                         │</tspan></text>
+<text x="42" y="407" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#51d6a0">│ 14:30:12 [scanner-scoped] ✓ ALLOWED nmap_scan → 192.0.2.11 (11ms)                                            │</tspan></text>
+<text x="42" y="431" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#ff718a">│ 14:30:18 [scanner-scoped] ✗ BLOCKED nmap_scan → 198.51.100.20 [NOT_IN_SCOPE] (2ms)                           │</tspan></text>
+<text x="42" y="455" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#ff718a">│ 14:30:22 [scanner-scoped] ✗ BLOCKED httpx → hr.example.test [EXCLUDED_TARGET] (1ms)                          │</tspan></text>
+<text x="42" y="479" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#51d6a0">│ 14:30:27 [scanner-scoped] ✓ ALLOWED nuclei → 192.0.2.10 (25ms)                                               │</tspan></text>
+<text x="42" y="503" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</tspan></text>
+</svg>

package/docs/images/tui-policy-blocks.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1140" height="506" viewBox="0 0 1140 506">
+<rect width="1140" height="506" rx="16" fill="#0b1220"/>
+<rect x="1" y="1" width="1138" height="504" rx="15" fill="none" stroke="#26364f" stroke-width="2"/>
+<circle cx="32" cy="31" r="7" fill="#ff718a"/><circle cx="56" cy="31" r="7" fill="#f7c977"/><circle cx="80" cy="31" r="7" fill="#51d6a0"/>
+<text x="570" y="38" text-anchor="middle" fill="#a9bad0" font-family="Cascadia Code, Consolas, monospace" font-size="16">Technique and time guardrails</text>
+<line x1="20" y1="60" x2="1120" y2="60" stroke="#26364f"/>
+<text x="42" y="95" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐</tspan></text>
+<text x="42" y="119" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#dce7f4">│ DEMO-001 | Example Labs | tester@example.test                                                                │</tspan></text>
+<text x="42" y="143" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</tspan></text>
+<text x="42" y="167" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐</tspan></text>
+<text x="42" y="191" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#dce7f4">│ ✓ Allowed: 3   ✗ Blocked: 3   Total: 6                                                                       │</tspan></text>
+<text x="42" y="215" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#8190a5">│ Targets: 192.0.2.10 (3)  app.example.test (2)  192.0.2.11 (1)                                                │</tspan></text>
+<text x="42" y="239" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#8190a5">│ Tools: nmap_scan (2)  httpx (1)  nuclei (1)                                                                  │</tspan></text>
+<text x="42" y="263" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</tspan></text>
+<text x="42" y="287" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐</tspan></text>
+<text x="42" y="311" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#dce7f4">│  LIVE FEED                                                                                                   │</tspan></text>
+<text x="42" y="335" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#51d6a0">│ 14:30:02 [scanner-scoped] ✓ ALLOWED nmap_scan → 192.0.2.10 (12ms)                                            │</tspan></text>
+<text x="42" y="359" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#51d6a0">│ 14:30:05 [scanner-scoped] ✓ ALLOWED httpx → app.example.test (22ms)                                          │</tspan></text>
+<text x="42" y="383" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#51d6a0">│ 14:30:09 [scanner-scoped] ✓ ALLOWED nuclei → app.example.test (34ms)                                         │</tspan></text>
+<text x="42" y="407" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#ff718a">│ 14:31:03 [scanner-scoped] ✗ BLOCKED slowloris → 192.0.2.10 [TECHNIQUE] (1ms)                                 │</tspan></text>
+<text x="42" y="431" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#ff718a">│ 14:31:06 [scanner-scoped] ✗ BLOCKED shell_command → 192.0.2.10 [UNINSPECTABLE_COMMAND] (1ms)                 │</tspan></text>
+<text x="42" y="455" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#ff718a">│ 14:31:10 [scanner-scoped] ✗ BLOCKED nmap_scan → 192.0.2.11 [OUTSIDE_WINDOW] (1ms)                            │</tspan></text>
+<text x="42" y="479" xml:space="preserve" font-family="Cascadia Code, Consolas, DejaVu Sans Mono, monospace" font-size="16"><tspan fill="#49617f">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</tspan></text>
+</svg>

package/docs/integrations.md

@@ -0,0 +1,74 @@
+# Connect MCP clients and tools
+
+The proxy sits between one MCP client entry and one upstream MCP tool. Run [setup](../README.md#quick-start-add-an-mcp-tool) once per tool, then paste each generated entry under the client's `mcpServers` object.
+
+## Stdio tools
+
+Take the launch command from the tool's own instructions and put it after `--`. For example, if the tool normally starts with `npx -y @example/scanner-mcp`:
+
+```bash
+integsec-agentic-pentest-setup --name scanner-scoped --manifest ./scope.json -- npx -y @example/scanner-mcp
+```
+
+The helper prints a complete `mcpServers` JSON object with an absolute manifest path, an audit directory beside it, and a JSON argument array. Paste only the new named entry if your config already has an `mcpServers` object. Keep the other entries intact.
+
+For a second tool, repeat with a different name and command. For example:
+
+```bash
+integsec-agentic-pentest-setup --name inventory-scoped --manifest ./scope.json -- node ./tools/inventory-server.js
+```
+
+The generated entries work in Claude Desktop's MCP server configuration and Claude Code's project `.mcp.json`. For other clients, copy the generated `command` and `env` values into that client's equivalent server settings. A project-local npm install can run the helper with `npm exec -- integsec-agentic-pentest-setup ...`.
+
+## SSE upstreams, including Burp Suite
+
+Start the upstream SSE server first. Use its actual URL:
+
+```bash
+integsec-agentic-pentest-setup --name burp-scoped --manifest ./scope.json --sse http://127.0.0.1:9876
+```
+
+The MCP client still launches the proxy as a local command; the proxy connects to the SSE upstream. The URL above is an example and must match your upstream listener.
+
+## HTTP and Docker
+
+Use HTTP mode when a client connects to a proxy URL instead of launching a local stdio command. Set `MCP_TRANSPORT=http`, `UPSTREAM_MCP_URL`, and a scope manifest source. The proxy listens on `127.0.0.1:9090` by default. Point the client to the proxy at the same path it would use on the upstream, such as `http://127.0.0.1:9090/mcp`.
+
+The container listens on all interfaces. Set `PROXY_AUTH_TOKEN` and have the client send it in `X-Proxy-Token`. Use TLS termination for remote clients. The example below assumes the token is already set in your host environment and the manifest path is replaced with an absolute path on your machine:
+
+```bash
+docker run --rm \
+  -e MCP_TRANSPORT=http \
+  -e UPSTREAM_MCP_URL=http://host.docker.internal:8080 \
+  -e SCOPE_MANIFEST_PATH=/scope.json \
+  -e PROXY_AUTH_TOKEN \
+  --mount type=bind,source=/path/to/scope.json,target=/scope.json,readonly \
+  -p 127.0.0.1:9090:9090 \
+  ghcr.io/integsec/agentic-pentest-proxy:latest
+```
+
+The upstream URL and bind mount must match your environment. The container's audit directory is `/app/audit`; mount it to durable storage if you need to retain logs. A `GET /healthz` check is available in HTTP mode.
+
+The same release is intended for Docker Hub as `integsec/agentic-pentest-mcp-proxy:<version>`. The GHCR package may require GitHub authentication depending on its visibility.
+
+GCP SDKs are omitted from the default image. To build an image with GCP logging and Secret Manager support from source:
+
+```bash
+docker build --build-arg INCLUDE_GCP_SDKS=true -t agentic-pentest-proxy:gcp .
+```
+
+## Monitor the audit log
+
+Run the TUI in another terminal using the audit directory printed by setup:
+
+```bash
+integsec-agentic-pentest-tui --audit-path /path/to/audit
+```
+
+For a one-off run without global installation:
+
+```bash
+npm exec --yes --package=@integsec/agentic-pentest-proxy -- integsec-agentic-pentest-tui --audit-path /path/to/audit
+```
+
+The TUI reads local JSONL files and can filter with `--engagement <id>`. It does not connect to cloud logging backends. [Screenshots and fields](tui.md).

package/docs/managed-gateway.md

@@ -1,5 +1,7 @@
 # Managed MCP gateway
 
+Start with the [architecture diagram and local-versus-hosted guide](https://agentic-proxy.pentestprepper.com/docs). All project guides are available on that site after team sign-in, with source and history in the [GitHub repository](https://github.com/IntegSec/agentic-pentest-proxy).
+
 The gateway combines MCP servers behind one `/mcp` endpoint. Its browser page at `/admin` lets administrators manage users and servers, review and approve scopes, and assign engagements. Each tester chooses their own approved engagement. With no selection, the gateway exposes no tools. Every `tools/call` passes through the scope validator and audit log. Tool names are prefixed with the server name, such as `burp__scan`.
 
 This is a new mode. The original per-tool stdio, SSE, and HTTP proxy commands remain available.

package/docs/release-readiness-0.2.6.md

@@ -0,0 +1,27 @@
+# Release review: 0.2.6
+
+Reviewed against GitHub `master` at `af9657d05d8b54c8c0e7d917739e4b6460dd618d`.
+
+## Changes
+
+- Scope checks now require every DNS answer to fit authorized IP ranges when IP ranges provide the authorization. Explicit exclusions are checked before DNS.
+- URL scope entries enforce scheme, host, port, and path prefix. Unknown targetless tools, deeply nested arguments, and free-form commands are denied by default.
+- HTTP forwarding is pinned to the configured upstream origin, has a request size limit, and requires a proxy token on non-loopback interfaces. Parsed JSON is reserialized before forwarding.
+- Audit redaction covers compound credential keys, URL credentials, sensitive query values, unstructured bodies, and invalid argument payloads. Engagement IDs cannot escape the audit directory through filenames.
+- AWS, Azure, and GCP secret-loading dependencies are packaged. Azure logging uses the DCR/DCE ingestion endpoint, and Key Vault secret URIs are parsed correctly.
+- The vulnerable CIDR dependency was replaced. Runtime and test dependencies were upgraded to versions with no current npm audit advisories. The container has a writable audit directory and an HTTP health check.
+- Personal machine paths were removed from examples; the tracked local settings file was removed and ignored.
+
+## Verification
+
+- `npm run lint`, `npm run build`, and 1,013 automated tests pass on Node 24.
+- `npm audit` reports zero advisories across the lockfile.
+- `npm pack --dry-run` contains the expected 0.2.6 package. The Docker build runs in GitHub CI because a local Docker daemon was unavailable during this review.
+
+## Deployment and operating limits
+
+- The proxy checks only MCP arguments it can see. It cannot guarantee the destinations chosen by upstream tools, redirects, file inputs, encoded payloads, or DNS changes after validation. Enforce engagement scope with network egress policy as well, and review the schemas of the MCP servers used by the team.
+- Keep `ALLOW_UNSTRUCTURED_COMMANDS=false`. The opt-in parser is heuristic and is not suitable as the only scope boundary.
+- The local audit file must remain writable and monitored. As designed, logging failures do not stop tool calls.
+- Cloud logging requires live credentialed tests in each target account before claiming that an integration is operational there.
+- Remote HTTP deployments require TLS termination, a secret `PROXY_AUTH_TOKEN`, and a private network or gateway.

package/docs/security.md

@@ -0,0 +1,33 @@
+# Security model
+
+Use this proxy as one layer of engagement control. It checks MCP `tools/call` requests before forwarding them to an upstream MCP server. It does not inspect arbitrary traffic sent outside MCP.
+
+## Enforced checks
+
+- Requests must have an inspectable tool name and JSON object arguments.
+- Recognized tool categories are compared with `authorized_techniques` and `excluded_techniques`.
+- Calls outside the manifest time window are blocked.
+- The proxy extracts all visible targets and checks each one; one blocked target blocks the call.
+- Exclusions win over broader authorizations. CIDR targets must fit inside an allowed CIDR and avoid exclusions.
+- DNS failures block the call. A hostname authorized only by IP range must resolve entirely inside that range.
+- URL entries restrict scheme, host, port, and path prefix.
+- Free-form commands and unrecognized targetless tool calls are blocked by default.
+- HTTP listeners bound beyond loopback require `PROXY_AUTH_TOKEN`; clients send `X-Proxy-Token`.
+
+Every decision is logged locally as JSONL after parameter sanitization. Cloud audit backends are additional; a cloud logging failure does not stop the tool call. Protect the local audit directory and monitor backend errors.
+
+## Boundaries
+
+The proxy cannot verify a destination selected later inside an upstream tool, a redirect, a target loaded from a file or encoded payload, DNS changes between check and execution, or traffic that never goes through this MCP proxy. Tool names also do not fully describe what a tool does. Review the upstream tool schemas and keep network egress controls in place for production engagements.
+
+`ALLOW_UNSTRUCTURED_COMMANDS=true` enables heuristic inspection of free-form command fields. It weakens the default scope check; use only after reviewing the specific upstream tool.
+
+For HTTP clients on a network, use TLS termination and keep the bearer token out of command history and committed files. The proxy should not be exposed directly to the public internet.
+
+## Container image
+
+The published image runs as an unprivileged user with only Node.js, production dependencies, and the built proxy. Its build upgrades Alpine OS packages. CI and release jobs smoke test the image and block publication if Trivy reports a moderate, high, or critical vulnerability. Scan results are a point-in-time check; rebuild and rescan after base image or advisory updates.
+
+### Docker Scout musl finding (November 2026)
+
+Docker Scout may flag CVE-2026-107891 for `musl 1.2.6-r3` in the Alpine 3.24 image and suggest `1.2.6-r6`. [Alpine's security tracker](https://security.alpinelinux.org/vuln/CVE-2026-107891) marks `1.2.6-r3` as fixed on the 3.24 branch; `1.2.6-r6` is the separate fix version for Alpine edge. This appears to be a version-mapping false positive for this image. If a Scout exception is needed, scope it to this image and package, cite the Alpine tracker, and review it when the base image changes.