# IntegSec Agentic Pentest Proxy

**Scope enforcement proxy for AI-driven penetration testing.**

The IntegSec Agentic Pentest MCP Proxy sits between an AI agent (Claude, GPT, etc.) and an MCP tool server ([TurboPentest](https://turbopentest.com), Nuclei MCP, etc.), intercepting every tool call and validating it against a scope manifest before it reaches the upstream server. Out-of-scope targets, banned techniques, and expired engagement windows are blocked in real time with a full audit trail.

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   | <---------- | (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)
- [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 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

---

## 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-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"
      }
    }
  }
}
```

### 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
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

# 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

---

## Manifest Builder

Build scope manifests interactively with smart validation, or share a web form with clients for scope intake.

### Quick Start

```bash
# Create a new manifest interactively
integsec-agentic-pentest-manifest new

# Create from a template
integsec-agentic-pentest-manifest new --from template.json -o scope.json

# Edit an existing manifest
integsec-agentic-pentest-manifest edit scope.json

# Review a client submission
integsec-agentic-pentest-manifest review submission.pending.json
```

### Client Intake (Web Form)

Share a web-based form with clients so they can define their own scope:

```bash
# Local only (default — localhost:9471)
integsec-agentic-pentest-manifest serve --template engagement-template.json

# Network-accessible (TLS required)
integsec-agentic-pentest-manifest serve \
  --host 0.0.0.0 \
  --tls-cert ./certs/server.pem \
  --tls-key ./certs/server-key.pem \
  --template engagement-template.json
```

**Workflow:**
1. Operator creates a template with engagement info, time window, and technique restrictions
2. Operator runs `serve` and shares the URL with the client
3. Client fills in their targets (domains, IPs, exclusions) via the web form
4. Client submits — saved as `.pending.json`
5. Operator reviews: `integsec-agentic-pentest-manifest review submission.pending.json`
6. Operator approves, edits, or rejects

**Security:** The web server binds to `127.0.0.1` by default. Exposing on `0.0.0.0` requires `--tls-cert` and `--tls-key` — the server refuses to start over plaintext on non-localhost interfaces.

### Smart Validation

The builder validates your manifest as you build it:

- **Format checks** — valid CIDRs, ISO 8601 dates, non-empty required fields
- **Live DNS resolution** — resolves domains and shows their IPs
- **Overlap detection** — warns when domains resolve to IPs already covered by CIDR ranges
- **Broad range warnings** — flags CIDR ranges wider than /16
- **Wildcard/apex prompts** — suggests adding `acme.com` when `*.acme.com` is entered
- **Exclusion checks** — warns if an excluded target isn't within any authorized range

### Dry-Run Preview

Before saving, the builder runs synthetic tool calls against your manifest to preview what the proxy will allow and block. This catches scope misconfigurations before an engagement starts.

---

## Contributing

Contributions are welcome. The IntegSec Agentic Pentest MCP Proxy is an open-source project under the MIT license.

### 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)