@integsec/agentic-pentest-proxy 0.2.6 → 0.2.8

package/README.md

@@ -1,952 +1,124 @@
 # IntegSec Agentic Pentest Proxy
 
-**Scope enforcement proxy for AI-driven penetration testing.**
+An MCP proxy that checks tool calls against a pentest scope manifest before forwarding them to your MCP tools. It blocks calls it can identify as outside the targets, techniques, or time window you approved, and records decisions in a local audit log.
 
-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.
+**Requires Node.js 22 or newer.** The proxy supports stdio tools, SSE upstreams such as Burp Suite, and HTTP upstreams.
 
-Built by **[IntegSec](https://integsec.com)** — offensive cybersecurity testing and threat simulation for modern organizations moving at AI speed.
+## Quick start: add an MCP tool
 
-```
-+------------+  JSON-RPC   +---------------------+  JSON-RPC   +----------------+
-|  AI Agent  | ----------> | IntegSec Agentic    | ----------> |  Upstream MCP  |
-|  (Claude)  | <---------- | Pentest MCP Proxy   | <---------- | (TurboPentest) |
-+------------+ allow/block | (validate + audit)  |  forwarded  +----------------+
-                           +---------------------+
-                                     |
-                                     v
-                               +-----------+
-                               | Audit Log |
-                               | (JSONL /  |
-                               |  Cloud)   |
-                               +-----------+
-```
-
-> **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)
-  - [Scope Manifest](#scope-manifest)
-  - [Environment Variables](#environment-variables)
-  - [Technique Mappings](#technique-mappings)
-- [Usage](#usage)
-  - [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)
-  - [Project Structure](#project-structure)
-  - [Testing](#testing)
-  - [Adding a New Audit Backend](#adding-a-new-audit-backend)
-  - [Adding Tool Extraction Support](#adding-tool-extraction-support)
-  - [Code Style](#code-style)
-- [Roadmap](#roadmap)
-- [About IntegSec](#about-integsec)
-- [License](#license)
-
----
-
-## Why This Exists
-
-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 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
-
-- **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
-- **DNS caching with TTL** — parallel A+AAAA resolution with in-flight deduplication
-- **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
-- **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
-# Install
-npm install -g @integsec/agentic-pentest-proxy
-
-# Create a scope manifest
-cat > scope.json << 'EOF'
-{
-  "engagement_id": "ENG-2025-0042",
-  "client": "Acme Corp",
-  "operator": "operator@yourfirm.com",
-  "authorized_targets": {
-    "ip_ranges": ["10.10.10.0/24"],
-    "domains": ["*.acme.com"],
-    "urls": [],
-    "cloud_accounts": []
-  },
-  "excluded_targets": ["hr.acme.com"],
-  "authorized_techniques": ["recon", "web_app"],
-  "excluded_techniques": ["dos", "destructive", "social_engineering"],
-  "engagement_window": {
-    "start": "2026-03-27T08:00:00Z",
-    "end": "2026-04-10T17:00:00Z"
-  }
-}
-EOF
-
-# Run the proxy (stdio mode, wrapping TurboPentest MCP)
-SCOPE_MANIFEST_PATH=./scope.json \
-UPSTREAM_MCP_COMMAND=npx \
-UPSTREAM_MCP_ARGS="-y,@turbopentest/mcp-server" \
-integsec-agentic-pentest-proxy
-```
-
-The proxy will intercept all tool calls, validate targets against scope.json, and log decisions to `./audit/`.
-
----
-
-## Installation
-
-### npm (global)
-
-```bash
-npm install -g @integsec/agentic-pentest-proxy
-```
-
-### npm (project-local)
-
-```bash
-npm install @integsec/agentic-pentest-proxy
-```
-
-### From source
-
-```bash
-git clone https://github.com/IntegSec/agentic-pentest-proxy.git
-cd agentic-pentest-proxy
-npm install
-npm run build
-```
-
-### Docker
-
-```bash
-docker build -t integsec-agentic-pentest-proxy .
-docker run --rm \
-  -e SCOPE_MANIFEST_PATH=/scope.json \
-  -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
-```
-
----
-
-## Configuration
-
-### Scope Manifest
-
-The scope manifest defines the boundaries of a penetration testing engagement. It is validated against a strict Zod schema on load.
-
-```jsonc
-{
-  // Unique engagement identifier — used in audit log filenames
-  "engagement_id": "ENG-2025-0142",
-
-  // Client and operator for audit attribution
-  "client": "Acme Corp",
-  "operator": "operator@integsec.com",
-
-  // What the AI agent IS allowed to target
-  "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.
-  // 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"],
-
-  // 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"],
+1. Install the proxy:
 
-  // Tool categories that are always blocked (wins over authorized_techniques)
-  "excluded_techniques": ["dos", "destructive", "social_engineering"],
-
-  // Time window — calls outside this range are blocked
-  "engagement_window": {
-    "start": "2026-03-26T08:00:00Z",
-    "end": "2026-04-09T17:00:00Z"
-  }
-}
-```
-
-**Loading priority:** The proxy checks these sources in order and uses the first one found:
-
-1. `SCOPE_MANIFEST_JSON` — inline JSON in env var
-2. `SCOPE_MANIFEST_PATH` — path to a local JSON file
-3. `SCOPE_MANIFEST_SECRET_ARN` — AWS Secrets Manager
-4. `SCOPE_MANIFEST_KEYVAULT_URI` — Azure Key Vault
-5. `SCOPE_MANIFEST_GCP_SECRET` — GCP Secret Manager
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| **Manifest (one required)** | | |
-| `SCOPE_MANIFEST_PATH` | — | Path to scope manifest JSON file |
-| `SCOPE_MANIFEST_JSON` | — | Inline scope manifest JSON string |
-| `SCOPE_MANIFEST_SECRET_ARN` | — | AWS Secrets Manager ARN |
-| `SCOPE_MANIFEST_KEYVAULT_URI` | — | Azure Key Vault secret URI |
-| `SCOPE_MANIFEST_GCP_SECRET` | — | GCP Secret Manager resource name |
-| **Transport** | | |
-| `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_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_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 |
-| **Tuning** | | |
-| `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.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`, `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
-{
-  "wireless": {
-    "exact": ["aircrack-ng", "wifite", "kismet"],
-    "patterns": ["wifi", "wireless"]
-  },
-  "physical": {
-    "exact": ["lockpick_sim"],
-    "patterns": ["physical"]
-  }
-}
-```
-
-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.
-
----
-
-## Usage
-
-### CLI
-
-```bash
-# stdio mode — wrap any MCP server
-SCOPE_MANIFEST_PATH=./scope.json \
-UPSTREAM_MCP_COMMAND=npx \
-UPSTREAM_MCP_ARGS="-y,@turbopentest/mcp-server" \
-integsec-agentic-pentest-proxy
-
-# HTTP mode — reverse proxy to a running MCP server (listens on 127.0.0.1:9090)
-SCOPE_MANIFEST_PATH=./scope.json \
-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`:
-
-```json
-{
-  "mcpServers": {
-    "turbopentest-scoped": {
-      "command": "npx",
-      "args": ["-y", "@integsec/agentic-pentest-proxy"],
-      "env": {
-        "SCOPE_MANIFEST_PATH": "/path/to/scope.json",
-        "MCP_TRANSPORT": "stdio",
-        "UPSTREAM_MCP_COMMAND": "npx",
-        "UPSTREAM_MCP_ARGS": "-y,@turbopentest/mcp-server",
-        "AUDIT_LOG_PATH": "./audit/"
-      }
-    }
-  }
-}
-```
-
-### Claude Code Integration
-
-Add to your `.mcp.json` or project settings:
-
-```json
-{
-  "mcpServers": {
-    "turbopentest-scoped": {
-      "command": "npx",
-      "args": ["-y", "@integsec/agentic-pentest-proxy"],
-      "env": {
-        "SCOPE_MANIFEST_PATH": "./scope.json",
-        "UPSTREAM_MCP_COMMAND": "npx",
-        "UPSTREAM_MCP_ARGS": "-y,@turbopentest/mcp-server"
-      }
-    }
-  }
-}
-```
-
-### 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 (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=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 \
-  integsec-agentic-pentest-proxy
-
-# With AWS CloudWatch
-docker run --rm \
-  -e SCOPE_MANIFEST_SECRET_ARN=arn:aws:secretsmanager:us-east-1:123456789012:secret:scope \
-  -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
-```
-
----
-
-## TUI Monitor
-
-A real-time terminal dashboard for monitoring proxy decisions as they happen.
-
-```bash
-# Monitor the default audit directory
-integsec-agentic-pentest-tui
-
-# Monitor a specific directory
-integsec-agentic-pentest-tui --audit-path /path/to/audit
-
-# Filter to a specific engagement
-integsec-agentic-pentest-tui --engagement ENG-2026-TEST-001
-```
-
-The TUI displays three panels:
-
-- **Engagement Header** — engagement ID, client, operator
-- **Stats Panel** — running allowed/blocked counts, top targets, top tools
-- **Live Feed** — color-coded scrolling decision feed (green = allowed, red = blocked)
-
-Run the TUI in a separate terminal while the proxy is active (via Claude Desktop, Claude Code, or CLI). It tails the audit JSONL files and updates in real time.
-
----
-
-## How Validation Works
-
-Every `tools/call` JSON-RPC message (including each element of a JSON-RPC batch) passes through this pipeline:
-
-```
-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
-   ▼
-   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
-   ▼
-   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
-   ▼
-7. DNS RESOLUTION ───▶ A + AAAA, falling back to the OS resolver
-   │                    No addresses → BLOCKED_DNS_FAILED
-   ▼
-8. EXCLUSION CHECK ──▶ Host or any resolved IP matches excluded_targets?
-   │                    YES → BLOCKED_EXCLUDED_TARGET
-   ▼
-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
-   ▼
-10. DEFAULT DENY ────▶ BLOCKED_NOT_IN_SCOPE
-```
-
-**Key design decisions:**
-- **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.
-- **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.
-
----
-
-## Audit Logging
-
-Every validation decision produces an audit entry:
-
-```json
-{
-  "timestamp": "2026-03-27T14:32:01.000Z",
-  "engagement_id": "ENG-2025-0142",
-  "client": "Acme Corp",
-  "operator": "operator@integsec.com",
-  "tool_name": "nmap_scan",
-  "tool_parameters": { "target": "10.10.10.5", "flags": "[REDACTED]" },
-  "extracted_target": "10.10.10.5",
-  "resolved_ips": ["10.10.10.5"],
-  "decision": "ALLOWED",
-  "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.2.6"
-}
-```
-
-### Backends
-
-| Backend | Config | Format |
-|---------|--------|--------|
-| **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_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. 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 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 (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 |
-
----
-
-## Examples
-
-See the [`examples/`](examples/) directory for:
-
-- **[`scope-manifest.json`](examples/scope-manifest.json)** — a real-world scope manifest
-- **[`claude-desktop-config.json`](examples/claude-desktop-config.json)** — Claude Desktop integration config
-- **[`technique-map.json`](examples/technique-map.json)** — custom technique category mappings
-
----
-
-## 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 Apache 2.0 license.
-
-### Architecture
-
-```
-bin/
-  integsec-agentic-pentest-proxy.ts  CLI entry point — loads config, manifest, starts transport
-
-src/
-  proxy.ts                 ScopeEnforcementProxy — core orchestrator
-  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
-  dns-resolver.ts          Caching DNS resolver with deduplication
-  technique-checker.ts     Tool → technique category mapping
-  sanitizer.ts             Parameter redaction for audit logs
-  manifest.ts              Manifest loading (file, env, AWS, Azure, GCP)
-  manifest-schema.ts       Zod schema for scope manifest
-  config.ts                Environment variable loader
-  types.ts                 TypeScript type definitions
-
-  audit/
-    index.ts               AuditLogger facade — manages multiple backends
-    local.ts               Local JSONL file logger
-    cloudwatch.ts          AWS CloudWatch backend
-    azure-monitor.ts       Azure Monitor backend
-    gcp-logging.ts         GCP Cloud Logging backend
-
-  transports/
-    stdio.ts               stdio transport — spawns upstream as child process
-    http.ts                HTTP reverse proxy transport
-```
-
-### Development Setup
-
-```bash
-# Clone the repo
-git clone https://github.com/IntegSec/agentic-pentest-proxy.git
-cd agentic-pentest-proxy
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Watch mode (rebuild on change)
-npm run dev
-
-# Type check without emitting
-npm run lint
-```
-
-**Requirements:**
-- Node.js >= 22.0.0
-- npm >= 9
-
-### Project Structure
-
-The codebase follows these principles:
-
-- **Pure TypeScript, ES modules** — no CommonJS, no bundler
-- **Zod for runtime validation** — all external data is schema-validated
-- **Fail-closed security** — when in doubt, block
-- **Isolated backends** — failures in one audit backend never affect others
-- **No classes where functions suffice** — classes only for stateful components (DnsResolver, AuditLogger, ScopeEnforcementProxy)
-- **No external HTTP framework** — uses Node.js built-in `http` module for the HTTP transport
-
-### Testing
-
-Tests use [Vitest](https://vitest.dev/) and are organized into unit and integration suites.
-
-```bash
-# Run all tests
-npm test
+   ```bash
+   npm install -g @integsec/agentic-pentest-proxy
+   ```
 
-# Run tests in watch mode
-npm run test:watch
+2. Create a scope manifest with the guided wizard:
 
-# Run a specific test file
-npx vitest run tests/unit/validator.test.ts
-```
-
-**Test structure:**
+   ```bash
+   integsec-agentic-pentest-manifest new -o scope.json
+   ```
 
-```
-tests/
-  unit/
-    validator.test.ts          Validation pipeline (comprehensive)
-    extractor.test.ts          Target extraction for 19 tools + fallback
-    domain-matcher.test.ts     Domain pattern matching
-    ip-matcher.test.ts         CIDR and private IP detection
-    dns-resolver.test.ts       DNS caching and deduplication
-    manifest-schema.test.ts    Scope manifest schema validation
-    manifest.test.ts           Manifest loading from all sources
-    technique-checker.test.ts  Technique categorization
-    sanitizer.test.ts          Parameter redaction
-    audit-local.test.ts        Local audit file writing
-    smoke.test.ts              Module import sanity check
-  integration/
-    proxy.test.ts              Full message flow through proxy
-  fixtures/
-    scope-valid.json           Valid scope manifest
-    scope-expired.json         Expired scope manifest
-    tool-calls.json            Sample JSON-RPC messages
-```
+   Set the real engagement targets and time window. Review the generated file with the engagement owner before using it.
 
-**Writing tests:**
-- Every new module should have a corresponding test file in `tests/unit/`
-- Use the fixtures in `tests/fixtures/` for scope manifests and tool call payloads
-- Mock DNS and cloud SDKs in unit tests; integration tests use the full proxy
-- Aim for edge cases: invalid inputs, boundary conditions, Unicode domains, IPv6, etc.
+3. Generate a client entry for **each** MCP tool. Put the tool's normal launch command after `--`:
 
-### Adding a New Audit Backend
+   ```bash
+   integsec-agentic-pentest-setup --name scanner-scoped --manifest ./scope.json -- npx -y @example/scanner-mcp
+   ```
 
-1. Create `src/audit/your-backend.ts` implementing the `AuditBackend` interface:
-   ```typescript
-   export interface AuditBackend {
-     name: string;
-     write(entries: AuditEntry[]): Promise<void>;
+   Replace `npx -y @example/scanner-mcp` with the command from your tool's own setup instructions. The command prints an `mcpServers` entry. Paste that entry into your MCP client's configuration and restart the client. To add another tool, run setup again with a new `--name`, then add its entry under the same `mcpServers` object.
+
+   For example, the generated entry has this shape (the setup command fills in your actual manifest and audit paths):
+
+   ```json
+   {
+     "mcpServers": {
+       "scanner-scoped": {
+         "command": "integsec-agentic-pentest-proxy",
+         "env": {
+           "SCOPE_MANIFEST_PATH": "/path/to/scope.json",
+           "MCP_TRANSPORT": "stdio",
+           "AUDIT_LOG_PATH": "/path/to/audit",
+           "UPSTREAM_MCP_COMMAND": "npx",
+           "UPSTREAM_MCP_ARGS_JSON": "[\"-y\",\"@example/scanner-mcp\"]"
+         }
+       }
+     }
    }
    ```
-2. Add it to the AuditLogger in `bin/integsec-agentic-pentest-proxy.ts` when the relevant env vars are set.
-3. Add a unit test in `tests/unit/audit-your-backend.test.ts`.
-4. Document the env vars in this README and `.env.example`.
-
-### Adding Tool Extraction Support
-
-To add target extraction for a new tool, edit `src/extractor.ts`:
-
-1. Add the tool name to the `TOOL_MAPPINGS` array with its target parameter name(s).
-2. If the tool uses a non-standard parameter format, add a case to the extraction logic.
-3. Add test cases in `tests/unit/extractor.test.ts`.
-
-### Code Style
-
-- TypeScript strict mode
-- No `any` types — use `unknown` and narrow
-- Explicit return types on exported functions
-- No default exports — use named exports
-- Keep functions small and focused
-- Security-sensitive code gets extra test coverage
-
----
 
-## Roadmap
+   Use the `mcpServers` block in Claude Desktop's MCP configuration or in your Claude Code project's `.mcp.json`. Other MCP clients may label the server settings differently; use the generated command and environment variables in their equivalent fields. The proxy starts when the client launches the tool.
 
-The following is the planned development roadmap for the IntegSec Agentic Pentest MCP Proxy. Items are grouped by phase and roughly ordered by priority within each phase.
+4. Watch decisions in another terminal:
 
-### Phase 1 — Core Hardening (v0.2)
-
-- [ ] **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, 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
-- [ ] **Plugin system for validators** — allow custom validation steps via a plugin interface
-
-### Phase 2 — Interception & Manipulation Engine (v0.3)
-
-> Burp Suite-style interception, inspection, and modification of MCP tool calls in real time.
+   ```bash
+   integsec-agentic-pentest-tui --audit-path ./audit
+   ```
 
-- [ ] **Intercept mode** — pause tool calls before forwarding, allowing human review and approval
-- [ ] **Request modification** — edit tool parameters before forwarding (e.g., add `--safe-mode` flags, restrict scan intensity)
-- [ ] **Response modification** — filter or transform upstream responses before they reach the AI agent
-- [ ] **Replay engine** — capture and replay tool call sequences for testing and training
-- [ ] **Match & replace rules** — regex-based rules to automatically rewrite parameters (e.g., replace hostnames, inject headers)
-- [ ] **Breakpoints** — conditional breakpoints on tool name, target, technique, or parameter patterns
-- [ ] **Interception history** — searchable log of all intercepted, modified, forwarded, and dropped messages
-- [ ] **Scope diff viewer** — visual diff showing what the agent requested vs. what was actually forwarded
-- [ ] **Redirection engine** — reroute tool calls to alternative targets (e.g., redirect production targets to staging, honeypots, or simulation environments)
-- [ ] **Upstream multiplexing** — forward a single tool call to multiple upstream servers simultaneously for comparison or redundancy
+   Setup prints the exact audit path to use. If your shell is in another directory, use that printed path. For a one-off TUI without a global install:
 
-### Phase 3 — Terminal UI (v0.4)
+   ```bash
+   npm exec --yes --package=@integsec/agentic-pentest-proxy -- integsec-agentic-pentest-tui --audit-path ./audit
+   ```
 
-> A real-time terminal dashboard for monitoring and controlling the proxy from the command line.
+   The TUI reads local audit files; it does not start the proxy. [See TUI screenshots](docs/tui.md).
 
-- [ ] **Live decision feed** — streaming view of ALLOWED/BLOCKED decisions as they happen
-- [ ] **Scope summary panel** — display active engagement info, authorized targets, and time window countdown
-- [ ] **Audit log viewer** — browse and filter audit entries with keyboard navigation
-- [ ] **Intercept queue** — review, approve, modify, or drop pending intercepted tool calls from the TUI
-- [ ] **Target heatmap** — ASCII visualization of which targets are being hit and how often
-- [ ] **Technique breakdown** — live stats on tool categories being used
-- [ ] **Session management** — start, pause, resume, and terminate proxy sessions
-- [ ] **Keyboard shortcuts** — vim-style bindings for rapid navigation
-- [ ] **Multi-pane layout** — configurable split views (decisions + audit + intercept queue)
-- [ ] **Dark/light themes** — because terminal aesthetics matter
+   ![Fictional TUI session showing allowed and blocked MCP calls](docs/images/tui-out-of-scope.png)
 
-### Phase 4 — Web GUI (v0.5)
+## Other MCP tool types
 
-> Full-featured browser-based interface for teams, with collaboration features.
+| Tool connection | What to do |
+| --- | --- |
+| **stdio** tool launched by a command | Use the setup command above with `-- <command> [args...]`. |
+| **SSE** upstream already listening, such as Burp Suite | Use `integsec-agentic-pentest-setup --name burp-scoped --manifest ./scope.json --sse http://127.0.0.1:9876`. |
+| **HTTP** upstream | Run the proxy as an HTTP service and point your MCP client at it. [HTTP and Docker guide](docs/integrations.md#http-and-docker). |
 
-- [ ] **Dashboard** — real-time overview of active engagements, decision rates, and alerts
-- [ ] **Scope manifest editor** — visual editor with validation, preview, and version history
-- [ ] **Audit explorer** — filterable, sortable table of all audit entries with export (CSV, JSON)
-- [ ] **Intercept workspace** — browser-based intercept, modify, and forward interface with syntax highlighting
-- [ ] **Request/response inspector** — detailed view of tool call parameters, extracted targets, DNS results, and validation steps
-- [ ] **Engagement timeline** — chronological visualization of all tool calls with scope boundary overlay
-- [ ] **Team collaboration** — multi-user access with role-based permissions (operator, reviewer, read-only)
-- [ ] **Engagement management** — create, clone, archive, and compare scope manifests across engagements
-- [ ] **Alert rules** — configurable notifications (email, Slack, webhook) on scope violations or anomalous patterns
-- [ ] **Report generation** — exportable engagement summary with decision statistics, target coverage, and compliance evidence
-- [ ] **API** — REST/GraphQL API for programmatic access to all GUI features
+Use one generated client entry per upstream tool. A single scope manifest can be shared by several entries; each call still gets checked. [More client examples](docs/integrations.md).
 
-### Phase 5 — Offensive Security MCP Marketplace (v1.0)
+## What gets checked
 
-> A curated registry of offensive security MCP servers, each with scope enforcement metadata.
+The proxy checks MCP `tools/call` arguments it can inspect. It blocks unknown target-bearing arguments, out-of-scope targets, explicit exclusions, restricted techniques, expired engagement windows, and free-form commands by default. DNS names authorized through IP ranges must resolve entirely inside the allowed ranges. Local JSONL auditing is always on; cloud logging is optional.
 
-- [ ] **Server registry** — searchable catalog of offensive security MCP servers (recon, exploitation, post-exploitation, reporting)
-- [ ] **Scope profiles** — each server publishes a scope profile declaring what targets/techniques it can affect
-- [ ] **One-click install** — install and configure MCP servers with automatic scope proxy wrapping
-- [ ] **Compatibility matrix** — which servers work with which AI agents (Claude, GPT, local LLMs)
-- [ ] **Community submissions** — submit and review MCP servers with quality ratings and security audits
-- [ ] **Technique taxonomy** — standardized technique categories (aligned with MITRE ATT&CK) for cross-server filtering
-- [ ] **Composite workflows** — chain multiple MCP servers into multi-stage attack workflows with per-stage scope constraints
-- [ ] **Sandboxed preview** — try MCP servers against a built-in vulnerable target before deploying
-- [ ] **License and compliance metadata** — track licensing, data handling, and compliance requirements per server
-- [ ] **Version management** — pin server versions, get update notifications, and review changelogs
+The proxy cannot control destinations selected inside an upstream tool, HTTP redirects, targets read from files or encoded payloads, DNS changes after validation, or traffic that bypasses MCP. Use network egress controls and review each upstream tool's schema before relying on the proxy for an engagement. [Security model](docs/security.md).
 
-### Phase 6 — Enterprise & Ecosystem (v1.x)
+## Install and release options
 
-- [ ] **SSO/OIDC integration** — enterprise authentication for the GUI and API
-- [ ] **Centralized policy server** — manage scope manifests across multiple proxies from a single control plane
-- [ ] **SIEM integration** — forward audit logs to Splunk, Elastic, Sentinel, etc.
-- [ ] **Compliance reporting** — automated reports for PCI-DSS, SOC 2, ISO 27001, and CREST engagement evidence
-- [ ] **Agent behavior analytics** — ML-based detection of anomalous agent behavior (target drift, technique escalation)
-- [ ] **Multi-agent support** — scope enforcement across multiple concurrent AI agents with shared state
-- [ ] **Engagement templates** — pre-built scope manifests for common engagement types (web app, internal network, cloud, API)
-- [ ] **SDK / library mode** — import scope validation as a library into custom agent frameworks without running a proxy
-- [ ] **CI/CD integration** — validate scope manifests in CI pipelines, run automated scope compliance checks
+| Option | Command or image |
+| --- | --- |
+| Global npm install | `npm install -g @integsec/agentic-pentest-proxy` |
+| Project install | `npm install @integsec/agentic-pentest-proxy` |
+| GHCR image | `ghcr.io/integsec/agentic-pentest-proxy:latest` |
+| Docker Hub image | `integsec/agentic-pentest-mcp-proxy:latest` |
 
-### Future Explorations
+The npm package includes the proxy, manifest builder, setup helper, and TUI executables. To see the optional install welcome banner, add `--foreground-scripts`; npm hides package install-script output by default. You can always run `integsec-agentic-pentest-proxy --help` for the same next steps. The welcome script does not access the network or modify files.
 
-- **MCP-native protocol extensions** — propose scope enforcement as a first-class MCP protocol feature
-- **Hardware security module (HSM) support** — store manifest signing keys in HSMs
-- **Air-gapped mode** — offline operation with pre-loaded manifests and local-only audit
-- **Agent scoring** — track per-agent compliance rates and generate trust scores over time
+Google Cloud logging and Secret Manager SDKs are opt-in to keep the default install lean and free of their deprecated transitive package. If you use either GCP backend, install the SDKs alongside the proxy:
 
----
+```bash
+npm install -g @integsec/agentic-pentest-proxy @google-cloud/logging @google-cloud/secret-manager
+```
 
-## About IntegSec
+AWS and Azure SDKs are included as optional dependencies. See [configuration and cloud setup](docs/configuration.md) for the required environment variables and Docker notes.
+If you use GCP and are upgrading from 0.2.6, install the GCP SDKs before restarting the proxy; it now reports a missing Cloud Logging SDK at startup.
 
-**[IntegSec](https://integsec.com)** delivers human-expert-led agentic penetration testing for modern organizations moving at AI speed. We combine seasoned offensive security professionals with autonomous AI agents to find real vulnerabilities — not just scan results.
+## Troubleshooting
 
-### Our Services
+| Symptom | Check |
+| --- | --- |
+| Tool does not appear in your MCP client | Paste the generated entry inside one `mcpServers` object, restart the client, and confirm the client can run `integsec-agentic-pentest-proxy`. |
+| TUI shows no decisions | Start a tool call, then use the exact audit path printed by setup. The TUI and client may have different working directories. |
+| Call is blocked | Check the decision and reason in the TUI or audit JSONL. Confirm the target, exclusions, technique, and window in your manifest. |
+| GCP backend says its SDK is missing | Install the two GCP packages shown above alongside the proxy. |
+| Need all CLI options | Run `integsec-agentic-pentest-proxy --help`, `integsec-agentic-pentest-setup --help`, `integsec-agentic-pentest-manifest --help`, or `integsec-agentic-pentest-tui --help`. |
 
-- **[Pentest as a Service (PTaaS)](https://integsec.com/become-unbreachable)** — continuous human-led penetration testing for web apps, networks, APIs, and cloud environments
-- **[Adversary Simulation & Red Teaming](https://integsec.com/redteaming)** — real-world attack simulations to evaluate your security posture
-- **LLM Red Teaming** — security testing for AI/LLM applications
-- **OWASP Reviews** — structured assessments aligned with OWASP Testing Guides
-- **Offensive Cybersecurity Training** — level up your team's security skills
-
-### TurboPentest
-
-**[TurboPentest](https://turbopentest.com)** is our agentic penetration testing platform. Paladin AI agents powered by Claude orchestrate 15 professional security tools — Nmap, OWASP ZAP, Nuclei, Nikto, Subfinder, FFUF, OpenVAS, Semgrep, and more — to deliver comprehensive security assessments in under 4 hours.
+## Reference
 
-- OWASP Top 10 coverage with validated exploits, not just potential findings
-- Black box and white box testing with GitHub integration
-- Blockchain-attested reports (SHA-256 hashed, anchored to Base L2)
-- CI/CD, VS Code, and Burp Suite Pro integrations
-- **Starting at $99/domain** — [try it now](https://turbopentest.com)
-
-> **Need human expertise + AI speed?** [Contact IntegSec](https://integsec.com) for expert-led pentesting backed by the same AI agents that power TurboPentest.
-
----
+- [Configuration and manifest fields](docs/configuration.md)
+- [Client integrations, HTTP, and Docker](docs/integrations.md)
+- [TUI usage and screenshots](docs/tui.md)
+- [Security model and limitations](docs/security.md)
+- [Contributing and development](docs/development.md)
 
 ## License
 
-Apache 2.0 License. See [LICENSE](LICENSE) for details.
-
----
-
-Built by **[IntegSec](https://integsec.com)** | **[TurboPentest](https://turbopentest.com)** | [GitHub](https://github.com/integsec) | [Twitter](https://x.com/integ_sec)
+Apache-2.0. See [LICENSE](LICENSE).