@integsec/agentic-pentest-proxy 0.2.4 → 0.2.6

package/README.md

@@ -1,8 +1,8 @@
-# IntegSec Agentic Pentest MCP Proxy
+# IntegSec Agentic Pentest Proxy
 
 **Scope enforcement proxy for AI-driven penetration testing.**
 
-The IntegSec Agentic Pentest MCP Proxy sits between an AI agent (Claude, GPT, etc.) and an MCP tool server ([TurboPentest](https://turbopentest.com), Nuclei MCP, etc.), intercepting every tool call and validating it against a scope manifest before it reaches the upstream server. Out-of-scope targets, banned techniques, and expired engagement windows are blocked in real time with a full audit trail.
+The IntegSec Agentic Pentest MCP Proxy sits between an AI agent (Claude, GPT, etc.) and an MCP tool server ([TurboPentest](https://turbopentest.com), Nuclei MCP, etc.), checking MCP `tools/call` requests against a scope manifest before forwarding them. It blocks targets, techniques, and engagement times it can identify as unauthorized and writes audit decisions locally.
 
 Built by **[IntegSec](https://integsec.com)** — offensive cybersecurity testing and threat simulation for modern organizations moving at AI speed.
 
@@ -21,14 +21,16 @@ Built by **[IntegSec](https://integsec.com)** — offensive cybersecurity testin
                                +-----------+
 ```
 
-> **Using AI agents for pentesting?** [TurboPentest](https://turbopentest.com) delivers agentic penetration testing powered by Claude — 15 orchestrated security tools, OWASP Top 10 coverage, results in under 4 hours, blockchain-attested reports. Starting at $99/domain. Pair it with this proxy for scope-safe autonomous testing.
+> **Using AI agents for pentesting?** [TurboPentest](https://turbopentest.com) delivers agentic penetration testing powered by Claude — 15 orchestrated security tools, OWASP Top 10 coverage, results in under 4 hours, blockchain-attested reports. Starting at $99/domain. Use this proxy with MCP servers like Burp Suite, Kali MCP, Nmap, and more for scope-safe autonomous testing.
 
 ---
 
 ## Table of Contents
 
 - [Why This Exists](#why-this-exists)
+- [Security Boundaries](#security-boundaries)
 - [Features](#features)
+- [Supported MCP Servers](#supported-mcp-servers)
 - [Quick Start](#quick-start)
 - [Installation](#installation)
 - [Configuration](#configuration)
@@ -39,12 +41,14 @@ Built by **[IntegSec](https://integsec.com)** — offensive cybersecurity testin
   - [CLI](#cli)
   - [Claude Desktop Integration](#claude-desktop-integration)
   - [Claude Code Integration](#claude-code-integration)
+  - [Burp Suite Integration](#burp-suite-integration)
   - [Docker](#docker)
   - [HTTP Mode](#http-mode)
 - [TUI Monitor](#tui-monitor)
 - [How Validation Works](#how-validation-works)
 - [Audit Logging](#audit-logging)
 - [Examples](#examples)
+- [Manifest Builder](#manifest-builder)
 - [Contributing](#contributing)
   - [Architecture](#architecture)
   - [Development Setup](#development-setup)
@@ -63,17 +67,24 @@ Built by **[IntegSec](https://integsec.com)** — offensive cybersecurity testin
 
 AI agents equipped with offensive security tools (nmap, sqlmap, Metasploit, etc.) can cause serious harm if they stray outside an authorized engagement scope. A misconfigured prompt or hallucinated target can turn a legitimate pentest into an unauthorized attack.
 
-The IntegSec Agentic Pentest MCP Proxy solves this by enforcing scope at the protocol layer — not at the prompt layer. Every tool invocation is validated against a cryptographically-loadable scope manifest before it reaches the upstream MCP server. If the target, technique, or timing is wrong, the call is blocked and logged.
+The IntegSec Agentic Pentest MCP Proxy enforces scope at the protocol layer. Every tool invocation is checked against a scope manifest before it reaches the upstream MCP server. If the target, technique, or timing is wrong, the call is blocked and logged.
 
 **No prompt engineering. No honor system. Enforcement.**
 
+## Security Boundaries
+
+The proxy checks the arguments it can see in MCP `tools/call` requests. It cannot control destinations chosen inside an upstream tool, HTTP redirects, DNS changes between validation and execution, targets read from files or encoded payloads, or traffic that bypasses MCP. Use network egress controls and review each upstream tool's schema before relying on this proxy for an engagement. Keep free-form commands disabled with the default `ALLOW_UNSTRUCTURED_COMMANDS=false`.
+
+Cloud logging failures do not stop tool calls. Monitor the writable local audit directory and alert on logging errors. For remote HTTP clients, place the proxy behind TLS and set `PROXY_AUTH_TOKEN`.
+
 
 ---
 
 ## Features
 
-- **8-step validation pipeline** — technique check, time window, target extraction, DNS resolution, exclusion check, authorization check, default deny
-- **Fail-closed design** — DNS failures, unknown targets, and expired windows all result in blocks
+- **Multi-stage validation pipeline** — request shape, technique, time window, target extraction, CIDR containment, DNS resolution, exclusion, authorization, default deny
+- **Every target checked** — arrays, comma/space-separated lists, nested option objects, and `host:port` values are checked; free-form commands are blocked by default
+- **Fail-closed design** — DNS failures, malformed requests, unparseable JSON, internal errors and expired windows all result in blocks; JSON-RPC batches are checked element by element
 - **19 tool extractors + smart fallback** — built-in parameter extraction for nmap, sqlmap, burp, curl, metasploit, nuclei, gobuster, ffuf, nikto, and more, with generic fallback for unknown tools
 - **Wildcard domain matching** — `*.acme.com` matches `app.acme.com` but not `deep.sub.acme.com`
 - **CIDR + IPv6 support** — authorize by IP range, detect RFC-1918 private ranges and cloud metadata endpoints
@@ -81,13 +92,61 @@ The IntegSec Agentic Pentest MCP Proxy solves this by enforcing scope at the pro
 - **Technique blocking** — categorize tools into `dos`, `destructive`, `social_engineering`, etc., with custom mappings
 - **Parameter sanitization** — passwords, tokens, API keys, and secrets are redacted before logging
 - **Multi-backend audit logging** — local JSONL, AWS CloudWatch, Azure Monitor, GCP Cloud Logging
-- **Two transport modes** — stdio (child process) and HTTP (reverse proxy)
+- **Three transport modes** — stdio (child process), SSE (stdio-to-SSE bridge, e.g. Burp) and HTTP (reverse proxy)
 - **Cloud-native manifest loading** — load scope from file, env var, AWS Secrets Manager, Azure Key Vault, or GCP Secret Manager
 - **Docker-ready** — multi-stage build, runs as non-root user
 - **Zero runtime config files** — everything via environment variables
 
 ---
 
+## Supported MCP Servers
+
+Built-in target extraction and technique categorization for the following tools and MCP servers. Unlisted tools still receive scope enforcement via the generic parameter fallback (`target`, `url`, `host`, `domain`, etc.).
+
+### Subdomain Enumeration
+[amass](https://github.com/owasp-amass/amass) · [alterx](https://github.com/projectdiscovery/alterx) · [assetfinder](https://github.com/tomnomnom/assetfinder) · [subfinder](https://github.com/projectdiscovery/subfinder) · [shuffledns](https://github.com/projectdiscovery/shuffledns) · [Hex Strike AI MCP](https://github.com/0x4m4/hexstrike-ai) · [Kali Linux MCP](https://github.com/k3nn3dy-ai/kali-mcp)
+
+### DNS & Certificate
+[dnsx](https://github.com/projectdiscovery/dnsx) · [cero](https://github.com/glebarez/cero) · [crtsh](https://crt.sh) · [Shodan MCP](https://github.com/BurtTheCoder/mcp-shodan) (BurtTheCoder) · [Shodan MCP](https://github.com/Vorota-ai/shodan-mcp) (Vorota-ai)
+
+### HTTP Probing
+[httpx](https://github.com/projectdiscovery/httpx) · [katana](https://github.com/projectdiscovery/katana) · [gowitness](https://github.com/sensepost/gowitness) · [Burp Suite MCP](https://github.com/PortSwigger/mcp-server) · [Postman MCP](https://github.com/postmanlabs/postman-mcp-server)
+
+### Port Scanning
+[nmap](https://github.com/nmap/nmap) · [nmap_scan](https://github.com/nmap/nmap) · [masscan](https://github.com/robertdavidgraham/masscan) · [Nmap MCP Server](https://github.com/mohdhaji87/nmap-mcp-server) · [Awesome Kali MCP Servers](https://github.com/ccq1/awsome_kali_MCPServers) · [Hex Strike AI MCP](https://github.com/0x4m4/hexstrike-ai) · [Kali Linux MCP](https://github.com/k3nn3dy-ai/kali-mcp)
+
+### Web App Testing
+[nuclei](https://github.com/projectdiscovery/nuclei) · [ffuf](https://github.com/ffuf/ffuf) · [gobuster](https://github.com/OJ/gobuster) · [dirb](https://sourceforge.net/projects/dirb) · [arjun](https://github.com/s0md3v/Arjun) · [sqlmap](https://github.com/sqlmapproject/sqlmap) · [dalfox](https://github.com/hahwul/dalfox) · [smuggler](https://github.com/defparam/smuggler) · [nikto](https://github.com/sullo/nikto) · [wpscan](https://github.com/wpscanteam/wpscan) · [nessus](https://www.tenable.com/products/nessus) · [zap](https://github.com/zaproxy/zaproxy) · [burpsuite](https://portswigger.net/burp) · [burp_scan](https://portswigger.net/burp) · [burp_active_scan](https://portswigger.net/burp) · [Burp Suite MCP](https://github.com/PortSwigger/mcp-server) (PortSwigger) · [Acunetix MCP](https://github.com/therealcoiffeur/MCPwnetix) · [Hex Strike AI MCP](https://github.com/0x4m4/hexstrike-ai) · [Kali Linux MCP](https://github.com/k3nn3dy-ai/kali-mcp) · **Next.js Scanner** · **Unified All-in-One MCP**
+
+### SSL/TLS & Headers
+**SSLScan MCP** · **HTTP Headers** (Custom MCP) · [Kali Linux MCP](https://github.com/k3nn3dy-ai/kali-mcp)
+
+### OSINT & Threat Intel
+[uncover](https://github.com/projectdiscovery/uncover) · [waybackurls](https://github.com/tomnomnom/waybackurls) · [shodan](https://www.shodan.io) · [virustotal](https://www.virustotal.com) · [bloodhound](https://github.com/BloodHoundAD/BloodHound) · [notify](https://github.com/projectdiscovery/notify) · [Shodan MCP](https://github.com/BurtTheCoder/mcp-shodan) (BurtTheCoder) · [Shodan MCP](https://github.com/Vorota-ai/shodan-mcp) (Vorota-ai) · [WireMCP](https://github.com/0xKoda/WireMCP) · [VirusTotal MCP](https://github.com/BurtTheCoder/mcp-virustotal)
+
+### Exploitation
+[metasploit](https://github.com/rapid7/metasploit-framework) · [`msf_*`](https://github.com/rapid7/metasploit-framework) · [hydra](https://github.com/vanhauser-thc/thc-hydra) · [hashcat](https://github.com/hashcat/hashcat) · **CrackMapExec MCP** · **Commix MCP** · [Hex Strike AI MCP](https://github.com/0x4m4/hexstrike-ai) · [Kali Linux MCP](https://github.com/k3nn3dy-ai/kali-mcp)
+
+### Cloud Security
+[prowler](https://github.com/prowler-cloud/prowler) · [scoutsuite](https://github.com/nccgroup/ScoutSuite)
+
+### Container & IaC
+[trivy](https://github.com/aquasecurity/trivy) · [checkov](https://github.com/bridgecrewio/checkov)
+
+### Kubernetes
+[kube-hunter](https://github.com/aquasecurity/kube-hunter) · [kubeaudit](https://github.com/Shopify/kubeaudit) · [kube-bench](https://github.com/aquasecurity/kube-bench)
+
+### Code Security
+[Semgrep MCP](https://github.com/semgrep/mcp) · [Gitleaks MCP](https://github.com/FuzzingLabs/mcp-security-hub)
+
+### Reverse Engineering
+[Ghidra MCP](https://github.com/LaurieWired/GhidraMCP)
+
+### Mobile Security
+[MobSF MCP](https://github.com/pullkitsan/mobsf-mcp-server)
+
+---
+
 ## Quick Start
 
 ```bash
@@ -144,8 +203,8 @@ npm install @integsec/agentic-pentest-proxy
 ### From source
 
 ```bash
-git clone https://github.com/integsec/agentic-pentest-mcp-proxy.git
-cd agentic-pentest-mcp-proxy
+git clone https://github.com/IntegSec/agentic-pentest-proxy.git
+cd agentic-pentest-proxy
 npm install
 npm run build
 ```
@@ -156,9 +215,10 @@ npm run build
 docker build -t integsec-agentic-pentest-proxy .
 docker run --rm \
   -e SCOPE_MANIFEST_PATH=/scope.json \
-  -e MCP_TRANSPORT=sse \
+  -e MCP_TRANSPORT=http \
   -e UPSTREAM_MCP_URL=http://host.docker.internal:8080 \
   -e PROXY_PORT=9090 \
+  -e PROXY_AUTH_TOKEN \
   -v ./scope.json:/scope.json:ro \
   -p 9090:9090 \
   integsec-agentic-pentest-proxy
@@ -185,17 +245,22 @@ The scope manifest defines the boundaries of a penetration testing engagement. I
   "authorized_targets": {
     "ip_ranges": ["10.10.10.0/24", "203.0.113.0/28"],
     "domains": ["*.acme.com", "acme-staging.example.com"],
+    // Authorizes the URL's scheme, host, port and path prefix
     "urls": ["https://app.acme.com", "https://api.acme.com"],
+    // Matched against account parameters of cloud audit tools (prowler, scoutsuite)
     "cloud_accounts": ["aws:123456789012"]
   },
 
-  // Override: these are NEVER allowed even if they match above
+  // Override: these are NEVER allowed even if they match above.
+  // Accepts IPs, CIDRs ("203.0.113.0/30"), hostnames, wildcards ("*.hr.acme.com",
+  // any depth) and URLs (compared by hostname).
   "excluded_targets": ["203.0.113.5", "hr.acme.com"],
 
-  // Technique categories (for reference / future enforcement)
-  "authorized_techniques": ["recon", "web_app", "api_testing"],
+  // Allowed technique categories. When non-empty, a tool in any OTHER known
+  // category is blocked. Uncategorized tools are unaffected. [] = no restriction.
+  "authorized_techniques": ["recon", "web_app"],
 
-  // Tool categories that are always blocked
+  // Tool categories that are always blocked (wins over authorized_techniques)
   "excluded_techniques": ["dos", "destructive", "social_engineering"],
 
   // Time window — calls outside this range are blocked
@@ -225,16 +290,20 @@ The scope manifest defines the boundaries of a penetration testing engagement. I
 | `SCOPE_MANIFEST_KEYVAULT_URI` | — | Azure Key Vault secret URI |
 | `SCOPE_MANIFEST_GCP_SECRET` | — | GCP Secret Manager resource name |
 | **Transport** | | |
-| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `sse` |
+| `MCP_TRANSPORT` | `stdio` | `stdio` (spawn upstream), `sse` (agent on stdio, upstream over SSE — e.g. Burp) or `http` (listen on `PROXY_HOST:PROXY_PORT`, reverse-proxy to upstream). Anything else is a startup error |
 | `UPSTREAM_MCP_COMMAND` | — | Command to spawn upstream MCP (stdio mode) |
 | `UPSTREAM_MCP_ARGS` | — | Comma-separated args for upstream command |
-| `UPSTREAM_MCP_URL` | — | Upstream MCP HTTP URL (HTTP mode) |
-| `PROXY_PORT` | `9090` | HTTP listen port (HTTP mode) |
+| `UPSTREAM_STARTUP_DELAY_MS` | `0` | stdio mode: hold messages until the upstream prints or this delay passes. Only needed for bridges that drop early messages |
+| `UPSTREAM_MCP_URL` | — | Upstream MCP URL (`sse` and `http` modes) |
+| `PROXY_PORT` | `9090` | Listen port (`http` mode) |
+| `PROXY_HOST` | `127.0.0.1` | Listen address (`http` mode). The Docker image sets `0.0.0.0` |
+| `PROXY_AUTH_TOKEN` | — | Required for non-loopback HTTP. Clients send it in `X-Proxy-Token`; use TLS termination for remote clients |
+| `ALLOW_UNSTRUCTURED_COMMANDS` | `false` | Explicitly opt in to heuristic inspection of free-form command and argument fields; unsafe for strict scope enforcement |
 | **Audit** | | |
 | `AUDIT_LOG_PATH` | `./audit/` | Directory for local JSONL audit logs |
 | `AWS_LOG_GROUP` | — | AWS CloudWatch log group name |
 | `AWS_REGION` | — | AWS region for CloudWatch |
-| `AZURE_LOG_WORKSPACE_ID` | — | Azure Log Analytics workspace ID |
+| `AZURE_LOG_INGESTION_ENDPOINT` | — | DCR or DCE Logs Ingestion endpoint URL |
 | `AZURE_DCR_IMMUTABLE_ID` | — | Azure Data Collection Rule immutable ID |
 | `AZURE_DCR_STREAM_NAME` | `Custom-MCPProxyAudit_CL` | Azure DCR stream name |
 | `GOOGLE_CLOUD_PROJECT` | — | GCP project ID for Cloud Logging |
@@ -242,13 +311,17 @@ The scope manifest defines the boundaries of a penetration testing engagement. I
 | `TECHNIQUE_MAP_PATH` | — | Path to custom technique mappings JSON |
 | `DNS_CACHE_TTL` | `60` | DNS cache TTL in seconds |
 | `LOG_LEVEL` | `INFO` | Log verbosity |
-| `PROXY_VERSION` | `0.1.0` | Version string in audit entries |
+| `PROXY_VERSION` | `0.2.6` | Version string in audit entries |
 
 See [`.env.example`](.env.example) for a complete template.
 
 ### Technique Mappings
 
-The proxy ships with built-in technique categories (`dos`, `destructive`, `social_engineering`). You can extend these with a custom mapping file:
+The proxy ships with built-in technique categories: `dos`, `destructive`, `social_engineering`, `recon`, `web_app`, `exploitation` and `cloud_audit` (see `src/technique-checker.ts` for the tool lists). Use these names in `authorized_techniques` / `excluded_techniques`.
+
+`exact` entries match the whole tool name. `patterns` containing a separator (`nmap_`, `msf_`) match as substrings; purely alphanumeric patterns match whole words of the tool name or the end of a word (`dos` matches `dos_attack` and `ddos` but not `get_dossier`). All matching is case-insensitive.
+
+You can extend these with a custom mapping file:
 
 ```json
 {
@@ -263,7 +336,7 @@ The proxy ships with built-in technique categories (`dos`, `destructive`, `socia
 }
 ```
 
-Point `TECHNIQUE_MAP_PATH` at this file. Custom mappings are merged with built-in ones — they don't replace them.
+Point `TECHNIQUE_MAP_PATH` at this file. Custom mappings are merged with built-in ones — they don't replace them. A missing or malformed file stops the proxy at startup rather than silently dropping your blocks.
 
 ---
 
@@ -278,14 +351,22 @@ UPSTREAM_MCP_COMMAND=npx \
 UPSTREAM_MCP_ARGS="-y,@turbopentest/mcp-server" \
 integsec-agentic-pentest-proxy
 
-# HTTP mode — reverse proxy to a running MCP server
+# HTTP mode — reverse proxy to a running MCP server (listens on 127.0.0.1:9090)
 SCOPE_MANIFEST_PATH=./scope.json \
-MCP_TRANSPORT=sse \
+MCP_TRANSPORT=http \
 UPSTREAM_MCP_URL=http://localhost:8080 \
 PROXY_PORT=9090 \
 integsec-agentic-pentest-proxy
+
+# SSE mode — agent talks stdio, proxy connects to an SSE upstream (no listening port)
+SCOPE_MANIFEST_PATH=./scope.json \
+MCP_TRANSPORT=sse \
+UPSTREAM_MCP_URL=http://127.0.0.1:9876 \
+integsec-agentic-pentest-proxy
 ```
 
+In HTTP mode, point your MCP client at the proxy using the same path it would use on the upstream (e.g. `http://127.0.0.1:9090/mcp`). For a non-loopback listener, set `PROXY_AUTH_TOKEN` and configure the client to send `X-Proxy-Token`. Terminate TLS before the proxy when clients connect over a network.
+
 ### Claude Desktop Integration
 
 Add to your Claude Desktop `claude_desktop_config.json`:
@@ -328,15 +409,42 @@ Add to your `.mcp.json` or project settings:
 }
 ```
 
+### Burp Suite Integration
+
+The proxy connects directly to Burp Suite's MCP extension via SSE — no Java bridge jar needed.
+
+1. Open Burp Suite Pro and enable the MCP extension (listening on port 9876)
+2. Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "burp-scoped": {
+      "command": "integsec-agentic-pentest-proxy",
+      "args": [],
+      "env": {
+        "SCOPE_MANIFEST_PATH": "/path/to/scope.json",
+        "MCP_TRANSPORT": "sse",
+        "UPSTREAM_MCP_URL": "http://127.0.0.1:9876",
+        "AUDIT_LOG_PATH": "/path/to/audit"
+      }
+    }
+  }
+}
+```
+
+The proxy validates `targetHostname` in Burp's `send_http1_request`, `send_http2_request`, `create_repeater_tab`, and `send_to_intruder` tools — blocking requests to out-of-scope targets.
+
 ### Docker
 
 ```bash
-# HTTP mode
+# HTTP mode (the image sets PROXY_HOST=0.0.0.0 so the published port is reachable)
 docker run --rm \
   -e SCOPE_MANIFEST_PATH=/scope.json \
-  -e MCP_TRANSPORT=sse \
+  -e MCP_TRANSPORT=http \
   -e UPSTREAM_MCP_URL=http://host.docker.internal:8080 \
   -e PROXY_PORT=9090 \
+  -e PROXY_AUTH_TOKEN \
   -v ./scope.json:/scope.json:ro \
   -v ./audit:/app/audit \
   -p 9090:9090 \
@@ -345,10 +453,11 @@ docker run --rm \
 # With AWS CloudWatch
 docker run --rm \
   -e SCOPE_MANIFEST_SECRET_ARN=arn:aws:secretsmanager:us-east-1:123456789012:secret:scope \
-  -e MCP_TRANSPORT=sse \
+  -e MCP_TRANSPORT=http \
   -e UPSTREAM_MCP_URL=http://host.docker.internal:8080 \
   -e AWS_LOG_GROUP=/integsec/mcp-proxy \
   -e AWS_REGION=us-east-1 \
+  -e PROXY_AUTH_TOKEN \
   -p 9090:9090 \
   integsec-agentic-pentest-proxy
 ```
@@ -382,38 +491,58 @@ Run the TUI in a separate terminal while the proxy is active (via Claude Desktop
 
 ## How Validation Works
 
-Every `tools/call` JSON-RPC message passes through an 8-step validation pipeline:
+Every `tools/call` JSON-RPC message (including each element of a JSON-RPC batch) passes through this pipeline:
 
 ```
-1. TECHNIQUE CHECK ──▶ Is the tool in an excluded_techniques category?
+0. REQUEST SHAPE ────▶ Tool name a string? Arguments a JSON object?
+   │                    NO  → BLOCKED_INVALID_REQUEST
+   ▼
+1. TECHNIQUE CHECK ──▶ Tool in an excluded_techniques category, or in a known
+   │                    category missing from a non-empty authorized_techniques?
    │                    YES → BLOCKED_TECHNIQUE
    ▼
 2. TIME WINDOW ──────▶ Is current time within engagement_window?
    │                    NO  → BLOCKED_OUTSIDE_WINDOW
    ▼
-3. TARGET EXTRACTION ▶ Extract hostname/IP from tool parameters
-   │                    (19 tool-specific extractors + fallback params)
+   COMMAND CHECK ─────▶ Free-form command fields present without opt-in?
+   │                    YES → BLOCKED_UNINSPECTABLE_COMMAND
+   ▼
+3. TARGET EXTRACTION ▶ Extract EVERY hostname/IP/CIDR from the parameters
+   │                    (tool mappings + fallback names, arrays, lists,
+   │                    nested objects)
+   ▼
+4. NO TARGET? ───────▶ No target found?
+   │                    YES → ALLOWED_NO_TARGET only for explicitly safe local tools
+   │                    otherwise → BLOCKED_INVALID_REQUEST
    ▼
-4. NO TARGET? ───────▶ No target-like parameter found?
-   │                    YES → ALLOWED_NO_TARGET
+   For each target — any block blocks the whole call:
+5. CLOUD ACCOUNT ────▶ Matches authorized cloud_accounts? → ALLOWED
+6. CIDR TARGET ──────▶ Overlaps an exclusion → BLOCKED_EXCLUDED_TARGET
+   │                    Fully inside an authorized range → ALLOWED
+   │                    Otherwise → BLOCKED_NOT_IN_SCOPE
    ▼
-5. DNS RESOLUTION ───▶ Resolve hostname to A + AAAA records
-   │                    NXDOMAIN → BLOCKED_DNS_FAILED
+7. DNS RESOLUTION ───▶ A + AAAA, falling back to the OS resolver
+   │                    No addresses → BLOCKED_DNS_FAILED
    ▼
-6. EXCLUSION CHECK ──▶ Does target match excluded_targets?
+8. EXCLUSION CHECK ──▶ Host or any resolved IP matches excluded_targets?
    │                    YES → BLOCKED_EXCLUDED_TARGET
    ▼
-7. AUTHORIZATION ────▶ Does target match authorized_targets?
-   │                    YES → ALLOWED
+9. AUTHORIZATION ────▶ Host matches a domain, IP range or URL prefix?
+   │                      resolves to loopback/link-local/metadata not in
+   │                      ip_ranges → BLOCKED_RESTRICTED_IP, else ALLOWED
+   │                    Resolved IP in an authorized ip_range? → ALLOWED
    ▼
-8. DEFAULT DENY ─────▶ BLOCKED_NOT_IN_SCOPE
+10. DEFAULT DENY ────▶ BLOCKED_NOT_IN_SCOPE
 ```
 
 **Key design decisions:**
-- **Exclusions beat authorizations.** If `hr.acme.com` is in `excluded_targets`, it's blocked even if `*.acme.com` is authorized.
+- **Every target must pass.** `targets: ["10.10.10.5", "8.8.8.8"]` is blocked because of the second element.
+- **Exclusions beat authorizations.** If `hr.acme.com` is in `excluded_targets`, it's blocked even if `*.acme.com` is authorized — with or without a trailing dot, in any letter case. A CIDR target that *contains* an excluded IP is blocked.
 - **DNS failures are blocks.** If the proxy can't resolve a hostname, it won't forward the call. Fail closed.
-- **Private IPs require explicit authorization.** RFC-1918 ranges and cloud metadata endpoints (169.254.169.254) are only allowed if they appear in `authorized_targets.ip_ranges`.
-- **No target = allowed.** Tools that don't operate on network targets (e.g., `list_tools`, `get_version`) pass through.
+- **Restricted addresses require explicit authorization.** An authorized domain that resolves to loopback, link-local or a cloud metadata endpoint (169.254.169.254) is blocked unless that IP appears in `authorized_targets.ip_ranges`. Private RFC-1918 addresses reached through an authorized domain are allowed (internal engagements); reached directly, they need an `ip_ranges` entry like any other IP.
+- **Unparseable input is never forwarded.** Invalid JSON gets a JSON-RPC parse error (`-32700`) instead of being passed to an upstream whose parser may be more lenient.
+- **Batches are all-or-nothing.** If any tool call in a JSON-RPC batch is blocked, the whole batch is rejected with one error per request.
+- **No target is denied by default.** Only the explicitly listed local tools (`whoami`, `date`, `ls`, `list_tools`, `get_version`, `list_pentests`) may pass without a target. Free-form command fields are blocked unless `ALLOW_UNSTRUCTURED_COMMANDS=true` is set; that opt-in relies on incomplete heuristic extraction and is unsuitable when the proxy is the only scope control.
 
 ---
 
@@ -435,7 +564,7 @@ Every validation decision produces an audit entry:
   "decision_reason": "Target 10.10.10.5 matches authorized IP range 10.10.10.0/24",
   "matched_scope_item": "10.10.10.0/24",
   "duration_ms": 2,
-  "proxy_version": "0.1.0"
+  "proxy_version": "0.2.6"
 }
 ```
 
@@ -445,22 +574,26 @@ Every validation decision produces an audit entry:
 |---------|--------|--------|
 | **Local** (always active) | `AUDIT_LOG_PATH` | JSONL files: `{engagement_id}.jsonl` |
 | **AWS CloudWatch** | `AWS_LOG_GROUP` + `AWS_REGION` | Log events in `{engagement_id}/{date}` stream |
-| **Azure Monitor** | `AZURE_LOG_WORKSPACE_ID` + `AZURE_DCR_IMMUTABLE_ID` | Logs Ingestion API via Data Collection Rules |
+| **Azure Monitor** | `AZURE_LOG_INGESTION_ENDPOINT` + `AZURE_DCR_IMMUTABLE_ID` | Logs Ingestion API via Data Collection Rules |
 | **GCP Cloud Logging** | `GOOGLE_CLOUD_PROJECT` | Cloud Logging entries with severity mapping |
 
-Multiple backends can be active simultaneously. Entries are buffered and flushed every 5 seconds. Backend failures are isolated — a CloudWatch error won't affect local logging.
+Multiple backends can be active simultaneously. The local JSONL entry is written to disk before the call is forwarded, so the local trail survives an abrupt kill. Cloud backends are buffered and flushed every 5 seconds. Backend failures are isolated — a CloudWatch error won't affect local logging.
 
 ### Decision Types
 
 | Decision | Meaning |
 |----------|---------|
 | `ALLOWED` | Target matches an authorized scope item |
-| `ALLOWED_NO_TARGET` | Tool has no network target parameter |
-| `BLOCKED_TECHNIQUE` | Tool belongs to an excluded technique category |
+| `ALLOWED_NO_TARGET` | Tool is on the explicit targetless local-tool list |
+| `BLOCKED_TECHNIQUE` | Tool belongs to an excluded technique category, or a known category not in `authorized_techniques` |
 | `BLOCKED_OUTSIDE_WINDOW` | Current time is outside the engagement window |
-| `BLOCKED_EXCLUDED_TARGET` | Target is explicitly excluded |
+| `BLOCKED_EXCLUDED_TARGET` | Target (or a range containing it) is explicitly excluded |
 | `BLOCKED_NOT_IN_SCOPE` | Target doesn't match any authorized scope item |
 | `BLOCKED_DNS_FAILED` | DNS resolution returned no addresses |
+| `BLOCKED_RESTRICTED_IP` | Authorized hostname resolves to loopback/link-local/cloud metadata not listed in `ip_ranges` |
+| `BLOCKED_INVALID_REQUEST` | Tool name or arguments malformed — cannot be validated |
+| `BLOCKED_UNINSPECTABLE_COMMAND` | Free-form command or argument field cannot be reliably scoped |
+| `BLOCKED_INTERNAL_ERROR` | Validation threw unexpectedly — failed closed |
 
 ---
 
@@ -474,9 +607,72 @@ See the [`examples/`](examples/) directory for:
 
 ---
 
+## Manifest Builder
+
+Build scope manifests interactively with smart validation, or share a web form with clients for scope intake.
+
+### Quick Start
+
+```bash
+# Create a new manifest interactively
+integsec-agentic-pentest-manifest new
+
+# Create from a template
+integsec-agentic-pentest-manifest new --from template.json -o scope.json
+
+# Edit an existing manifest
+integsec-agentic-pentest-manifest edit scope.json
+
+# Review a client submission
+integsec-agentic-pentest-manifest review submission.pending.json
+```
+
+### Client Intake (Web Form)
+
+Share a web-based form with clients so they can define their own scope:
+
+```bash
+# Local only (default — localhost:9471)
+integsec-agentic-pentest-manifest serve --template engagement-template.json
+
+# Network-accessible (TLS required)
+integsec-agentic-pentest-manifest serve \
+  --host 0.0.0.0 \
+  --tls-cert ./certs/server.pem \
+  --tls-key ./certs/server-key.pem \
+  --template engagement-template.json
+```
+
+**Workflow:**
+1. Operator creates a template with engagement info, time window, and technique restrictions
+2. Operator runs `serve` and shares the URL with the client
+3. Client fills in their targets (domains, IPs, exclusions) via the web form
+4. Client submits — saved as `.pending.json`
+5. Operator reviews: `integsec-agentic-pentest-manifest review submission.pending.json`
+6. Operator approves, edits, or rejects
+
+**Security:** The web server binds to `127.0.0.1` by default. Exposing on `0.0.0.0` requires `--tls-cert` and `--tls-key` — the server refuses to start over plaintext on non-localhost interfaces.
+
+### Smart Validation
+
+The builder validates your manifest as you build it:
+
+- **Format checks** — valid CIDRs, ISO 8601 dates, non-empty required fields
+- **Live DNS resolution** — resolves domains and shows their IPs
+- **Overlap detection** — warns when domains resolve to IPs already covered by CIDR ranges
+- **Broad range warnings** — flags CIDR ranges wider than /16
+- **Wildcard/apex prompts** — suggests adding `acme.com` when `*.acme.com` is entered
+- **Exclusion checks** — warns if an excluded target isn't within any authorized range
+
+### Dry-Run Preview
+
+Before saving, the builder runs synthetic tool calls against your manifest to preview what the proxy will allow and block. This catches scope misconfigurations before an engagement starts.
+
+---
+
 ## Contributing
 
-Contributions are welcome. The IntegSec Agentic Pentest MCP Proxy is an open-source project under the MIT license.
+Contributions are welcome. The IntegSec Agentic Pentest MCP Proxy is an open-source project under the Apache 2.0 license.
 
 ### Architecture
 
@@ -486,7 +682,7 @@ bin/
 
 src/
   proxy.ts                 ScopeEnforcementProxy — core orchestrator
-  validator.ts             ScopeValidator — 8-step validation pipeline
+  validator.ts             ScopeValidator — validation pipeline
   extractor.ts             Target extraction from tool parameters (19 tools + fallback)
   domain-matcher.ts        Wildcard and exact domain matching
   ip-matcher.ts            CIDR matching, RFC-1918 detection
@@ -514,8 +710,8 @@ src/
 
 ```bash
 # Clone the repo
-git clone https://github.com/integsec/agentic-pentest-mcp-proxy.git
-cd agentic-pentest-mcp-proxy
+git clone https://github.com/IntegSec/agentic-pentest-proxy.git
+cd agentic-pentest-proxy
 
 # Install dependencies
 npm install
@@ -534,7 +730,7 @@ npm run lint
 ```
 
 **Requirements:**
-- Node.js >= 20.0.0
+- Node.js >= 22.0.0
 - npm >= 9
 
 ### Project Structure
@@ -633,7 +829,7 @@ The following is the planned development roadmap for the IntegSec Agentic Pentes
 
 - [ ] **Signed scope manifests** — Ed25519 signatures on manifests to prevent tampering, with key pinning
 - [ ] **Manifest hot-reload** — watch manifest file for changes and reload without restart
-- [ ] **Scope manifest v2 schema** — add per-tool overrides, port ranges, protocol restrictions, and path-level URL scoping
+- [ ] **Scope manifest v2 schema** — add per-tool overrides, port ranges, and protocol restrictions
 - [ ] **Rate limiting** — per-tool and per-target rate limits to prevent runaway agents
 - [ ] **Metrics endpoint** — Prometheus `/metrics` with counters for allowed/blocked decisions, latency histograms
 - [ ] **WebSocket transport** — support MCP over WebSocket for persistent connections
@@ -749,7 +945,7 @@ The following is the planned development roadmap for the IntegSec Agentic Pentes
 
 ## License
 
-MIT License. See [LICENSE](LICENSE) for details.
+Apache 2.0 License. See [LICENSE](LICENSE) for details.
 
 ---
 

package/dist/bin/integsec-agentic-pentest-manifest.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=integsec-agentic-pentest-manifest.d.ts.map

package/dist/bin/integsec-agentic-pentest-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integsec-agentic-pentest-manifest.d.ts","sourceRoot":"","sources":["../../bin/integsec-agentic-pentest-manifest.tsx"],"names":[],"mappings":""}