@integsec/agentic-pentest-proxy 0.1.0

package/README.md

@@ -0,0 +1,731 @@
+# IntegSec Agentic Pentest MCP 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 (Kali MCP, Nuclei MCP, [TurboPentest](https://turbopentest.com), 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.
+
+Built by **[IntegSec](https://integsec.com)** — offensive cybersecurity testing and threat simulation for modern organizations moving at AI speed.
+
+```
+┌──────────┐     JSON-RPC      ┌─────────────────────┐     JSON-RPC      ┌──────────────┐
+│ AI Agent │ ──────────────────▶│ IntegSec Agentic    │ ──────────────────▶│ Upstream MCP │
+│ (Claude) │ ◀──────────────────│ Pentest MCP Proxy   │ ◀──────────────────│  (Kali /     │
+└──────────┘   allow / block    │        audit)       │    forwarded       │ TurboPentest)│
+                                └─────────────────────┘                    └──────────────┘
+                                        │
+                                        ▼
+                                  ┌───────────┐
+                                  │ 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)
+- [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.**
+
+This is the same scope enforcement philosophy behind [IntegSec's](https://integsec.com) human-expert-led penetration testing services — applied to autonomous AI agents.
+
+---
+
+## 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 kali-mcp)
+SCOPE_MANIFEST_PATH=./scope.json \
+UPSTREAM_MCP_COMMAND=npx \
+UPSTREAM_MCP_ARGS="-y,@anthropic/kali-mcp" \
+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,@anthropic/kali-mcp" \
+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": {
+    "kali-mcp-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,@anthropic/kali-mcp",
+        "AUDIT_LOG_PATH": "./audit/"
+      }
+    }
+  }
+}
+```
+
+### Claude Code Integration
+
+Add to your `.mcp.json` or project settings:
+
+```json
+{
+  "mcpServers": {
+    "kali-scoped": {
+      "command": "npx",
+      "args": ["-y", "@integsec/agentic-pentest-proxy"],
+      "env": {
+        "SCOPE_MANIFEST_PATH": "./scope.json",
+        "UPSTREAM_MCP_COMMAND": "npx",
+        "UPSTREAM_MCP_ARGS": "-y,@anthropic/kali-mcp"
+      }
+    }
+  }
+}
+```
+
+### 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
+```
+
+---
+
+## 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
+
+# Run a specific test file
+npx vitest run tests/unit/validator.test.ts
+```
+
+**Test structure:**
+
+```
+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
+```
+
+**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.
+
+### Adding a New Audit Backend
+
+1. Create `src/audit/your-backend.ts` implementing the `AuditBackend` interface:
+   ```typescript
+   export interface AuditBackend {
+     name: string;
+     write(entries: AuditEntry[]): Promise<void>;
+   }
+   ```
+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.
+
+### 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
+
+### Phase 2 — Interception & Manipulation Engine (v0.3)
+
+> Burp Suite-style interception, inspection, and modification of MCP tool calls in real time.
+
+- [ ] **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
+
+### Phase 3 — Terminal UI (v0.4)
+
+> A real-time terminal dashboard for monitoring and controlling the proxy from the command line.
+
+- [ ] **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
+
+### Phase 4 — Web GUI (v0.5)
+
+> Full-featured browser-based interface for teams, with collaboration features.
+
+- [ ] **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
+
+### Phase 5 — Offensive Security MCP Marketplace (v1.0)
+
+> A curated registry of offensive security MCP servers, each with scope enforcement metadata.
+
+- [ ] **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
+
+### Phase 6 — Enterprise & Ecosystem (v1.x)
+
+- [ ] **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
+
+### Future Explorations
+
+- **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
+
+---
+
+## About IntegSec
+
+**[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.
+
+### Our Services
+
+- **[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.
+
+- 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.
+
+---
+
+## 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)