@integsec/agentic-pentest-proxy 0.2.5 → 0.2.7

package/README.md

@@ -1,756 +1,124 @@
-# IntegSec Agentic Pentest MCP Proxy
+# 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.), 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.
+**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. Pair it with this proxy for scope-safe autonomous testing.
-
----
-
-## Table of Contents
-
-- [Why This Exists](#why-this-exists)
-- [Features](#features)
-- [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)
-  - [Docker](#docker)
-  - [HTTP Mode](#http-mode)
-- [TUI Monitor](#tui-monitor)
-- [How Validation Works](#how-validation-works)
-- [Audit Logging](#audit-logging)
-- [Examples](#examples)
-- [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 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.
-
-**No prompt engineering. No honor system. Enforcement.**
-
-
----
-
-## 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
-- **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
-- **Two transport modes** — stdio (child process) 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
-
----
-
-## 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-mcp-proxy.git
-cd agentic-pentest-mcp-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=sse \
-  -e UPSTREAM_MCP_URL=http://host.docker.internal:8080 \
-  -e PROXY_PORT=9090 \
-  -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"],
-    "urls": ["https://app.acme.com", "https://api.acme.com"],
-    "cloud_accounts": ["aws:123456789012"]
-  },
-
-  // Override: these are NEVER allowed even if they match above
-  "excluded_targets": ["203.0.113.5", "hr.acme.com"],
-
-  // Technique categories (for reference / future enforcement)
-  "authorized_techniques": ["recon", "web_app", "api_testing"],
-
-  // Tool categories that are always blocked
-  "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` | Transport mode: `stdio` or `sse` |
-| `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) |
-| **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_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.1.0` | 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:
-
-```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.
-
----
-
-## 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
-SCOPE_MANIFEST_PATH=./scope.json \
-MCP_TRANSPORT=sse \
-UPSTREAM_MCP_URL=http://localhost:8080 \
-PROXY_PORT=9090 \
-integsec-agentic-pentest-proxy
-```
-
-### 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"
-      }
-    }
-  }
-}
-```
-
-### Docker
-
-```bash
-# HTTP mode
-docker run --rm \
-  -e SCOPE_MANIFEST_PATH=/scope.json \
-  -e MCP_TRANSPORT=sse \
-  -e UPSTREAM_MCP_URL=http://host.docker.internal:8080 \
-  -e PROXY_PORT=9090 \
-  -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=sse \
-  -e UPSTREAM_MCP_URL=http://host.docker.internal:8080 \
-  -e AWS_LOG_GROUP=/integsec/mcp-proxy \
-  -e AWS_REGION=us-east-1 \
-  -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
+1. Install the proxy:
 
-# 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 passes through an 8-step validation pipeline:
-
-```
-1. TECHNIQUE CHECK ──▶ Is the tool in an excluded_techniques category?
-   │                    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)
-   ▼
-4. NO TARGET? ───────▶ No target-like parameter found?
-   │                    YES → ALLOWED_NO_TARGET
-   ▼
-5. DNS RESOLUTION ───▶ Resolve hostname to A + AAAA records
-   │                    NXDOMAIN → BLOCKED_DNS_FAILED
-   ▼
-6. EXCLUSION CHECK ──▶ Does target match excluded_targets?
-   │                    YES → BLOCKED_EXCLUDED_TARGET
-   ▼
-7. AUTHORIZATION ────▶ Does target match authorized_targets?
-   │                    YES → ALLOWED
-   ▼
-8. 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.
-- **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.
-
----
-
-## 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.1.0"
-}
-```
-
-### 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_WORKSPACE_ID` + `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.
-
-### 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 |
-| `BLOCKED_OUTSIDE_WINDOW` | Current time is outside the engagement window |
-| `BLOCKED_EXCLUDED_TARGET` | Target is explicitly excluded |
-| `BLOCKED_NOT_IN_SCOPE` | Target doesn't match any authorized scope item |
-| `BLOCKED_DNS_FAILED` | DNS resolution returned no addresses |
-
----
-
-## 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
-
----
-
-## Contributing
-
-Contributions are welcome. The IntegSec Agentic Pentest MCP Proxy is an open-source project under the MIT 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 — 8-step 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-mcp-proxy.git
-cd agentic-pentest-mcp-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 >= 20.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
-
-# Run tests in watch mode
-npm run test:watch
+   ```bash
+   npm install -g @integsec/agentic-pentest-proxy
+   ```
 
-# Run a specific test file
-npx vitest run tests/unit/validator.test.ts
-```
+2. Create a scope manifest with the guided wizard:
 
-**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
 
-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.
+   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.
 
-### 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, protocol restrictions, and path-level URL scoping
-- [ ] **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
+4. Watch decisions in another terminal:
 
-### 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
 
-MIT 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).