@integsec/agentic-pentest-proxy 0.3.3 → 0.3.5

package/docs/superpowers/plans/2026-03-26-mcp-scope-proxy.md

@@ -0,0 +1,3051 @@
+# MCP Scope Enforcement Proxy — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a production-grade MCP middleware proxy that intercepts AI agent tool calls, validates targets against a pentest engagement scope manifest, blocks out-of-scope calls, and produces a full audit trail to local files and cloud logging (AWS/Azure/GCP).
+
+**Architecture:** The proxy sits between an AI agent and upstream MCP servers. It intercepts `tools/call` JSON-RPC messages, extracts targets from tool parameters, validates them against an in-memory scope manifest (IP/CIDR, domain, URL, technique, time window checks), and either forwards allowed calls or returns MCP error responses for blocked calls. Every decision is audit-logged.
+
+**Tech Stack:** TypeScript, Node.js 20+, `@modelcontextprotocol/sdk`, `zod` for validation, `vitest` for testing, `ip-cidr`/`netmask` for CIDR matching, `dns/promises` (stdlib) for resolution, cloud SDKs (`@aws-sdk/client-cloudwatch-logs`, `@azure/monitor-ingestion`, `@google-cloud/logging`) as optional peer dependencies.
+
+---
+
+## File Structure
+
+```
+mcp-scope-proxy/
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+├── Dockerfile
+├── .env.example
+├── .gitignore
+├── bin/
+│   └── mcp-scope-proxy.ts          # CLI entry point (hashbang, arg parsing)
+├── src/
+│   ├── index.ts                     # Public API exports
+│   ├── proxy.ts                     # Core proxy: intercepts tools/call, delegates to validator
+│   ├── manifest.ts                  # Scope manifest loading (file, env, cloud secrets)
+│   ├── manifest-schema.ts           # Zod schema for scope manifest
+│   ├── validator.ts                 # Scope validation engine (orchestrates all checks)
+│   ├── extractor.ts                 # Target extraction from tool parameters
+│   ├── dns-resolver.ts              # DNS resolution with TTL-aware caching
+│   ├── ip-matcher.ts                # IP/CIDR matching utilities
+│   ├── domain-matcher.ts            # Domain/wildcard matching utilities
+│   ├── technique-checker.ts         # Technique category blocking
+│   ├── sanitizer.ts                 # Parameter sanitization for audit logs
+│   ├── config.ts                    # Environment variable parsing with defaults
+│   ├── types.ts                     # Shared TypeScript types and interfaces
+│   ├── audit/
+│   │   ├── index.ts                 # AuditLogger facade (dispatches to backends)
+│   │   ├── local.ts                 # Local JSONL file writer
+│   │   ├── cloudwatch.ts            # AWS CloudWatch Logs integration
+│   │   ├── azure-monitor.ts         # Azure Monitor/Log Analytics integration
+│   │   └── gcp-logging.ts           # GCP Cloud Logging integration
+│   └── transports/
+│       ├── stdio.ts                 # stdio transport proxy
+│       └── http.ts                  # Streamable HTTP transport proxy
+├── tests/
+│   ├── unit/
+│   │   ├── validator.test.ts
+│   │   ├── extractor.test.ts
+│   │   ├── dns-resolver.test.ts
+│   │   ├── ip-matcher.test.ts
+│   │   ├── domain-matcher.test.ts
+│   │   ├── technique-checker.test.ts
+│   │   ├── sanitizer.test.ts
+│   │   ├── manifest.test.ts
+│   │   └── audit-local.test.ts
+│   ├── integration/
+│   │   └── proxy.test.ts
+│   └── fixtures/
+│       ├── scope-valid.json
+│       ├── scope-expired.json
+│       └── tool-calls.json
+├── examples/
+│   ├── scope-manifest.json
+│   ├── technique-map.json
+│   └── claude-desktop-config.json
+└── scripts/
+    └── test-proxy.ts                # Manual integration test script
+```
+
+### File Responsibilities
+
+| File | Responsibility |
+|------|---------------|
+| `bin/mcp-scope-proxy.ts` | CLI entry: parse args, load config, start proxy |
+| `src/proxy.ts` | Core proxy loop: receive MCP messages, intercept `tools/call`, delegate validation, forward or block |
+| `src/manifest.ts` | Load scope manifest from file/env/AWS/Azure/GCP, parse and validate with Zod |
+| `src/manifest-schema.ts` | Zod schema definition for the scope manifest JSON |
+| `src/validator.ts` | Orchestrate validation: technique check → time window → extract target → exclusion → authorization |
+| `src/extractor.ts` | Extract target (IP/hostname/URL) from tool call parameters using tool-specific and fallback rules |
+| `src/dns-resolver.ts` | Resolve hostnames to IPs (A+AAAA), cache with TTL, fail closed on error |
+| `src/ip-matcher.ts` | Check if an IP is within CIDR ranges, detect RFC-1918/metadata IPs |
+| `src/domain-matcher.ts` | Wildcard domain matching (`*.acme.com`), exact match, case-insensitive |
+| `src/technique-checker.ts` | Map tool names to technique categories, check against blocked list |
+| `src/sanitizer.ts` | Redact sensitive parameter values (passwords, tokens, keys) before logging |
+| `src/config.ts` | Read all env vars, apply defaults, validate required config |
+| `src/types.ts` | TypeScript interfaces: `ScopeManifest`, `AuditEntry`, `ValidationResult`, `Decision` |
+| `src/audit/index.ts` | Facade: dispatch audit entries to all configured backends |
+| `src/audit/local.ts` | Append JSONL to local file per engagement |
+| `src/audit/cloudwatch.ts` | Batch + flush to AWS CloudWatch Logs |
+| `src/audit/azure-monitor.ts` | Batch + flush to Azure Monitor via DCR |
+| `src/audit/gcp-logging.ts` | Batch + flush to GCP Cloud Logging |
+| `src/transports/stdio.ts` | Proxy MCP over stdio (spawn upstream as subprocess or connect via pipe) |
+| `src/transports/http.ts` | Proxy MCP over Streamable HTTP (listen on PROXY_PORT, forward to UPSTREAM_MCP_URL) |
+
+---
+
+## Task 1: Project Scaffolding
+
+**Files:**
+- Create: `package.json`
+- Create: `tsconfig.json`
+- Create: `vitest.config.ts`
+- Create: `.gitignore`
+- Create: `.env.example`
+
+- [ ] **Step 1: Create package.json**
+
+```json
+{
+  "name": "mcp-scope-proxy",
+  "version": "0.1.0",
+  "description": "MCP Scope Enforcement Proxy — enforce penetration testing engagement scope for AI agents",
+  "type": "module",
+  "bin": {
+    "mcp-scope-proxy": "./dist/bin/mcp-scope-proxy.js"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "start": "node dist/bin/mcp-scope-proxy.js"
+  },
+  "keywords": ["mcp", "proxy", "pentest", "scope-enforcement", "audit", "ai-agent"],
+  "author": "IntegSec",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0",
+    "ip-cidr": "^4.0.1",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "@aws-sdk/client-cloudwatch-logs": "^3.700.0",
+    "@azure/monitor-ingestion": "^1.1.0",
+    "@azure/identity": "^4.5.0",
+    "@google-cloud/logging": "^11.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}
+```
+
+- [ ] **Step 2: Create tsconfig.json**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*", "bin/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+- [ ] **Step 3: Create vitest.config.ts**
+
+```typescript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ["tests/**/*.test.ts"],
+  },
+});
+```
+
+- [ ] **Step 4: Create .gitignore**
+
+```
+node_modules/
+dist/
+.env
+audit/
+*.jsonl
+.DS_Store
+```
+
+- [ ] **Step 5: Create .env.example**
+
+```bash
+# Required — scope manifest source (use ONE)
+SCOPE_MANIFEST_PATH=./scope.json
+# SCOPE_MANIFEST_JSON='{"engagement_id":"..."}'
+# SCOPE_MANIFEST_SECRET_ARN=arn:aws:secretsmanager:us-east-1:123456789012:secret:scope
+# SCOPE_MANIFEST_KEYVAULT_URI=https://vault.azure.net/secrets/scope/latest
+# SCOPE_MANIFEST_GCP_SECRET=projects/123/secrets/scope/versions/latest
+
+# Transport
+MCP_TRANSPORT=stdio
+# UPSTREAM_MCP_URL=http://localhost:8080
+# UPSTREAM_MCP_COMMAND=npx
+# UPSTREAM_MCP_ARGS=-y,@anthropic/kali-mcp
+# PROXY_PORT=9090
+
+# Audit logging
+AUDIT_LOG_PATH=./audit/
+
+# AWS CloudWatch (optional)
+# AWS_LOG_GROUP=/integsec/mcp-proxy
+# AWS_REGION=us-east-1
+
+# Azure Monitor (optional)
+# AZURE_LOG_WORKSPACE_ID=...
+# AZURE_DCR_IMMUTABLE_ID=...
+# AZURE_DCR_STREAM_NAME=Custom-MCPProxyAudit_CL
+
+# GCP Cloud Logging (optional)
+# GOOGLE_CLOUD_PROJECT=my-project
+
+# Optional
+# TECHNIQUE_MAP_PATH=./technique_map.json
+# DNS_CACHE_TTL=60
+# LOG_LEVEL=INFO
+```
+
+- [ ] **Step 6: Install dependencies**
+
+Run: `npm install`
+Expected: `node_modules/` created, lockfile generated.
+
+- [ ] **Step 7: Verify build toolchain**
+
+Create `src/index.ts` with placeholder:
+```typescript
+export const VERSION = "0.1.0";
+```
+
+Run: `npx tsc --noEmit`
+Expected: No errors.
+
+- [ ] **Step 8: Verify test toolchain**
+
+Create `tests/unit/smoke.test.ts`:
+```typescript
+import { describe, it, expect } from "vitest";
+import { VERSION } from "../../src/index.js";
+
+describe("smoke test", () => {
+  it("exports version", () => {
+    expect(VERSION).toBe("0.1.0");
+  });
+});
+```
+
+Run: `npx vitest run`
+Expected: 1 test passes.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add -A
+git commit -m "chore: scaffold project with TypeScript, vitest, and dependencies"
+```
+
+---
+
+## Task 2: Types and Manifest Schema
+
+**Files:**
+- Create: `src/types.ts`
+- Create: `src/manifest-schema.ts`
+- Test: `tests/unit/manifest.test.ts` (schema validation portion)
+
+- [ ] **Step 1: Write failing tests for manifest schema**
+
+Create `tests/unit/manifest-schema.test.ts`:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { ScopeManifestSchema } from "../../src/manifest-schema.js";
+
+describe("ScopeManifestSchema", () => {
+  const validManifest = {
+    engagement_id: "ENG-2025-0142",
+    client: "Acme Corp",
+    operator: "operator@integsec.com",
+    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", "azure:sub-xxxx"],
+    },
+    excluded_targets: ["203.0.113.5", "hr.acme.com"],
+    authorized_techniques: ["recon", "web_app", "api_testing"],
+    excluded_techniques: ["dos", "destructive", "social_engineering"],
+    engagement_window: {
+      start: "2026-03-26T08:00:00Z",
+      end: "2026-04-09T17:00:00Z",
+    },
+  };
+
+  it("parses a valid manifest", () => {
+    const result = ScopeManifestSchema.safeParse(validManifest);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects manifest missing engagement_id", () => {
+    const { engagement_id, ...rest } = validManifest;
+    const result = ScopeManifestSchema.safeParse(rest);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects manifest with invalid engagement_window dates", () => {
+    const bad = { ...validManifest, engagement_window: { start: "not-a-date", end: "also-bad" } };
+    const result = ScopeManifestSchema.safeParse(bad);
+    expect(result.success).toBe(false);
+  });
+
+  it("allows empty optional arrays", () => {
+    const minimal = {
+      engagement_id: "ENG-001",
+      client: "Test",
+      operator: "test@test.com",
+      authorized_targets: {
+        ip_ranges: [],
+        domains: [],
+        urls: [],
+        cloud_accounts: [],
+      },
+      excluded_targets: [],
+      authorized_techniques: [],
+      excluded_techniques: [],
+      engagement_window: {
+        start: "2026-01-01T00:00:00Z",
+        end: "2026-12-31T23:59:59Z",
+      },
+    };
+    const result = ScopeManifestSchema.safeParse(minimal);
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/manifest-schema.test.ts`
+Expected: FAIL — cannot find module `../../src/manifest-schema.js`
+
+- [ ] **Step 3: Implement types.ts**
+
+Create `src/types.ts`:
+
+```typescript
+export type Decision =
+  | "ALLOWED"
+  | "BLOCKED_EXCLUDED_TARGET"
+  | "BLOCKED_NOT_IN_SCOPE"
+  | "BLOCKED_OUTSIDE_WINDOW"
+  | "BLOCKED_TECHNIQUE"
+  | "BLOCKED_DNS_FAILED"
+  | "ALLOWED_NO_TARGET";
+
+export interface ValidationResult {
+  decision: Decision;
+  reason: string;
+  matchedScopeItem?: string;
+  extractedTarget?: string;
+  resolvedIps?: string[];
+  durationMs: number;
+}
+
+export interface AuditEntry {
+  timestamp: string;
+  engagement_id: string;
+  client: string;
+  operator: string;
+  tool_name: string;
+  tool_parameters: Record<string, unknown>;
+  extracted_target: string | null;
+  resolved_ips: string[];
+  decision: Decision;
+  decision_reason: string;
+  matched_scope_item: string | null;
+  duration_ms: number;
+  proxy_version: string;
+}
+
+export interface ScopeManifest {
+  engagement_id: string;
+  client: string;
+  operator: string;
+  authorized_targets: {
+    ip_ranges: string[];
+    domains: string[];
+    urls: string[];
+    cloud_accounts: string[];
+  };
+  excluded_targets: string[];
+  authorized_techniques: string[];
+  excluded_techniques: string[];
+  engagement_window: {
+    start: string;
+    end: string;
+  };
+}
+```
+
+- [ ] **Step 4: Implement manifest-schema.ts**
+
+Create `src/manifest-schema.ts`:
+
+```typescript
+import { z } from "zod";
+
+const isoDateString = z.string().refine(
+  (val) => !isNaN(Date.parse(val)),
+  { message: "Must be a valid ISO 8601 date string" }
+);
+
+export const ScopeManifestSchema = z.object({
+  engagement_id: z.string().min(1),
+  client: z.string().min(1),
+  operator: z.string().min(1),
+  authorized_targets: z.object({
+    ip_ranges: z.array(z.string()),
+    domains: z.array(z.string()),
+    urls: z.array(z.string()),
+    cloud_accounts: z.array(z.string()),
+  }),
+  excluded_targets: z.array(z.string()),
+  authorized_techniques: z.array(z.string()),
+  excluded_techniques: z.array(z.string()),
+  engagement_window: z.object({
+    start: isoDateString,
+    end: isoDateString,
+  }),
+});
+
+export type ScopeManifest = z.infer<typeof ScopeManifestSchema>;
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/manifest-schema.test.ts`
+Expected: 4 tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/types.ts src/manifest-schema.ts tests/unit/manifest-schema.test.ts
+git commit -m "feat: add types and Zod schema for scope manifest"
+```
+
+---
+
+## Task 3: IP Matcher
+
+**Files:**
+- Create: `src/ip-matcher.ts`
+- Test: `tests/unit/ip-matcher.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/unit/ip-matcher.test.ts`:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { isIpInCidr, isRfc1918, isCloudMetadata, isIpInAnyRange } from "../../src/ip-matcher.js";
+
+describe("isIpInCidr", () => {
+  it("matches IP within CIDR range", () => {
+    expect(isIpInCidr("10.10.10.5", "10.10.10.0/24")).toBe(true);
+  });
+
+  it("rejects IP outside CIDR range", () => {
+    expect(isIpInCidr("10.10.11.1", "10.10.10.0/24")).toBe(false);
+  });
+
+  it("matches exact IP as /32", () => {
+    expect(isIpInCidr("203.0.113.5", "203.0.113.5/32")).toBe(true);
+  });
+
+  it("handles single IP (no CIDR notation) as exact match", () => {
+    expect(isIpInCidr("203.0.113.5", "203.0.113.5")).toBe(true);
+  });
+
+  it("rejects invalid IP gracefully", () => {
+    expect(isIpInCidr("not-an-ip", "10.0.0.0/8")).toBe(false);
+  });
+});
+
+describe("isRfc1918", () => {
+  it("detects 10.x.x.x", () => {
+    expect(isRfc1918("10.0.0.1")).toBe(true);
+  });
+
+  it("detects 172.16.x.x", () => {
+    expect(isRfc1918("172.16.0.1")).toBe(true);
+  });
+
+  it("detects 192.168.x.x", () => {
+    expect(isRfc1918("192.168.1.1")).toBe(true);
+  });
+
+  it("detects link-local 169.254.x.x", () => {
+    expect(isRfc1918("169.254.1.1")).toBe(true);
+  });
+
+  it("does not flag public IPs", () => {
+    expect(isRfc1918("203.0.113.10")).toBe(false);
+  });
+});
+
+describe("isCloudMetadata", () => {
+  it("detects AWS/GCP metadata IP", () => {
+    expect(isCloudMetadata("169.254.169.254")).toBe(true);
+  });
+
+  it("detects AWS IPv6 metadata", () => {
+    expect(isCloudMetadata("fd00:ec2::254")).toBe(true);
+  });
+
+  it("does not flag normal IPs", () => {
+    expect(isCloudMetadata("10.0.0.1")).toBe(false);
+  });
+});
+
+describe("isIpInAnyRange", () => {
+  const ranges = ["10.10.10.0/24", "203.0.113.0/28"];
+
+  it("matches IP in first range", () => {
+    expect(isIpInAnyRange("10.10.10.50", ranges)).toBe(true);
+  });
+
+  it("matches IP in second range", () => {
+    expect(isIpInAnyRange("203.0.113.10", ranges)).toBe(true);
+  });
+
+  it("rejects IP not in any range", () => {
+    expect(isIpInAnyRange("192.168.1.1", ranges)).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/ip-matcher.test.ts`
+Expected: FAIL — cannot find module
+
+- [ ] **Step 3: Implement ip-matcher.ts**
+
+Create `src/ip-matcher.ts`:
+
+```typescript
+import IPCIDR from "ip-cidr";
+
+const RFC1918_RANGES = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "169.254.0.0/16"];
+const CLOUD_METADATA = ["169.254.169.254", "fd00:ec2::254"];
+
+export function isIpInCidr(ip: string, cidr: string): boolean {
+  try {
+    // Handle bare IP (no slash) as exact match
+    if (!cidr.includes("/")) {
+      return ip === cidr;
+    }
+    const range = new IPCIDR(cidr);
+    if (!range.isValid()) return false;
+    return range.contains(ip);
+  } catch {
+    return false;
+  }
+}
+
+export function isIpInAnyRange(ip: string, ranges: string[]): boolean {
+  return ranges.some((range) => isIpInCidr(ip, range));
+}
+
+export function isRfc1918(ip: string): boolean {
+  return isIpInAnyRange(ip, RFC1918_RANGES);
+}
+
+export function isCloudMetadata(ip: string): boolean {
+  return CLOUD_METADATA.includes(ip);
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/ip-matcher.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ip-matcher.ts tests/unit/ip-matcher.test.ts
+git commit -m "feat: add IP/CIDR matching with RFC-1918 and cloud metadata detection"
+```
+
+---
+
+## Task 4: Domain Matcher
+
+**Files:**
+- Create: `src/domain-matcher.ts`
+- Test: `tests/unit/domain-matcher.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/unit/domain-matcher.test.ts`:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { matchesDomain, matchesAnyDomain } from "../../src/domain-matcher.js";
+
+describe("matchesDomain", () => {
+  it("matches exact domain", () => {
+    expect(matchesDomain("acme-staging.example.com", "acme-staging.example.com")).toBe(true);
+  });
+
+  it("matches case-insensitively", () => {
+    expect(matchesDomain("ACME-STAGING.Example.COM", "acme-staging.example.com")).toBe(true);
+  });
+
+  it("wildcard matches single subdomain", () => {
+    expect(matchesDomain("foo.acme.com", "*.acme.com")).toBe(true);
+  });
+
+  it("wildcard does NOT match apex domain", () => {
+    expect(matchesDomain("acme.com", "*.acme.com")).toBe(false);
+  });
+
+  it("wildcard does NOT match two levels deep", () => {
+    expect(matchesDomain("foo.bar.acme.com", "*.acme.com")).toBe(false);
+  });
+
+  it("strips trailing dots", () => {
+    expect(matchesDomain("foo.acme.com.", "*.acme.com")).toBe(true);
+  });
+
+  it("rejects non-matching domain", () => {
+    expect(matchesDomain("evil.com", "*.acme.com")).toBe(false);
+  });
+});
+
+describe("matchesAnyDomain", () => {
+  const patterns = ["*.acme.com", "acme-staging.example.com"];
+
+  it("matches wildcard pattern", () => {
+    expect(matchesAnyDomain("app.acme.com", patterns)).toBe(true);
+  });
+
+  it("matches exact pattern", () => {
+    expect(matchesAnyDomain("acme-staging.example.com", patterns)).toBe(true);
+  });
+
+  it("rejects no match", () => {
+    expect(matchesAnyDomain("evil.com", patterns)).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/domain-matcher.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement domain-matcher.ts**
+
+Create `src/domain-matcher.ts`:
+
+```typescript
+export function matchesDomain(hostname: string, pattern: string): boolean {
+  // Normalize: lowercase, strip trailing dot
+  const h = hostname.toLowerCase().replace(/\.$/, "");
+  const p = pattern.toLowerCase().replace(/\.$/, "");
+
+  if (p.startsWith("*.")) {
+    // Wildcard: *.acme.com matches foo.acme.com but NOT acme.com or foo.bar.acme.com
+    const base = p.slice(2); // "acme.com"
+    if (h === base) return false; // apex — no match
+    const prefix = h.slice(0, -(base.length + 1)); // everything before ".acme.com"
+    if (!h.endsWith("." + base)) return false;
+    // prefix must be a single label (no dots)
+    return prefix.length > 0 && !prefix.includes(".");
+  }
+
+  return h === p;
+}
+
+export function matchesAnyDomain(hostname: string, patterns: string[]): boolean {
+  return patterns.some((p) => matchesDomain(hostname, p));
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/domain-matcher.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/domain-matcher.ts tests/unit/domain-matcher.test.ts
+git commit -m "feat: add domain/wildcard matching with case-insensitive comparison"
+```
+
+---
+
+## Task 5: Target Extractor
+
+**Files:**
+- Create: `src/extractor.ts`
+- Test: `tests/unit/extractor.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/unit/extractor.test.ts`:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { extractTarget, ExtractionResult } from "../../src/extractor.js";
+
+describe("extractTarget", () => {
+  it("extracts target from nmap_scan", () => {
+    const result = extractTarget("nmap_scan", { target: "203.0.113.10", ports: "1-1024" });
+    expect(result).toEqual({ target: "203.0.113.10", source: "target", usedFallback: false });
+  });
+
+  it("extracts host from nmap", () => {
+    const result = extractTarget("nmap", { host: "10.10.10.1" });
+    expect(result).toEqual({ target: "10.10.10.1", source: "host", usedFallback: false });
+  });
+
+  it("extracts hostname from burp_scan URL", () => {
+    const result = extractTarget("burp_scan", { url: "https://app.acme.com/api/v1" });
+    expect(result).toEqual({ target: "app.acme.com", source: "url", usedFallback: false });
+  });
+
+  it("extracts hostname from sqlmap URL", () => {
+    const result = extractTarget("sqlmap", { url: "http://test.acme.com/login?id=1" });
+    expect(result).toEqual({ target: "test.acme.com", source: "url", usedFallback: false });
+  });
+
+  it("extracts rhost from metasploit tool", () => {
+    const result = extractTarget("msf_exploit", { rhost: "10.10.10.5", payload: "reverse_tcp" });
+    expect(result).toEqual({ target: "10.10.10.5", source: "rhost", usedFallback: false });
+  });
+
+  it("handles nuclei with targets array (takes first)", () => {
+    const result = extractTarget("nuclei", { targets: ["10.10.10.1", "10.10.10.2"] });
+    expect(result).toEqual({ target: "10.10.10.1", source: "targets", usedFallback: false });
+  });
+
+  it("falls back to host param for unknown tool", () => {
+    const result = extractTarget("custom_tool", { host: "192.168.1.1", mode: "fast" });
+    expect(result).toEqual({ target: "192.168.1.1", source: "host", usedFallback: true });
+  });
+
+  it("falls back to url param for unknown tool", () => {
+    const result = extractTarget("custom_scanner", { url: "https://example.com/path" });
+    expect(result).toEqual({ target: "example.com", source: "url", usedFallback: true });
+  });
+
+  it("returns null for tool with no recognizable target param", () => {
+    const result = extractTarget("list_files", { path: "/tmp", recursive: true });
+    expect(result).toBeNull();
+  });
+
+  it("strips credentials from URL before extracting hostname", () => {
+    const result = extractTarget("curl", { url: "https://user:pass@secret.acme.com/api" });
+    expect(result).toEqual({ target: "secret.acme.com", source: "url", usedFallback: false });
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/extractor.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement extractor.ts**
+
+Create `src/extractor.ts`:
+
+```typescript
+export interface ExtractionResult {
+  target: string;
+  source: string;
+  usedFallback: boolean;
+}
+
+// Tool name patterns → ordered list of parameter names to check
+const TOOL_PARAM_MAP: Record<string, string[]> = {
+  nmap: ["target", "host", "hosts"],
+  nmap_scan: ["target", "host", "hosts"],
+  burp_scan: ["url", "target_url", "base_url"],
+  burp_active_scan: ["url", "target_url", "base_url"],
+  sqlmap: ["url", "target"],
+  curl: ["url", "uri"],
+  http_request: ["url", "uri"],
+  nikto: ["host", "target", "url"],
+  gobuster: ["url", "target"],
+  ffuf: ["url", "target"],
+  dirb: ["url", "target"],
+  netcat: ["host", "target"],
+  nc: ["host", "target"],
+  ping: ["host", "target"],
+  traceroute: ["host", "target"],
+  nuclei: ["target", "targets", "url"],
+};
+
+// Metasploit-style tools use rhost/rhosts
+const MSF_PARAMS = ["rhost", "rhosts", "target"];
+
+// Fallback parameter names for unknown tools
+const FALLBACK_PARAMS = ["target", "host", "url", "rhost", "destination", "uri"];
+
+function extractHostnameFromUrl(urlStr: string): string | null {
+  try {
+    const url = new URL(urlStr);
+    return url.hostname;
+  } catch {
+    return null;
+  }
+}
+
+function isUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function resolveParamValue(params: Record<string, unknown>, paramNames: string[]): { value: string; source: string } | null {
+  for (const name of paramNames) {
+    const val = params[name];
+    if (typeof val === "string" && val.length > 0) {
+      return { value: val, source: name };
+    }
+    if (Array.isArray(val) && val.length > 0 && typeof val[0] === "string") {
+      return { value: val[0], source: name };
+    }
+  }
+  return null;
+}
+
+export function extractTarget(toolName: string, params: Record<string, unknown>): ExtractionResult | null {
+  const normalizedTool = toolName.toLowerCase();
+
+  // Check for metasploit-style tools
+  const isMsf = normalizedTool.startsWith("msf") || normalizedTool === "metasploit";
+  const paramList = isMsf ? MSF_PARAMS : TOOL_PARAM_MAP[normalizedTool];
+
+  let usedFallback = false;
+  let resolved: { value: string; source: string } | null = null;
+
+  if (paramList) {
+    resolved = resolveParamValue(params, paramList);
+  }
+
+  if (!resolved) {
+    // Fallback for unknown tools
+    resolved = resolveParamValue(params, FALLBACK_PARAMS);
+    if (resolved) usedFallback = true;
+  }
+
+  if (!resolved) return null;
+
+  // If the value looks like a URL, extract the hostname
+  let target = resolved.value;
+  if (isUrl(target)) {
+    const hostname = extractHostnameFromUrl(target);
+    if (!hostname) return null;
+    target = hostname;
+  }
+
+  return { target, source: resolved.source, usedFallback };
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/extractor.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/extractor.ts tests/unit/extractor.test.ts
+git commit -m "feat: add target extraction from MCP tool parameters"
+```
+
+---
+
+## Task 6: Technique Checker
+
+**Files:**
+- Create: `src/technique-checker.ts`
+- Test: `tests/unit/technique-checker.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/unit/technique-checker.test.ts`:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { TechniqueChecker } from "../../src/technique-checker.js";
+
+describe("TechniqueChecker", () => {
+  const checker = new TechniqueChecker();
+
+  it("blocks hping3 as dos technique", () => {
+    expect(checker.getCategory("hping3")).toBe("dos");
+  });
+
+  it("blocks slowloris as dos technique", () => {
+    expect(checker.getCategory("slowloris")).toBe("dos");
+  });
+
+  it("blocks tool with flood in name as dos", () => {
+    expect(checker.getCategory("synflood")).toBe("dos");
+  });
+
+  it("blocks tool with dos in name", () => {
+    expect(checker.getCategory("my_dos_tool")).toBe("dos");
+  });
+
+  it("blocks gophish as social_engineering", () => {
+    expect(checker.getCategory("gophish")).toBe("social_engineering");
+  });
+
+  it("blocks setoolkit as social_engineering", () => {
+    expect(checker.getCategory("setoolkit")).toBe("social_engineering");
+  });
+
+  it("returns null for non-categorized tool", () => {
+    expect(checker.getCategory("nmap")).toBeNull();
+  });
+
+  it("isBlocked returns true when technique is excluded", () => {
+    expect(checker.isBlocked("hping3", ["dos"])).toBe(true);
+  });
+
+  it("isBlocked returns false when technique is not excluded", () => {
+    expect(checker.isBlocked("nmap", ["dos"])).toBe(false);
+  });
+
+  it("loads custom technique mappings", () => {
+    const custom = new TechniqueChecker({
+      custom_category: { exact: ["my_tool"], patterns: ["custom_"] },
+    });
+    expect(custom.getCategory("my_tool")).toBe("custom_category");
+    expect(custom.getCategory("custom_scanner")).toBe("custom_category");
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/technique-checker.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement technique-checker.ts**
+
+Create `src/technique-checker.ts`:
+
+```typescript
+interface TechniqueMapping {
+  exact: string[];
+  patterns: string[];
+}
+
+type TechniqueMap = Record<string, TechniqueMapping>;
+
+const DEFAULT_TECHNIQUE_MAP: TechniqueMap = {
+  dos: {
+    exact: ["hping3", "slowloris", "udpflood", "synflood"],
+    patterns: ["flood", "dos"],
+  },
+  destructive: {
+    exact: [],
+    patterns: ["destroy", "wipe", "wiper"],
+  },
+  social_engineering: {
+    exact: ["gophish", "setoolkit", "evilginx", "modlishka"],
+    patterns: [],
+  },
+};
+
+export class TechniqueChecker {
+  private map: TechniqueMap;
+
+  constructor(customMappings?: TechniqueMap) {
+    this.map = { ...DEFAULT_TECHNIQUE_MAP };
+    if (customMappings) {
+      for (const [category, mapping] of Object.entries(customMappings)) {
+        if (this.map[category]) {
+          this.map[category] = {
+            exact: [...this.map[category].exact, ...mapping.exact],
+            patterns: [...this.map[category].patterns, ...mapping.patterns],
+          };
+        } else {
+          this.map[category] = mapping;
+        }
+      }
+    }
+  }
+
+  getCategory(toolName: string): string | null {
+    const normalized = toolName.toLowerCase();
+    for (const [category, mapping] of Object.entries(this.map)) {
+      if (mapping.exact.includes(normalized)) return category;
+      if (mapping.patterns.some((p) => normalized.includes(p))) return category;
+    }
+    return null;
+  }
+
+  isBlocked(toolName: string, excludedTechniques: string[]): boolean {
+    const category = this.getCategory(toolName);
+    if (!category) return false;
+    return excludedTechniques.includes(category);
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/technique-checker.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/technique-checker.ts tests/unit/technique-checker.test.ts
+git commit -m "feat: add technique category checker with configurable mappings"
+```
+
+---
+
+## Task 7: Parameter Sanitizer
+
+**Files:**
+- Create: `src/sanitizer.ts`
+- Test: `tests/unit/sanitizer.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/unit/sanitizer.test.ts`:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { sanitizeParams } from "../../src/sanitizer.js";
+
+describe("sanitizeParams", () => {
+  it("redacts password field", () => {
+    expect(sanitizeParams({ password: "secret123" })).toEqual({ password: "[REDACTED]" });
+  });
+
+  it("redacts api_key field", () => {
+    expect(sanitizeParams({ api_key: "sk-abc123" })).toEqual({ api_key: "[REDACTED]" });
+  });
+
+  it("redacts token field", () => {
+    expect(sanitizeParams({ token: "eyJhb..." })).toEqual({ token: "[REDACTED]" });
+  });
+
+  it("redacts case-insensitively", () => {
+    expect(sanitizeParams({ API_KEY: "key", Password: "pw" })).toEqual({
+      API_KEY: "[REDACTED]",
+      Password: "[REDACTED]",
+    });
+  });
+
+  it("redacts nested objects recursively", () => {
+    const input = {
+      config: { auth: { password: "secret", username: "admin" } },
+      target: "10.0.0.1",
+    };
+    const result = sanitizeParams(input);
+    expect(result).toEqual({
+      config: { auth: { password: "[REDACTED]", username: "admin" } },
+      target: "10.0.0.1",
+    });
+  });
+
+  it("redacts within arrays", () => {
+    const input = { headers: [{ key: "Authorization", secret: "Bearer abc" }] };
+    const result = sanitizeParams(input);
+    expect(result).toEqual({ headers: [{ key: "Authorization", secret: "[REDACTED]" }] });
+  });
+
+  it("passes through normal params unchanged", () => {
+    expect(sanitizeParams({ target: "10.0.0.1", ports: "80" })).toEqual({
+      target: "10.0.0.1",
+      ports: "80",
+    });
+  });
+
+  it("handles null and undefined values", () => {
+    expect(sanitizeParams({ password: null, target: "x" })).toEqual({
+      password: "[REDACTED]",
+      target: "x",
+    });
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/sanitizer.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement sanitizer.ts**
+
+Create `src/sanitizer.ts`:
+
+```typescript
+const SENSITIVE_PATTERNS = /^(password|passwd|token|secret|key|credential|auth|apikey|api_key|authorization)$/i;
+
+export function sanitizeParams(params: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (SENSITIVE_PATTERNS.test(key)) {
+      result[key] = "[REDACTED]";
+    } else if (Array.isArray(value)) {
+      result[key] = value.map((item) =>
+        typeof item === "object" && item !== null
+          ? sanitizeParams(item as Record<string, unknown>)
+          : item
+      );
+    } else if (typeof value === "object" && value !== null) {
+      result[key] = sanitizeParams(value as Record<string, unknown>);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/sanitizer.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/sanitizer.ts tests/unit/sanitizer.test.ts
+git commit -m "feat: add parameter sanitizer to redact secrets from audit logs"
+```
+
+---
+
+## Task 8: DNS Resolver with Caching
+
+**Files:**
+- Create: `src/dns-resolver.ts`
+- Test: `tests/unit/dns-resolver.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/unit/dns-resolver.test.ts`:
+
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { DnsResolver } from "../../src/dns-resolver.js";
+
+// We mock dns/promises at the module level
+vi.mock("dns/promises", () => ({
+  default: {
+    resolve4: vi.fn(),
+    resolve6: vi.fn(),
+  },
+}));
+
+import dns from "dns/promises";
+
+const mockResolve4 = vi.mocked(dns.resolve4);
+const mockResolve6 = vi.mocked(dns.resolve6);
+
+describe("DnsResolver", () => {
+  let resolver: DnsResolver;
+
+  beforeEach(() => {
+    resolver = new DnsResolver(60);
+    vi.clearAllMocks();
+  });
+
+  it("resolves A records", async () => {
+    mockResolve4.mockResolvedValue(["93.184.216.34"]);
+    mockResolve6.mockRejectedValue(new Error("no AAAA"));
+    const ips = await resolver.resolve("example.com");
+    expect(ips).toEqual(["93.184.216.34"]);
+  });
+
+  it("resolves both A and AAAA records", async () => {
+    mockResolve4.mockResolvedValue(["93.184.216.34"]);
+    mockResolve6.mockResolvedValue(["2606:2800:220:1:248:1893:25c8:1946"]);
+    const ips = await resolver.resolve("example.com");
+    expect(ips).toContain("93.184.216.34");
+    expect(ips).toContain("2606:2800:220:1:248:1893:25c8:1946");
+  });
+
+  it("returns empty array on NXDOMAIN (does not throw)", async () => {
+    mockResolve4.mockRejectedValue(Object.assign(new Error("NXDOMAIN"), { code: "ENOTFOUND" }));
+    mockResolve6.mockRejectedValue(Object.assign(new Error("NXDOMAIN"), { code: "ENOTFOUND" }));
+    const ips = await resolver.resolve("nonexistent.invalid");
+    expect(ips).toEqual([]);
+  });
+
+  it("returns cached result within TTL", async () => {
+    mockResolve4.mockResolvedValue(["1.2.3.4"]);
+    mockResolve6.mockRejectedValue(new Error("no AAAA"));
+
+    await resolver.resolve("cached.example.com");
+    await resolver.resolve("cached.example.com");
+
+    expect(mockResolve4).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-resolves after TTL expires", async () => {
+    const shortTtlResolver = new DnsResolver(0); // 0 second TTL = always expired
+    mockResolve4.mockResolvedValue(["1.2.3.4"]);
+    mockResolve6.mockRejectedValue(new Error("no AAAA"));
+
+    await shortTtlResolver.resolve("ttl.example.com");
+    await shortTtlResolver.resolve("ttl.example.com");
+
+    expect(mockResolve4).toHaveBeenCalledTimes(2);
+  });
+
+  it("recognizes raw IP addresses without DNS lookup", async () => {
+    const ips = await resolver.resolve("10.10.10.5");
+    expect(ips).toEqual(["10.10.10.5"]);
+    expect(mockResolve4).not.toHaveBeenCalled();
+  });
+
+  it("recognizes raw IPv6 addresses without DNS lookup", async () => {
+    const ips = await resolver.resolve("::1");
+    expect(ips).toEqual(["::1"]);
+    expect(mockResolve4).not.toHaveBeenCalled();
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/dns-resolver.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement dns-resolver.ts**
+
+Create `src/dns-resolver.ts`:
+
+```typescript
+import dns from "dns/promises";
+import { isIP } from "net";
+
+interface CacheEntry {
+  ips: string[];
+  expiresAt: number;
+}
+
+export class DnsResolver {
+  private cache = new Map<string, CacheEntry>();
+  private ttlSeconds: number;
+
+  constructor(ttlSeconds: number = 60) {
+    this.ttlSeconds = ttlSeconds;
+  }
+
+  async resolve(target: string): Promise<string[]> {
+    // If it's already an IP address, return it directly
+    if (isIP(target)) {
+      return [target];
+    }
+
+    // Check cache
+    const cached = this.cache.get(target);
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.ips;
+    }
+
+    // Resolve A and AAAA in parallel
+    const [ipv4, ipv6] = await Promise.all([
+      dns.resolve4(target).catch(() => [] as string[]),
+      dns.resolve6(target).catch(() => [] as string[]),
+    ]);
+
+    const ips = [...ipv4, ...ipv6];
+
+    // Cache the result
+    this.cache.set(target, {
+      ips,
+      expiresAt: Date.now() + this.ttlSeconds * 1000,
+    });
+
+    return ips;
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/dns-resolver.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/dns-resolver.ts tests/unit/dns-resolver.test.ts
+git commit -m "feat: add DNS resolver with TTL-aware caching"
+```
+
+---
+
+## Task 9: Scope Validator Engine
+
+**Files:**
+- Create: `src/validator.ts`
+- Test: `tests/unit/validator.test.ts`
+
+This is the core orchestrator that ties together all the previous components.
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/unit/validator.test.ts`:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ScopeValidator } from "../../src/validator.js";
+import type { ScopeManifest } from "../../src/types.js";
+
+const baseManifest: ScopeManifest = {
+  engagement_id: "ENG-2025-0142",
+  client: "Acme Corp",
+  operator: "operator@integsec.com",
+  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: [],
+  },
+  excluded_targets: ["203.0.113.5", "hr.acme.com"],
+  authorized_techniques: ["recon", "web_app", "api_testing"],
+  excluded_techniques: ["dos", "destructive", "social_engineering"],
+  engagement_window: {
+    start: "2020-01-01T00:00:00Z",
+    end: "2099-12-31T23:59:59Z",
+  },
+};
+
+describe("ScopeValidator", () => {
+  let validator: ScopeValidator;
+
+  beforeEach(() => {
+    validator = new ScopeValidator(baseManifest);
+  });
+
+  // --- Target authorization ---
+  it("ALLOWS IP in authorized CIDR", async () => {
+    const result = await validator.validate("nmap_scan", { target: "10.10.10.50" });
+    expect(result.decision).toBe("ALLOWED");
+    expect(result.matchedScopeItem).toBe("10.10.10.0/24");
+  });
+
+  it("BLOCKS IP not in any authorized range", async () => {
+    const result = await validator.validate("nmap_scan", { target: "192.168.1.1" });
+    expect(result.decision).toBe("BLOCKED_NOT_IN_SCOPE");
+  });
+
+  it("BLOCKS explicitly excluded IP even if in authorized range", async () => {
+    const result = await validator.validate("nmap_scan", { target: "203.0.113.5" });
+    expect(result.decision).toBe("BLOCKED_EXCLUDED_TARGET");
+  });
+
+  // --- Domain matching ---
+  it("ALLOWS domain matching wildcard", async () => {
+    // Mock DNS to return an in-scope IP
+    validator["dnsResolver"].resolve = vi.fn().mockResolvedValue(["10.10.10.1"]);
+    const result = await validator.validate("curl", { url: "https://app.acme.com/api" });
+    expect(result.decision).toBe("ALLOWED");
+  });
+
+  it("BLOCKS apex domain (wildcard does not match)", async () => {
+    validator["dnsResolver"].resolve = vi.fn().mockResolvedValue(["1.2.3.4"]);
+    const result = await validator.validate("curl", { url: "https://acme.com/" });
+    expect(result.decision).toBe("BLOCKED_NOT_IN_SCOPE");
+  });
+
+  it("BLOCKS two levels deep (wildcard does not match)", async () => {
+    validator["dnsResolver"].resolve = vi.fn().mockResolvedValue(["1.2.3.4"]);
+    const result = await validator.validate("curl", { url: "https://a.b.acme.com/" });
+    expect(result.decision).toBe("BLOCKED_NOT_IN_SCOPE");
+  });
+
+  it("BLOCKS excluded domain even if wildcard matches", async () => {
+    validator["dnsResolver"].resolve = vi.fn().mockResolvedValue(["10.10.10.1"]);
+    const result = await validator.validate("curl", { url: "https://hr.acme.com/" });
+    expect(result.decision).toBe("BLOCKED_EXCLUDED_TARGET");
+  });
+
+  // --- Time window ---
+  it("BLOCKS when outside engagement window", async () => {
+    const expiredManifest = {
+      ...baseManifest,
+      engagement_window: {
+        start: "2020-01-01T00:00:00Z",
+        end: "2020-01-02T00:00:00Z",
+      },
+    };
+    const v = new ScopeValidator(expiredManifest);
+    const result = await v.validate("nmap_scan", { target: "10.10.10.50" });
+    expect(result.decision).toBe("BLOCKED_OUTSIDE_WINDOW");
+  });
+
+  // --- Technique blocking ---
+  it("BLOCKS blocked technique regardless of target", async () => {
+    const result = await validator.validate("slowloris", { target: "10.10.10.50" });
+    expect(result.decision).toBe("BLOCKED_TECHNIQUE");
+  });
+
+  it("BLOCKS tool with dos in name", async () => {
+    const result = await validator.validate("my_dos_tool", { target: "10.10.10.50" });
+    expect(result.decision).toBe("BLOCKED_TECHNIQUE");
+  });
+
+  // --- No target ---
+  it("ALLOWS tool with no target-like parameter", async () => {
+    const result = await validator.validate("list_files", { path: "/tmp" });
+    expect(result.decision).toBe("ALLOWED_NO_TARGET");
+  });
+
+  // --- RFC-1918 and metadata ---
+  it("BLOCKS RFC-1918 address not explicitly in scope", async () => {
+    const noPrivateManifest = {
+      ...baseManifest,
+      authorized_targets: { ...baseManifest.authorized_targets, ip_ranges: ["203.0.113.0/28"] },
+    };
+    const v = new ScopeValidator(noPrivateManifest);
+    const result = await v.validate("nmap_scan", { target: "192.168.1.1" });
+    expect(result.decision).toBe("BLOCKED_NOT_IN_SCOPE");
+  });
+
+  it("BLOCKS cloud metadata IP 169.254.169.254", async () => {
+    const result = await validator.validate("curl", { url: "http://169.254.169.254/latest/meta-data/" });
+    expect(result.decision).toBe("BLOCKED_NOT_IN_SCOPE");
+  });
+
+  // --- DNS failure ---
+  it("BLOCKS when DNS resolution fails (fail closed)", async () => {
+    validator["dnsResolver"].resolve = vi.fn().mockResolvedValue([]);
+    const result = await validator.validate("curl", { url: "https://nonexistent.example.com/" });
+    expect(result.decision).toBe("BLOCKED_DNS_FAILED");
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/validator.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement validator.ts**
+
+Create `src/validator.ts`:
+
+```typescript
+import type { ScopeManifest, ValidationResult, Decision } from "./types.js";
+import { extractTarget } from "./extractor.js";
+import { DnsResolver } from "./dns-resolver.js";
+import { isIpInAnyRange, isRfc1918, isCloudMetadata } from "./ip-matcher.js";
+import { matchesDomain, matchesAnyDomain } from "./domain-matcher.js";
+import { TechniqueChecker } from "./technique-checker.js";
+
+export class ScopeValidator {
+  private manifest: ScopeManifest;
+  private dnsResolver: DnsResolver;
+  private techniqueChecker: TechniqueChecker;
+
+  constructor(manifest: ScopeManifest, dnsResolver?: DnsResolver, techniqueChecker?: TechniqueChecker) {
+    this.manifest = manifest;
+    this.dnsResolver = dnsResolver ?? new DnsResolver();
+    this.techniqueChecker = techniqueChecker ?? new TechniqueChecker();
+  }
+
+  async validate(toolName: string, params: Record<string, unknown>): Promise<ValidationResult> {
+    const start = performance.now();
+
+    const result = await this.doValidate(toolName, params);
+
+    result.durationMs = Math.round(performance.now() - start);
+    return result;
+  }
+
+  private async doValidate(toolName: string, params: Record<string, unknown>): Promise<ValidationResult> {
+    // 1. Technique block check
+    if (this.techniqueChecker.isBlocked(toolName, this.manifest.excluded_techniques)) {
+      const category = this.techniqueChecker.getCategory(toolName);
+      return {
+        decision: "BLOCKED_TECHNIQUE",
+        reason: `Tool "${toolName}" matches blocked technique category "${category}"`,
+        durationMs: 0,
+      };
+    }
+
+    // 2. Time window check
+    const now = new Date();
+    const windowStart = new Date(this.manifest.engagement_window.start);
+    const windowEnd = new Date(this.manifest.engagement_window.end);
+    if (now < windowStart || now > windowEnd) {
+      return {
+        decision: "BLOCKED_OUTSIDE_WINDOW",
+        reason: `Current time is outside engagement window (${this.manifest.engagement_window.start} to ${this.manifest.engagement_window.end})`,
+        durationMs: 0,
+      };
+    }
+
+    // 3. Target extraction
+    const extraction = extractTarget(toolName, params);
+    if (!extraction) {
+      return {
+        decision: "ALLOWED_NO_TARGET",
+        reason: "No target-like parameter found in tool call",
+        durationMs: 0,
+      };
+    }
+
+    const { target } = extraction;
+
+    // 4. Resolve DNS if it's a hostname
+    const resolvedIps = await this.dnsResolver.resolve(target);
+
+    // Fail closed on DNS failure (empty result for a hostname)
+    const isIpAddress = /^[\d.]+$/.test(target) || target.includes(":");
+    if (!isIpAddress && resolvedIps.length === 0) {
+      return {
+        decision: "BLOCKED_DNS_FAILED",
+        reason: `DNS resolution failed for "${target}" — blocking (fail closed)`,
+        extractedTarget: target,
+        resolvedIps: [],
+        durationMs: 0,
+      };
+    }
+
+    // 5. Exclusion check — exclusions win
+    // Check hostname against excluded targets
+    if (this.manifest.excluded_targets.some((ex) => matchesDomain(target, ex) || target.toLowerCase() === ex.toLowerCase())) {
+      return {
+        decision: "BLOCKED_EXCLUDED_TARGET",
+        reason: `Target "${target}" is explicitly excluded`,
+        extractedTarget: target,
+        resolvedIps,
+        durationMs: 0,
+      };
+    }
+    // Check resolved IPs against excluded targets
+    for (const ip of resolvedIps) {
+      if (this.manifest.excluded_targets.includes(ip)) {
+        return {
+          decision: "BLOCKED_EXCLUDED_TARGET",
+          reason: `Resolved IP "${ip}" for target "${target}" is explicitly excluded`,
+          extractedTarget: target,
+          resolvedIps,
+          durationMs: 0,
+        };
+      }
+    }
+
+    // 6. Authorization check
+    // Check domain match
+    const domainMatch = matchesAnyDomain(target, this.manifest.authorized_targets.domains);
+
+    // Check IP match
+    let ipMatch: string | null = null;
+    for (const ip of resolvedIps) {
+      // Block RFC-1918 and metadata IPs unless explicitly authorized
+      if ((isRfc1918(ip) || isCloudMetadata(ip)) && !isIpInAnyRange(ip, this.manifest.authorized_targets.ip_ranges)) {
+        continue; // Not authorized, skip — will fall through to NOT_IN_SCOPE
+      }
+      for (const range of this.manifest.authorized_targets.ip_ranges) {
+        const { isIpInCidr } = await import("./ip-matcher.js");
+        if (isIpInCidr(ip, range)) {
+          ipMatch = range;
+          break;
+        }
+      }
+      if (ipMatch) break;
+    }
+
+    if (domainMatch || ipMatch) {
+      return {
+        decision: "ALLOWED",
+        reason: domainMatch
+          ? `Target "${target}" matches authorized domain pattern`
+          : `Target matches authorized range ${ipMatch}`,
+        matchedScopeItem: ipMatch ?? target,
+        extractedTarget: target,
+        resolvedIps,
+        durationMs: 0,
+      };
+    }
+
+    return {
+      decision: "BLOCKED_NOT_IN_SCOPE",
+      reason: `Target "${target}" (resolved: ${resolvedIps.join(", ") || "none"}) is not in authorized scope`,
+      extractedTarget: target,
+      resolvedIps,
+      durationMs: 0,
+    };
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/validator.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/validator.ts tests/unit/validator.test.ts
+git commit -m "feat: add scope validator engine orchestrating all validation checks"
+```
+
+---
+
+## Task 10: Manifest Loader
+
+**Files:**
+- Create: `src/manifest.ts`
+- Create: `src/config.ts`
+- Test: `tests/unit/manifest.test.ts`
+- Create: `tests/fixtures/scope-valid.json`
+- Create: `tests/fixtures/scope-expired.json`
+
+- [ ] **Step 1: Create test fixtures**
+
+Create `tests/fixtures/scope-valid.json`:
+```json
+{
+  "engagement_id": "ENG-2025-0142",
+  "client": "Acme Corp",
+  "operator": "operator@integsec.com",
+  "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"]
+  },
+  "excluded_targets": ["203.0.113.5", "hr.acme.com"],
+  "authorized_techniques": ["recon", "web_app", "api_testing"],
+  "excluded_techniques": ["dos", "destructive", "social_engineering"],
+  "engagement_window": {
+    "start": "2020-01-01T00:00:00Z",
+    "end": "2099-12-31T23:59:59Z"
+  }
+}
+```
+
+Create `tests/fixtures/scope-expired.json`:
+```json
+{
+  "engagement_id": "ENG-OLD-001",
+  "client": "Old Client",
+  "operator": "old@integsec.com",
+  "authorized_targets": {
+    "ip_ranges": ["10.0.0.0/8"],
+    "domains": [],
+    "urls": [],
+    "cloud_accounts": []
+  },
+  "excluded_targets": [],
+  "authorized_techniques": ["recon"],
+  "excluded_techniques": [],
+  "engagement_window": {
+    "start": "2020-01-01T00:00:00Z",
+    "end": "2020-01-02T00:00:00Z"
+  }
+}
+```
+
+- [ ] **Step 2: Write failing tests for manifest loader**
+
+Create `tests/unit/manifest.test.ts`:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { loadManifest } from "../../src/manifest.js";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixturesDir = join(__dirname, "..", "fixtures");
+
+describe("loadManifest", () => {
+  beforeEach(() => {
+    // Clear all manifest env vars
+    delete process.env.SCOPE_MANIFEST_PATH;
+    delete process.env.SCOPE_MANIFEST_JSON;
+    delete process.env.SCOPE_MANIFEST_SECRET_ARN;
+    delete process.env.SCOPE_MANIFEST_KEYVAULT_URI;
+    delete process.env.SCOPE_MANIFEST_GCP_SECRET;
+  });
+
+  it("loads manifest from file path", async () => {
+    process.env.SCOPE_MANIFEST_PATH = join(fixturesDir, "scope-valid.json");
+    const manifest = await loadManifest();
+    expect(manifest.engagement_id).toBe("ENG-2025-0142");
+    expect(manifest.client).toBe("Acme Corp");
+  });
+
+  it("loads manifest from inline JSON env var", async () => {
+    process.env.SCOPE_MANIFEST_JSON = JSON.stringify({
+      engagement_id: "ENG-INLINE",
+      client: "Inline",
+      operator: "op@test.com",
+      authorized_targets: { ip_ranges: [], domains: [], urls: [], cloud_accounts: [] },
+      excluded_targets: [],
+      authorized_techniques: [],
+      excluded_techniques: [],
+      engagement_window: { start: "2020-01-01T00:00:00Z", end: "2099-12-31T23:59:59Z" },
+    });
+    const manifest = await loadManifest();
+    expect(manifest.engagement_id).toBe("ENG-INLINE");
+  });
+
+  it("throws if no manifest source is configured", async () => {
+    await expect(loadManifest()).rejects.toThrow(/No scope manifest source configured/);
+  });
+
+  it("throws if manifest file does not exist", async () => {
+    process.env.SCOPE_MANIFEST_PATH = "/nonexistent/path.json";
+    await expect(loadManifest()).rejects.toThrow();
+  });
+
+  it("throws if manifest JSON is invalid", async () => {
+    process.env.SCOPE_MANIFEST_JSON = "{ not valid json";
+    await expect(loadManifest()).rejects.toThrow();
+  });
+
+  it("throws if manifest fails schema validation", async () => {
+    process.env.SCOPE_MANIFEST_JSON = JSON.stringify({ engagement_id: "ENG-1" });
+    await expect(loadManifest()).rejects.toThrow();
+  });
+});
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/manifest.test.ts`
+Expected: FAIL
+
+- [ ] **Step 4: Implement config.ts**
+
+Create `src/config.ts`:
+
+```typescript
+export interface ProxyConfig {
+  // Manifest sources
+  manifestPath?: string;
+  manifestJson?: string;
+  manifestSecretArn?: string;
+  manifestKeyvaultUri?: string;
+  manifestGcpSecret?: string;
+
+  // Transport
+  transport: "stdio" | "sse";
+  upstreamMcpUrl?: string;
+  upstreamMcpCommand?: string;
+  upstreamMcpArgs?: string[];
+  proxyPort: number;
+
+  // Audit
+  auditLogPath: string;
+
+  // Cloud logging
+  awsLogGroup?: string;
+  awsRegion?: string;
+  azureLogWorkspaceId?: string;
+  azureDcrImmutableId?: string;
+  azureDcrStreamName: string;
+  gcpProject?: string;
+
+  // Optional
+  techniqueMapPath?: string;
+  dnsCacheTtl: number;
+  logLevel: string;
+  proxyVersion: string;
+}
+
+export function loadConfig(): ProxyConfig {
+  return {
+    manifestPath: process.env.SCOPE_MANIFEST_PATH,
+    manifestJson: process.env.SCOPE_MANIFEST_JSON,
+    manifestSecretArn: process.env.SCOPE_MANIFEST_SECRET_ARN,
+    manifestKeyvaultUri: process.env.SCOPE_MANIFEST_KEYVAULT_URI,
+    manifestGcpSecret: process.env.SCOPE_MANIFEST_GCP_SECRET,
+
+    transport: (process.env.MCP_TRANSPORT as "stdio" | "sse") || "stdio",
+    upstreamMcpUrl: process.env.UPSTREAM_MCP_URL,
+    upstreamMcpCommand: process.env.UPSTREAM_MCP_COMMAND,
+    upstreamMcpArgs: process.env.UPSTREAM_MCP_ARGS?.split(","),
+    proxyPort: parseInt(process.env.PROXY_PORT || "9090", 10),
+
+    auditLogPath: process.env.AUDIT_LOG_PATH || "./audit/",
+
+    awsLogGroup: process.env.AWS_LOG_GROUP,
+    awsRegion: process.env.AWS_REGION,
+    azureLogWorkspaceId: process.env.AZURE_LOG_WORKSPACE_ID,
+    azureDcrImmutableId: process.env.AZURE_DCR_IMMUTABLE_ID,
+    azureDcrStreamName: process.env.AZURE_DCR_STREAM_NAME || "Custom-MCPProxyAudit_CL",
+    gcpProject: process.env.GOOGLE_CLOUD_PROJECT,
+
+    techniqueMapPath: process.env.TECHNIQUE_MAP_PATH,
+    dnsCacheTtl: parseInt(process.env.DNS_CACHE_TTL || "60", 10),
+    logLevel: process.env.LOG_LEVEL || "INFO",
+    proxyVersion: process.env.PROXY_VERSION || "0.1.0",
+  };
+}
+```
+
+- [ ] **Step 5: Implement manifest.ts**
+
+Create `src/manifest.ts`:
+
+```typescript
+import { readFile } from "fs/promises";
+import { ScopeManifestSchema, type ScopeManifest } from "./manifest-schema.js";
+
+export async function loadManifest(): Promise<ScopeManifest> {
+  const raw = await loadRawJson();
+  const parsed = ScopeManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(`Scope manifest validation failed: ${parsed.error.message}`);
+  }
+  return parsed.data;
+}
+
+async function loadRawJson(): Promise<unknown> {
+  // 1. Inline JSON
+  if (process.env.SCOPE_MANIFEST_JSON) {
+    return JSON.parse(process.env.SCOPE_MANIFEST_JSON);
+  }
+
+  // 2. Local file
+  if (process.env.SCOPE_MANIFEST_PATH) {
+    const content = await readFile(process.env.SCOPE_MANIFEST_PATH, "utf-8");
+    return JSON.parse(content);
+  }
+
+  // 3. AWS Secrets Manager
+  if (process.env.SCOPE_MANIFEST_SECRET_ARN) {
+    return loadFromAwsSecrets(process.env.SCOPE_MANIFEST_SECRET_ARN);
+  }
+
+  // 4. Azure Key Vault
+  if (process.env.SCOPE_MANIFEST_KEYVAULT_URI) {
+    return loadFromAzureKeyVault(process.env.SCOPE_MANIFEST_KEYVAULT_URI);
+  }
+
+  // 5. GCP Secret Manager
+  if (process.env.SCOPE_MANIFEST_GCP_SECRET) {
+    return loadFromGcpSecrets(process.env.SCOPE_MANIFEST_GCP_SECRET);
+  }
+
+  throw new Error(
+    "No scope manifest source configured. Set one of: SCOPE_MANIFEST_PATH, SCOPE_MANIFEST_JSON, SCOPE_MANIFEST_SECRET_ARN, SCOPE_MANIFEST_KEYVAULT_URI, SCOPE_MANIFEST_GCP_SECRET"
+  );
+}
+
+async function loadFromAwsSecrets(secretArn: string): Promise<unknown> {
+  const { SecretsManagerClient, GetSecretValueCommand } = await import("@aws-sdk/client-secrets-manager");
+  const client = new SecretsManagerClient({});
+  const resp = await client.send(new GetSecretValueCommand({ SecretId: secretArn }));
+  if (!resp.SecretString) throw new Error("AWS secret has no string value");
+  return JSON.parse(resp.SecretString);
+}
+
+async function loadFromAzureKeyVault(secretUri: string): Promise<unknown> {
+  const { SecretClient } = await import("@azure/keyvault-secrets");
+  const { DefaultAzureCredential } = await import("@azure/identity");
+  // Extract vault URL and secret name from URI
+  const url = new URL(secretUri);
+  const vaultUrl = `${url.protocol}//${url.host}`;
+  const secretName = url.pathname.split("/")[2];
+  const client = new SecretClient(vaultUrl, new DefaultAzureCredential());
+  const secret = await client.getSecret(secretName);
+  if (!secret.value) throw new Error("Azure Key Vault secret has no value");
+  return JSON.parse(secret.value);
+}
+
+async function loadFromGcpSecrets(resourceName: string): Promise<unknown> {
+  const { SecretManagerServiceClient } = await import("@google-cloud/secret-manager");
+  const client = new SecretManagerServiceClient();
+  const [version] = await client.accessSecretVersion({ name: resourceName });
+  const payload = version.payload?.data;
+  if (!payload) throw new Error("GCP secret has no payload");
+  const str = typeof payload === "string" ? payload : Buffer.from(payload).toString("utf-8");
+  return JSON.parse(str);
+}
+```
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/manifest.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/config.ts src/manifest.ts tests/unit/manifest.test.ts tests/fixtures/
+git commit -m "feat: add manifest loader with file, env, and cloud secret sources"
+```
+
+---
+
+## Task 11: Local Audit Logger
+
+**Files:**
+- Create: `src/audit/local.ts`
+- Create: `src/audit/index.ts`
+- Test: `tests/unit/audit-local.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/unit/audit-local.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { LocalAuditLogger } from "../../src/audit/local.js";
+import { readFile, rm, mkdir } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import type { AuditEntry } from "../../src/types.js";
+
+const testDir = join(tmpdir(), "mcp-proxy-test-audit-" + Date.now());
+
+const sampleEntry: AuditEntry = {
+  timestamp: "2026-03-26T14:32:01.234Z",
+  engagement_id: "ENG-TEST-001",
+  client: "Test Corp",
+  operator: "test@integsec.com",
+  tool_name: "nmap_scan",
+  tool_parameters: { target: "10.10.10.5", ports: "1-1024" },
+  extracted_target: "10.10.10.5",
+  resolved_ips: ["10.10.10.5"],
+  decision: "ALLOWED",
+  decision_reason: "Target matches authorized range 10.10.10.0/24",
+  matched_scope_item: "10.10.10.0/24",
+  duration_ms: 5,
+  proxy_version: "0.1.0",
+};
+
+describe("LocalAuditLogger", () => {
+  let logger: LocalAuditLogger;
+
+  beforeEach(async () => {
+    await mkdir(testDir, { recursive: true });
+    logger = new LocalAuditLogger(testDir);
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it("writes a JSONL entry to file", async () => {
+    await logger.log(sampleEntry);
+    await logger.flush();
+    const filePath = join(testDir, "ENG-TEST-001.jsonl");
+    const content = await readFile(filePath, "utf-8");
+    const lines = content.trim().split("\n");
+    expect(lines).toHaveLength(1);
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.engagement_id).toBe("ENG-TEST-001");
+    expect(parsed.decision).toBe("ALLOWED");
+  });
+
+  it("appends multiple entries", async () => {
+    await logger.log(sampleEntry);
+    await logger.log({ ...sampleEntry, decision: "BLOCKED_NOT_IN_SCOPE" as const });
+    await logger.flush();
+    const filePath = join(testDir, "ENG-TEST-001.jsonl");
+    const content = await readFile(filePath, "utf-8");
+    const lines = content.trim().split("\n");
+    expect(lines).toHaveLength(2);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run tests/unit/audit-local.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Implement local.ts**
+
+Create `src/audit/local.ts`:
+
+```typescript
+import { appendFile, mkdir } from "fs/promises";
+import { join } from "path";
+import type { AuditEntry } from "../types.js";
+
+export class LocalAuditLogger {
+  private basePath: string;
+  private buffer: Map<string, string[]> = new Map();
+
+  constructor(basePath: string) {
+    this.basePath = basePath;
+  }
+
+  async log(entry: AuditEntry): Promise<void> {
+    const line = JSON.stringify(entry) + "\n";
+    const existing = this.buffer.get(entry.engagement_id) ?? [];
+    existing.push(line);
+    this.buffer.set(entry.engagement_id, existing);
+  }
+
+  async flush(): Promise<void> {
+    await mkdir(this.basePath, { recursive: true });
+    for (const [engagementId, lines] of this.buffer) {
+      const filePath = join(this.basePath, `${engagementId}.jsonl`);
+      await appendFile(filePath, lines.join(""));
+    }
+    this.buffer.clear();
+  }
+}
+```
+
+- [ ] **Step 4: Implement audit/index.ts (facade)**
+
+Create `src/audit/index.ts`:
+
+```typescript
+import type { AuditEntry } from "../types.js";
+import { LocalAuditLogger } from "./local.js";
+
+export interface AuditBackend {
+  log(entry: AuditEntry): Promise<void>;
+  flush(): Promise<void>;
+}
+
+export class AuditLogger {
+  private backends: AuditBackend[] = [];
+  private flushIntervalMs: number;
+  private flushTimer?: ReturnType<typeof setInterval>;
+
+  constructor(localPath: string, flushIntervalMs: number = 5000) {
+    this.backends.push(new LocalAuditLogger(localPath));
+    this.flushIntervalMs = flushIntervalMs;
+  }
+
+  addBackend(backend: AuditBackend): void {
+    this.backends.push(backend);
+  }
+
+  start(): void {
+    this.flushTimer = setInterval(() => this.flush(), this.flushIntervalMs);
+  }
+
+  async log(entry: AuditEntry): Promise<void> {
+    const promises = this.backends.map((b) =>
+      b.log(entry).catch((err) => {
+        console.error(`[mcp-scope-proxy] Audit backend error: ${err.message}`);
+      })
+    );
+    await Promise.all(promises);
+  }
+
+  async flush(): Promise<void> {
+    const promises = this.backends.map((b) =>
+      b.flush().catch((err) => {
+        console.error(`[mcp-scope-proxy] Audit flush error: ${err.message}`);
+      })
+    );
+    await Promise.all(promises);
+  }
+
+  async stop(): Promise<void> {
+    if (this.flushTimer) clearInterval(this.flushTimer);
+    await this.flush();
+  }
+}
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `npx vitest run tests/unit/audit-local.test.ts`
+Expected: All tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/audit/ tests/unit/audit-local.test.ts
+git commit -m "feat: add local JSONL audit logger with flush support"
+```
+
+---
+
+## Task 12: Cloud Audit Backends (AWS, Azure, GCP)
+
+**Files:**
+- Create: `src/audit/cloudwatch.ts`
+- Create: `src/audit/azure-monitor.ts`
+- Create: `src/audit/gcp-logging.ts`
+
+These use optional dependencies and dynamic imports, so they gracefully skip if the cloud SDK isn't installed.
+
+- [ ] **Step 1: Implement cloudwatch.ts**
+
+Create `src/audit/cloudwatch.ts`:
+
+```typescript
+import type { AuditEntry } from "../types.js";
+import type { AuditBackend } from "./index.js";
+
+export class CloudWatchAuditLogger implements AuditBackend {
+  private logGroup: string;
+  private buffer: AuditEntry[] = [];
+  private client: any;
+  private sequenceToken?: string;
+
+  constructor(logGroup: string, region?: string) {
+    this.logGroup = logGroup;
+    this.initClient(region);
+  }
+
+  private async initClient(region?: string): Promise<void> {
+    try {
+      const { CloudWatchLogsClient } = await import("@aws-sdk/client-cloudwatch-logs");
+      this.client = new CloudWatchLogsClient(region ? { region } : {});
+    } catch {
+      console.warn("[mcp-scope-proxy] @aws-sdk/client-cloudwatch-logs not installed, CloudWatch logging disabled");
+    }
+  }
+
+  async log(entry: AuditEntry): Promise<void> {
+    this.buffer.push(entry);
+  }
+
+  async flush(): Promise<void> {
+    if (!this.client || this.buffer.length === 0) return;
+    const entries = this.buffer.splice(0, this.buffer.length);
+
+    try {
+      const { PutLogEventsCommand, CreateLogGroupCommand, CreateLogStreamCommand } = await import(
+        "@aws-sdk/client-cloudwatch-logs"
+      );
+      const logStream = `${entries[0].engagement_id}/${new Date().toISOString().split("T")[0]}`;
+
+      // Ensure log group and stream exist (idempotent)
+      try {
+        await this.client.send(new CreateLogGroupCommand({ logGroupName: this.logGroup }));
+      } catch (e: any) {
+        if (e.name !== "ResourceAlreadyExistsException") throw e;
+      }
+      try {
+        await this.client.send(
+          new CreateLogStreamCommand({ logGroupName: this.logGroup, logStreamName: logStream })
+        );
+      } catch (e: any) {
+        if (e.name !== "ResourceAlreadyExistsException") throw e;
+      }
+
+      await this.client.send(
+        new PutLogEventsCommand({
+          logGroupName: this.logGroup,
+          logStreamName: logStream,
+          logEvents: entries.map((e) => ({
+            timestamp: new Date(e.timestamp).getTime(),
+            message: JSON.stringify(e),
+          })),
+        })
+      );
+    } catch (err: any) {
+      console.error(`[mcp-scope-proxy] CloudWatch flush error: ${err.message}`);
+      // Put entries back for retry
+      this.buffer.unshift(...entries);
+    }
+  }
+}
+```
+
+- [ ] **Step 2: Implement azure-monitor.ts**
+
+Create `src/audit/azure-monitor.ts`:
+
+```typescript
+import type { AuditEntry } from "../types.js";
+import type { AuditBackend } from "./index.js";
+
+export class AzureMonitorAuditLogger implements AuditBackend {
+  private buffer: AuditEntry[] = [];
+  private client: any;
+  private ruleId: string;
+  private streamName: string;
+
+  constructor(workspaceId: string, dcrImmutableId: string, streamName: string) {
+    this.ruleId = dcrImmutableId;
+    this.streamName = streamName;
+    this.initClient(workspaceId);
+  }
+
+  private async initClient(workspaceId: string): Promise<void> {
+    try {
+      const { LogsIngestionClient } = await import("@azure/monitor-ingestion");
+      const { DefaultAzureCredential } = await import("@azure/identity");
+      const endpoint = `https://${workspaceId}.ingest.monitor.azure.com`;
+      this.client = new LogsIngestionClient(endpoint, new DefaultAzureCredential());
+    } catch {
+      console.warn("[mcp-scope-proxy] @azure/monitor-ingestion not installed, Azure Monitor logging disabled");
+    }
+  }
+
+  async log(entry: AuditEntry): Promise<void> {
+    this.buffer.push(entry);
+  }
+
+  async flush(): Promise<void> {
+    if (!this.client || this.buffer.length === 0) return;
+    const entries = this.buffer.splice(0, this.buffer.length);
+
+    try {
+      await this.client.upload(this.ruleId, this.streamName, entries);
+    } catch (err: any) {
+      console.error(`[mcp-scope-proxy] Azure Monitor flush error: ${err.message}`);
+      this.buffer.unshift(...entries);
+    }
+  }
+}
+```
+
+- [ ] **Step 3: Implement gcp-logging.ts**
+
+Create `src/audit/gcp-logging.ts`:
+
+```typescript
+import type { AuditEntry } from "../types.js";
+import type { AuditBackend } from "./index.js";
+
+export class GcpAuditLogger implements AuditBackend {
+  private buffer: AuditEntry[] = [];
+  private log: any;
+
+  constructor(projectId?: string) {
+    this.initClient(projectId);
+  }
+
+  private async initClient(projectId?: string): Promise<void> {
+    try {
+      const { Logging } = await import("@google-cloud/logging");
+      const logging = new Logging(projectId ? { projectId } : {});
+      this.log = logging.log("mcp-proxy-audit");
+    } catch {
+      console.warn("[mcp-scope-proxy] @google-cloud/logging not installed, GCP logging disabled");
+    }
+  }
+
+  async log(entry: AuditEntry): Promise<void> {
+    this.buffer.push(entry);
+  }
+
+  async flush(): Promise<void> {
+    if (!this.log || this.buffer.length === 0) return;
+    const entries = this.buffer.splice(0, this.buffer.length);
+
+    try {
+      const logEntries = entries.map((e) => {
+        const metadata = {
+          resource: { type: "global" },
+          labels: { engagement_id: e.engagement_id, client: e.client },
+          severity: e.decision.startsWith("BLOCKED") ? "WARNING" : "INFO",
+        };
+        return this.log.entry(metadata, e);
+      });
+      await this.log.write(logEntries);
+    } catch (err: any) {
+      console.error(`[mcp-scope-proxy] GCP Logging flush error: ${err.message}`);
+      this.buffer.unshift(...entries);
+    }
+  }
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/audit/cloudwatch.ts src/audit/azure-monitor.ts src/audit/gcp-logging.ts
+git commit -m "feat: add cloud audit backends for CloudWatch, Azure Monitor, and GCP Logging"
+```
+
+---
+
+## Task 13: Core MCP Proxy
+
+**Files:**
+- Create: `src/proxy.ts`
+- Update: `src/index.ts`
+
+- [ ] **Step 1: Implement proxy.ts**
+
+Create `src/proxy.ts`:
+
+```typescript
+import type { ScopeManifest, AuditEntry, Decision } from "./types.js";
+import { ScopeValidator } from "./validator.js";
+import { AuditLogger } from "./audit/index.js";
+import { sanitizeParams } from "./sanitizer.js";
+import { DnsResolver } from "./dns-resolver.js";
+import { TechniqueChecker } from "./technique-checker.js";
+import type { ProxyConfig } from "./config.js";
+
+export class ScopeEnforcementProxy {
+  private validator: ScopeValidator;
+  private auditLogger: AuditLogger;
+  private manifest: ScopeManifest;
+  private config: ProxyConfig;
+
+  constructor(manifest: ScopeManifest, config: ProxyConfig) {
+    this.manifest = manifest;
+    this.config = config;
+
+    const dnsResolver = new DnsResolver(config.dnsCacheTtl);
+    const techniqueChecker = new TechniqueChecker(); // TODO: load custom mappings from config.techniqueMapPath
+    this.validator = new ScopeValidator(manifest, dnsResolver, techniqueChecker);
+    this.auditLogger = new AuditLogger(config.auditLogPath);
+  }
+
+  getAuditLogger(): AuditLogger {
+    return this.auditLogger;
+  }
+
+  /**
+   * Handle an incoming JSON-RPC message. Returns the message to forward (possibly modified),
+   * or an error response if blocked.
+   */
+  async handleMessage(message: unknown): Promise<{ forward: boolean; response?: unknown }> {
+    // Only intercept tools/call requests
+    if (!isToolCallRequest(message)) {
+      return { forward: true };
+    }
+
+    const { id, params } = message as any;
+    const toolName: string = params?.name ?? "unknown";
+    const toolParams: Record<string, unknown> = params?.arguments ?? {};
+
+    const result = await this.validator.validate(toolName, toolParams);
+
+    // Build audit entry
+    const entry: AuditEntry = {
+      timestamp: new Date().toISOString(),
+      engagement_id: this.manifest.engagement_id,
+      client: this.manifest.client,
+      operator: this.manifest.operator,
+      tool_name: toolName,
+      tool_parameters: sanitizeParams(toolParams),
+      extracted_target: result.extractedTarget ?? null,
+      resolved_ips: result.resolvedIps ?? [],
+      decision: result.decision,
+      decision_reason: result.reason,
+      matched_scope_item: result.matchedScopeItem ?? null,
+      duration_ms: result.durationMs,
+      proxy_version: this.config.proxyVersion,
+    };
+
+    // Log asynchronously — never block on logging failure
+    this.auditLogger.log(entry).catch((err) => {
+      console.error(`[mcp-scope-proxy] Failed to log audit entry: ${err.message}`);
+    });
+
+    // If blocked, return error response
+    if (result.decision.startsWith("BLOCKED")) {
+      return {
+        forward: false,
+        response: {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32001,
+            message: `SCOPE_VIOLATION: ${result.reason}. Decision: ${result.decision}.`,
+          },
+        },
+      };
+    }
+
+    // Allowed — forward to upstream
+    return { forward: true };
+  }
+}
+
+function isToolCallRequest(msg: unknown): boolean {
+  if (typeof msg !== "object" || msg === null) return false;
+  const obj = msg as Record<string, unknown>;
+  return obj.method === "tools/call" && obj.jsonrpc === "2.0";
+}
+```
+
+- [ ] **Step 2: Update src/index.ts**
+
+```typescript
+export { ScopeEnforcementProxy } from "./proxy.js";
+export { ScopeValidator } from "./validator.js";
+export { loadManifest } from "./manifest.js";
+export { loadConfig } from "./config.js";
+export { AuditLogger } from "./audit/index.js";
+export type { ScopeManifest, AuditEntry, ValidationResult, Decision } from "./types.js";
+export const VERSION = "0.1.0";
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/proxy.ts src/index.ts
+git commit -m "feat: add core MCP scope enforcement proxy with message interception"
+```
+
+---
+
+## Task 14: stdio Transport
+
+**Files:**
+- Create: `src/transports/stdio.ts`
+
+- [ ] **Step 1: Implement stdio transport**
+
+Create `src/transports/stdio.ts`:
+
+```typescript
+import { spawn, type ChildProcess } from "child_process";
+import { createInterface } from "readline";
+import type { ScopeEnforcementProxy } from "../proxy.js";
+
+export async function runStdioProxy(
+  proxy: ScopeEnforcementProxy,
+  upstreamCommand: string,
+  upstreamArgs: string[] = []
+): Promise<void> {
+  // Spawn the upstream MCP server
+  const upstream: ChildProcess = spawn(upstreamCommand, upstreamArgs, {
+    stdio: ["pipe", "pipe", "inherit"],
+  });
+
+  if (!upstream.stdin || !upstream.stdout) {
+    throw new Error("Failed to open stdio pipes to upstream MCP server");
+  }
+
+  const auditLogger = proxy.getAuditLogger();
+  auditLogger.start();
+
+  // Read lines from agent (our stdin) and process
+  const agentInput = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  const upstreamOutput = createInterface({ input: upstream.stdout, crlfDelay: Infinity });
+
+  // Agent → Proxy → Upstream
+  agentInput.on("line", async (line) => {
+    try {
+      const message = JSON.parse(line);
+      const { forward, response } = await proxy.handleMessage(message);
+      if (forward) {
+        upstream.stdin!.write(line + "\n");
+      } else if (response) {
+        process.stdout.write(JSON.stringify(response) + "\n");
+      }
+    } catch {
+      // Malformed JSON — pass through conservatively
+      upstream.stdin!.write(line + "\n");
+    }
+  });
+
+  // Upstream → Agent (pass through all responses)
+  upstreamOutput.on("line", (line) => {
+    process.stdout.write(line + "\n");
+  });
+
+  // Handle upstream exit
+  upstream.on("exit", async (code) => {
+    await auditLogger.stop();
+    process.exit(code ?? 0);
+  });
+
+  // Handle our own termination
+  process.on("SIGINT", async () => {
+    await auditLogger.stop();
+    upstream.kill();
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", async () => {
+    await auditLogger.stop();
+    upstream.kill();
+    process.exit(0);
+  });
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/transports/stdio.ts
+git commit -m "feat: add stdio transport for proxying MCP over stdin/stdout"
+```
+
+---
+
+## Task 15: HTTP (Streamable HTTP) Transport
+
+**Files:**
+- Create: `src/transports/http.ts`
+
+- [ ] **Step 1: Implement HTTP transport**
+
+Create `src/transports/http.ts`:
+
+```typescript
+import { createServer, type IncomingMessage, type ServerResponse } from "http";
+import type { ScopeEnforcementProxy } from "../proxy.js";
+
+export async function runHttpProxy(
+  proxy: ScopeEnforcementProxy,
+  upstreamUrl: string,
+  port: number
+): Promise<void> {
+  const auditLogger = proxy.getAuditLogger();
+  auditLogger.start();
+
+  const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const body = await readBody(req);
+
+    // Try to parse as JSON-RPC
+    let message: unknown;
+    try {
+      message = JSON.parse(body);
+    } catch {
+      // Not JSON — forward as-is
+      return forwardRaw(upstreamUrl, req, body, res);
+    }
+
+    // Check if this is a tools/call we need to intercept
+    const { forward, response } = await proxy.handleMessage(message);
+
+    if (!forward && response) {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(response));
+      return;
+    }
+
+    // Forward to upstream
+    return forwardRaw(upstreamUrl, req, body, res);
+  });
+
+  server.listen(port, () => {
+    console.error(`[mcp-scope-proxy] HTTP proxy listening on port ${port}, forwarding to ${upstreamUrl}`);
+  });
+
+  process.on("SIGINT", async () => {
+    await auditLogger.stop();
+    server.close();
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", async () => {
+    await auditLogger.stop();
+    server.close();
+    process.exit(0);
+  });
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+async function forwardRaw(
+  upstreamUrl: string,
+  originalReq: IncomingMessage,
+  body: string,
+  clientRes: ServerResponse
+): Promise<void> {
+  try {
+    const url = new URL(originalReq.url ?? "/", upstreamUrl);
+    const headers: Record<string, string> = {};
+    for (const [key, value] of Object.entries(originalReq.headers)) {
+      if (typeof value === "string") headers[key] = value;
+    }
+    // Remove host header to avoid conflicts
+    delete headers.host;
+
+    const resp = await fetch(url.toString(), {
+      method: originalReq.method ?? "POST",
+      headers,
+      body: originalReq.method !== "GET" ? body : undefined,
+    });
+
+    clientRes.writeHead(resp.status, Object.fromEntries(resp.headers.entries()));
+    const respBody = await resp.text();
+    clientRes.end(respBody);
+  } catch (err: any) {
+    clientRes.writeHead(502, { "Content-Type": "application/json" });
+    clientRes.end(JSON.stringify({ error: `Upstream error: ${err.message}` }));
+  }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/transports/http.ts
+git commit -m "feat: add HTTP transport for proxying MCP over Streamable HTTP"
+```
+
+---
+
+## Task 16: CLI Entry Point
+
+**Files:**
+- Create: `bin/mcp-scope-proxy.ts`
+
+- [ ] **Step 1: Implement CLI entry point**
+
+Create `bin/mcp-scope-proxy.ts`:
+
+```typescript
+#!/usr/bin/env node
+
+import { loadConfig } from "../src/config.js";
+import { loadManifest } from "../src/manifest.js";
+import { ScopeEnforcementProxy } from "../src/proxy.js";
+import { runStdioProxy } from "../src/transports/stdio.js";
+import { runHttpProxy } from "../src/transports/http.js";
+import { CloudWatchAuditLogger } from "../src/audit/cloudwatch.js";
+import { AzureMonitorAuditLogger } from "../src/audit/azure-monitor.js";
+import { GcpAuditLogger } from "../src/audit/gcp-logging.js";
+
+async function main(): Promise<void> {
+  console.error("[mcp-scope-proxy] Starting...");
+
+  const config = loadConfig();
+  const manifest = await loadManifest();
+
+  console.error(`[mcp-scope-proxy] Loaded scope for engagement ${manifest.engagement_id} (${manifest.client})`);
+  console.error(`[mcp-scope-proxy] Window: ${manifest.engagement_window.start} to ${manifest.engagement_window.end}`);
+  console.error(`[mcp-scope-proxy] Transport: ${config.transport}`);
+
+  const proxy = new ScopeEnforcementProxy(manifest, config);
+  const auditLogger = proxy.getAuditLogger();
+
+  // Add cloud backends if configured
+  if (config.awsLogGroup) {
+    auditLogger.addBackend(new CloudWatchAuditLogger(config.awsLogGroup, config.awsRegion));
+    console.error(`[mcp-scope-proxy] CloudWatch logging enabled: ${config.awsLogGroup}`);
+  }
+  if (config.azureLogWorkspaceId && config.azureDcrImmutableId) {
+    auditLogger.addBackend(
+      new AzureMonitorAuditLogger(config.azureLogWorkspaceId, config.azureDcrImmutableId, config.azureDcrStreamName)
+    );
+    console.error("[mcp-scope-proxy] Azure Monitor logging enabled");
+  }
+  if (config.gcpProject) {
+    auditLogger.addBackend(new GcpAuditLogger(config.gcpProject));
+    console.error("[mcp-scope-proxy] GCP Cloud Logging enabled");
+  }
+
+  if (config.transport === "stdio") {
+    if (!config.upstreamMcpCommand) {
+      console.error("[mcp-scope-proxy] ERROR: UPSTREAM_MCP_COMMAND is required for stdio transport");
+      process.exit(1);
+    }
+    await runStdioProxy(proxy, config.upstreamMcpCommand, config.upstreamMcpArgs);
+  } else {
+    if (!config.upstreamMcpUrl) {
+      console.error("[mcp-scope-proxy] ERROR: UPSTREAM_MCP_URL is required for HTTP transport");
+      process.exit(1);
+    }
+    await runHttpProxy(proxy, config.upstreamMcpUrl, config.proxyPort);
+  }
+}
+
+main().catch((err) => {
+  console.error(`[mcp-scope-proxy] Fatal error: ${err.message}`);
+  process.exit(1);
+});
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add bin/mcp-scope-proxy.ts
+git commit -m "feat: add CLI entry point with transport and cloud backend wiring"
+```
+
+---
+
+## Task 17: Integration Test
+
+**Files:**
+- Create: `tests/integration/proxy.test.ts`
+- Create: `tests/fixtures/tool-calls.json`
+
+- [ ] **Step 1: Create tool call fixtures**
+
+Create `tests/fixtures/tool-calls.json`:
+
+```json
+{
+  "allowed_nmap": {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "nmap_scan",
+      "arguments": { "target": "10.10.10.50", "ports": "1-1024" }
+    }
+  },
+  "blocked_out_of_scope": {
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/call",
+    "params": {
+      "name": "nmap_scan",
+      "arguments": { "target": "192.168.99.1", "ports": "1-1024" }
+    }
+  },
+  "blocked_excluded": {
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "tools/call",
+    "params": {
+      "name": "nmap_scan",
+      "arguments": { "target": "203.0.113.5" }
+    }
+  },
+  "blocked_technique": {
+    "jsonrpc": "2.0",
+    "id": 4,
+    "method": "tools/call",
+    "params": {
+      "name": "slowloris",
+      "arguments": { "target": "10.10.10.50" }
+    }
+  },
+  "pass_through_list": {
+    "jsonrpc": "2.0",
+    "id": 5,
+    "method": "tools/list",
+    "params": {}
+  },
+  "no_target_tool": {
+    "jsonrpc": "2.0",
+    "id": 6,
+    "method": "tools/call",
+    "params": {
+      "name": "list_tools",
+      "arguments": { "verbose": true }
+    }
+  }
+}
+```
+
+- [ ] **Step 2: Write integration tests**
+
+Create `tests/integration/proxy.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { ScopeEnforcementProxy } from "../../src/proxy.js";
+import type { ScopeManifest } from "../../src/types.js";
+import { rm } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import toolCalls from "../fixtures/tool-calls.json";
+
+const auditDir = join(tmpdir(), "mcp-proxy-integration-" + Date.now());
+
+const manifest: ScopeManifest = {
+  engagement_id: "ENG-INT-TEST",
+  client: "Integration Test Corp",
+  operator: "test@integsec.com",
+  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"],
+    cloud_accounts: [],
+  },
+  excluded_targets: ["203.0.113.5", "hr.acme.com"],
+  authorized_techniques: ["recon", "web_app"],
+  excluded_techniques: ["dos", "destructive", "social_engineering"],
+  engagement_window: {
+    start: "2020-01-01T00:00:00Z",
+    end: "2099-12-31T23:59:59Z",
+  },
+};
+
+describe("ScopeEnforcementProxy integration", () => {
+  let proxy: ScopeEnforcementProxy;
+
+  beforeEach(() => {
+    proxy = new ScopeEnforcementProxy(manifest, {
+      transport: "stdio",
+      auditLogPath: auditDir,
+      proxyPort: 9090,
+      azureDcrStreamName: "test",
+      dnsCacheTtl: 60,
+      logLevel: "INFO",
+      proxyVersion: "0.1.0-test",
+    });
+  });
+
+  afterEach(async () => {
+    await proxy.getAuditLogger().stop();
+    await rm(auditDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it("allows in-scope nmap scan", async () => {
+    const result = await proxy.handleMessage(toolCalls.allowed_nmap);
+    expect(result.forward).toBe(true);
+    expect(result.response).toBeUndefined();
+  });
+
+  it("blocks out-of-scope target", async () => {
+    const result = await proxy.handleMessage(toolCalls.blocked_out_of_scope);
+    expect(result.forward).toBe(false);
+    expect((result.response as any).error.code).toBe(-32001);
+    expect((result.response as any).error.message).toContain("BLOCKED_NOT_IN_SCOPE");
+  });
+
+  it("blocks excluded target", async () => {
+    const result = await proxy.handleMessage(toolCalls.blocked_excluded);
+    expect(result.forward).toBe(false);
+    expect((result.response as any).error.message).toContain("BLOCKED_EXCLUDED_TARGET");
+  });
+
+  it("blocks blocked technique", async () => {
+    const result = await proxy.handleMessage(toolCalls.blocked_technique);
+    expect(result.forward).toBe(false);
+    expect((result.response as any).error.message).toContain("BLOCKED_TECHNIQUE");
+  });
+
+  it("passes through non-tools/call messages", async () => {
+    const result = await proxy.handleMessage(toolCalls.pass_through_list);
+    expect(result.forward).toBe(true);
+  });
+
+  it("allows tool with no target parameter", async () => {
+    const result = await proxy.handleMessage(toolCalls.no_target_tool);
+    expect(result.forward).toBe(true);
+  });
+
+  it("preserves JSON-RPC id in blocked response", async () => {
+    const result = await proxy.handleMessage(toolCalls.blocked_out_of_scope);
+    expect((result.response as any).id).toBe(2);
+    expect((result.response as any).jsonrpc).toBe("2.0");
+  });
+});
+```
+
+- [ ] **Step 3: Run all tests**
+
+Run: `npx vitest run`
+Expected: All unit and integration tests pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/integration/ tests/fixtures/tool-calls.json
+git commit -m "test: add integration tests for proxy message handling"
+```
+
+---
+
+## Task 18: Examples and Claude Desktop Config
+
+**Files:**
+- Create: `examples/scope-manifest.json`
+- Create: `examples/technique-map.json`
+- Create: `examples/claude-desktop-config.json`
+
+- [ ] **Step 1: Create example scope manifest**
+
+Create `examples/scope-manifest.json`:
+
+```json
+{
+  "engagement_id": "ENG-2025-0142",
+  "client": "Acme Corp",
+  "operator": "operator@integsec.com",
+  "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", "azure:sub-xxxx"]
+  },
+  "excluded_targets": ["203.0.113.5", "hr.acme.com"],
+  "authorized_techniques": ["recon", "web_app", "api_testing"],
+  "excluded_techniques": ["dos", "destructive", "social_engineering"],
+  "engagement_window": {
+    "start": "2026-03-26T08:00:00Z",
+    "end": "2026-04-09T17:00:00Z"
+  }
+}
+```
+
+- [ ] **Step 2: Create example technique map**
+
+Create `examples/technique-map.json`:
+
+```json
+{
+  "wireless": {
+    "exact": ["aircrack-ng", "wifite", "kismet"],
+    "patterns": ["wifi", "wireless"]
+  },
+  "physical": {
+    "exact": ["lockpick_sim"],
+    "patterns": ["physical"]
+  }
+}
+```
+
+- [ ] **Step 3: Create Claude Desktop config example**
+
+Create `examples/claude-desktop-config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kali-mcp-scoped": {
+      "command": "npx",
+      "args": ["-y", "mcp-scope-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/"
+      }
+    }
+  }
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add examples/
+git commit -m "docs: add example scope manifest, technique map, and Claude Desktop config"
+```
+
+---
+
+## Task 19: Dockerfile
+
+**Files:**
+- Create: `Dockerfile`
+
+- [ ] **Step 1: Create Dockerfile**
+
+```dockerfile
+FROM node:20-slim AS builder
+
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY tsconfig.json ./
+COPY src/ ./src/
+COPY bin/ ./bin/
+RUN npm run build
+
+FROM node:20-slim
+
+RUN groupadd -r mcpproxy && useradd -r -g mcpproxy mcpproxy
+
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+COPY --from=builder /app/dist ./dist
+
+USER mcpproxy
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+  CMD node -e "process.exit(0)"
+
+ENTRYPOINT ["node", "dist/bin/mcp-scope-proxy.js"]
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add Dockerfile
+git commit -m "chore: add Dockerfile with non-root user and health check"
+```
+
+---
+
+## Task 20: Push to GitHub
+
+- [ ] **Step 1: Run full test suite**
+
+Run: `npm test`
+Expected: All tests pass.
+
+- [ ] **Step 2: Build**
+
+Run: `npm run build`
+Expected: `dist/` directory created with no errors.
+
+- [ ] **Step 3: Push to remote**
+
+```bash
+git push -u origin main
+```
+
+---
+
+## Summary of test coverage vs. acceptance criteria
+
+| Acceptance Criteria | Covered In |
+|---|---|
+| IP in authorized CIDR passes through | `validator.test.ts`, `proxy.test.ts` |
+| Out-of-scope IP blocked with MCP error | `validator.test.ts`, `proxy.test.ts` |
+| Excluded target blocked even if in range | `validator.test.ts`, `proxy.test.ts` |
+| Outside time window blocked | `validator.test.ts` |
+| Blocked technique blocked regardless | `validator.test.ts`, `proxy.test.ts` |
+| Local JSONL audit file | `audit-local.test.ts` |
+| Cloud logging integrations | `cloudwatch.ts`, `azure-monitor.ts`, `gcp-logging.ts` (runtime) |
+| Logging failures don't affect decisions | `audit/index.ts` error catching |
+| DNS failure causes block | `validator.test.ts` |
+| Credentials never logged | `sanitizer.test.ts` |
+| All pytest tests pass | N/A (vitest) — `npm test` |
+| Docker image builds | `Dockerfile` |
+| Claude Desktop config example | `examples/claude-desktop-config.json` |