@integsec/agentic-pentest-proxy 0.1.0

package/dist/src/technique-checker.js

@@ -0,0 +1,110 @@
+/**
+ * TechniqueChecker
+ *
+ * Maps tool names to technique categories using exact-match lists and
+ * substring patterns. All comparisons are case-insensitive.
+ *
+ * Default categories:
+ *   dos              — denial-of-service flooding tools
+ *   destructive      — data-wiping / destructive tools
+ *   social_engineering — phishing / credential-harvesting frameworks
+ *
+ * Custom mappings passed to the constructor are merged with the defaults
+ * (they do not replace them). Both exact lists and patterns are extended
+ * per-category.
+ */
+// ---------------------------------------------------------------------------
+// Default technique map
+// ---------------------------------------------------------------------------
+const DEFAULT_MAPPINGS = {
+    dos: {
+        exact: ["hping3", "slowloris", "udpflood", "synflood"],
+        patterns: ["flood", "dos"],
+    },
+    destructive: {
+        exact: [],
+        patterns: ["destroy", "wipe", "wiper"],
+    },
+    social_engineering: {
+        exact: ["gophish", "setoolkit", "evilginx", "modlishka"],
+        patterns: [],
+    },
+};
+// ---------------------------------------------------------------------------
+// TechniqueChecker class
+// ---------------------------------------------------------------------------
+export class TechniqueChecker {
+    mappings;
+    /**
+     * @param customMappings  Optional extra mappings to merge on top of the
+     *                        defaults. Keys that already exist in the defaults
+     *                        have their `exact` and `patterns` arrays extended;
+     *                        new keys add entirely new categories.
+     */
+    constructor(customMappings) {
+        this.mappings = TechniqueChecker.mergeMappings(DEFAULT_MAPPINGS, customMappings ?? {});
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Returns the technique category that `toolName` belongs to, or `null` if
+     * no category matches.
+     */
+    getCategory(toolName) {
+        if (toolName === "")
+            return null;
+        const lower = toolName.toLowerCase();
+        for (const [category, mapping] of Object.entries(this.mappings)) {
+            // 1. Exact match (O(n) over a small list — acceptable)
+            if (mapping.exact.some((name) => name.toLowerCase() === lower)) {
+                return category;
+            }
+            // 2. Substring pattern match
+            if (mapping.patterns.some((pattern) => lower.includes(pattern.toLowerCase()))) {
+                return category;
+            }
+        }
+        return null;
+    }
+    /**
+     * Returns `true` when `toolName` belongs to a category that appears in
+     * `excludedTechniques`, `false` otherwise (including when the tool is not
+     * categorised).
+     */
+    isBlocked(toolName, excludedTechniques) {
+        if (excludedTechniques.length === 0)
+            return false;
+        const category = this.getCategory(toolName);
+        if (category === null)
+            return false;
+        return excludedTechniques.includes(category);
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Merges `custom` mappings into `base`, extending per-category arrays rather
+     * than replacing them. Returns a deep-copied result so the originals are
+     * never mutated.
+     */
+    static mergeMappings(base, custom) {
+        // Deep-copy base
+        const merged = {};
+        for (const [cat, mapping] of Object.entries(base)) {
+            merged[cat] = { exact: [...mapping.exact], patterns: [...mapping.patterns] };
+        }
+        // Merge / extend with custom entries
+        for (const [cat, mapping] of Object.entries(custom)) {
+            if (merged[cat] === undefined) {
+                merged[cat] = { exact: [...mapping.exact], patterns: [...mapping.patterns] };
+            }
+            else {
+                merged[cat].exact.push(...mapping.exact);
+                merged[cat].patterns.push(...mapping.patterns);
+            }
+        }
+        return merged;
+    }
+}
+//# sourceMappingURL=technique-checker.js.map

package/dist/src/technique-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"technique-checker.js","sourceRoot":"","sources":["../../src/technique-checker.ts"],"names":[],"mappings":"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"}

package/dist/src/transports/http.d.ts

@@ -0,0 +1,3 @@
+import type { ScopeEnforcementProxy } from "../proxy.js";
+export declare function runHttpProxy(proxy: ScopeEnforcementProxy, upstreamUrl: string, port: number): Promise<void>;
+//# sourceMappingURL=http.d.ts.map

package/dist/src/transports/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/transports/http.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,wBAAsB,YAAY,CAChC,KAAK,EAAE,qBAAqB,EAC5B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAwCf"}

package/dist/src/transports/http.js

@@ -0,0 +1,67 @@
+import { createServer } from "http";
+export async function runHttpProxy(proxy, upstreamUrl, port) {
+    const auditLogger = proxy.getAuditLogger();
+    auditLogger.start();
+    const server = createServer(async (req, res) => {
+        const body = await readBody(req);
+        let message;
+        try {
+            message = JSON.parse(body);
+        }
+        catch {
+            return forwardRaw(upstreamUrl, req, body, res);
+        }
+        const { forward, response } = await proxy.handleMessage(message);
+        if (!forward && response) {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(response));
+            return;
+        }
+        return forwardRaw(upstreamUrl, req, body, res);
+    });
+    server.listen(port, () => {
+        console.error(`[integsec-agentic-pentest-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) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.on("error", reject);
+    });
+}
+async function forwardRaw(upstreamUrl, originalReq, body, clientRes) {
+    try {
+        const url = new URL(originalReq.url ?? "/", upstreamUrl);
+        const headers = {};
+        for (const [key, value] of Object.entries(originalReq.headers)) {
+            if (typeof value === "string")
+                headers[key] = value;
+        }
+        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) {
+        clientRes.writeHead(502, { "Content-Type": "application/json" });
+        clientRes.end(JSON.stringify({ error: `Upstream error: ${err.message}` }));
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/src/transports/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/transports/http.ts"],"names":[],"mappings":"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"}

package/dist/src/transports/stdio.d.ts

@@ -0,0 +1,3 @@
+import type { ScopeEnforcementProxy } from "../proxy.js";
+export declare function runStdioProxy(proxy: ScopeEnforcementProxy, upstreamCommand: string, upstreamArgs?: string[]): Promise<void>;
+//# sourceMappingURL=stdio.d.ts.map

package/dist/src/transports/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../../src/transports/stdio.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,wBAAsB,aAAa,CACjC,KAAK,EAAE,qBAAqB,EAC5B,eAAe,EAAE,MAAM,EACvB,YAAY,GAAE,MAAM,EAAO,GAC1B,OAAO,CAAC,IAAI,CAAC,CAoDf"}

package/dist/src/transports/stdio.js

@@ -0,0 +1,50 @@
+import { spawn } from "child_process";
+import { createInterface } from "readline";
+export async function runStdioProxy(proxy, upstreamCommand, upstreamArgs = []) {
+    const upstream = 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();
+    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");
+    });
+    upstream.on("exit", async (code) => {
+        await auditLogger.stop();
+        process.exit(code ?? 0);
+    });
+    process.on("SIGINT", async () => {
+        await auditLogger.stop();
+        upstream.kill();
+        process.exit(0);
+    });
+    process.on("SIGTERM", async () => {
+        await auditLogger.stop();
+        upstream.kill();
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=stdio.js.map

package/dist/src/transports/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../../src/transports/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAqB,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG3C,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAA4B,EAC5B,eAAuB,EACvB,eAAyB,EAAE;IAE3B,MAAM,QAAQ,GAAiB,KAAK,CAAC,eAAe,EAAE,YAAY,EAAE;QAClE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC;KACnC,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,cAAc,EAAE,CAAC;IAC3C,WAAW,CAAC,KAAK,EAAE,CAAC;IAEpB,MAAM,UAAU,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClF,MAAM,cAAc,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IAExF,2BAA2B;IAC3B,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACnC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YACjE,IAAI,OAAO,EAAE,CAAC;gBACZ,QAAQ,CAAC,KAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;YACrC,CAAC;iBAAM,IAAI,QAAQ,EAAE,CAAC;gBACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,+CAA+C;YAC/C,QAAQ,CAAC,KAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,gDAAgD;IAChD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACjC,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC;QACzB,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QAC/B,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC;QACzB,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,43 @@
+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;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAChB,SAAS,GACT,yBAAyB,GACzB,sBAAsB,GACtB,wBAAwB,GACxB,mBAAmB,GACnB,oBAAoB,GACpB,mBAAmB,CAAC;AAExB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE;QAClB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;IACF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,iBAAiB,EAAE;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;CACH"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/src/validator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * validator.ts
+ *
+ * ScopeValidator — the core orchestrator that ties all validation together.
+ *
+ * Validation steps (in exact order):
+ *  1. Technique block check
+ *  2. Time window check
+ *  3. Target extraction
+ *  4. If no target found → ALLOWED_NO_TARGET
+ *  5. DNS resolution (fail closed on NXDOMAIN)
+ *  6. Exclusion check (exclusions win over authorizations)
+ *  7. Authorization check (domain pattern match OR IP CIDR match)
+ *  8. No match → BLOCKED_NOT_IN_SCOPE
+ *
+ * SECURITY NOTE: This module is the gatekeeper for all tool calls. Every
+ * check order matters — do not reorder without updating tests.
+ */
+import type { ScopeManifest, ValidationResult } from "./types.js";
+import { DnsResolver } from "./dns-resolver.js";
+import { TechniqueChecker } from "./technique-checker.js";
+export declare class ScopeValidator {
+    private readonly manifest;
+    private readonly dnsResolver;
+    private readonly techniqueChecker;
+    constructor(manifest: ScopeManifest, dnsResolver?: DnsResolver, techniqueChecker?: TechniqueChecker);
+    validate(toolName: string, params: Record<string, unknown>): Promise<ValidationResult>;
+    /**
+     * Check whether `target` matches any entry in `excluded` (case-insensitive
+     * exact string match).
+     */
+    private isExcluded;
+    /**
+     * Find the first authorized domain pattern that matches `hostname`.
+     * Returns the matching pattern string, or null if no match.
+     */
+    private findMatchingDomain;
+    /**
+     * Find the first authorized CIDR range that contains `ip`.
+     * Returns the matching CIDR string, or null if no match.
+     *
+     * Note: RFC-1918 and cloud metadata IPs are only allowed if they explicitly
+     * appear within an authorized ip_range entry.  This function performs an
+     * exact `isIpInCidr` check — there is no implicit deny for private ranges
+     * because the exclusion of a private IP from the authorized list naturally
+     * means it will fall through to BLOCKED_NOT_IN_SCOPE in Step 8.
+     */
+    private findMatchingIpRange;
+    /**
+     * Build a ValidationResult, automatically populating durationMs.
+     */
+    private result;
+}
+//# sourceMappingURL=validator.d.ts.map

package/dist/src/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAElE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;gBAGlD,QAAQ,EAAE,aAAa,EACvB,WAAW,CAAC,EAAE,WAAW,EACzB,gBAAgB,CAAC,EAAE,gBAAgB;IAO/B,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,gBAAgB,CAAC;IA0I5B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAKlB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;OAEG;IACH,OAAO,CAAC,MAAM;CASf"}

package/dist/src/validator.js

@@ -0,0 +1,200 @@
+/**
+ * validator.ts
+ *
+ * ScopeValidator — the core orchestrator that ties all validation together.
+ *
+ * Validation steps (in exact order):
+ *  1. Technique block check
+ *  2. Time window check
+ *  3. Target extraction
+ *  4. If no target found → ALLOWED_NO_TARGET
+ *  5. DNS resolution (fail closed on NXDOMAIN)
+ *  6. Exclusion check (exclusions win over authorizations)
+ *  7. Authorization check (domain pattern match OR IP CIDR match)
+ *  8. No match → BLOCKED_NOT_IN_SCOPE
+ *
+ * SECURITY NOTE: This module is the gatekeeper for all tool calls. Every
+ * check order matters — do not reorder without updating tests.
+ */
+import { extractTarget } from "./extractor.js";
+import { DnsResolver } from "./dns-resolver.js";
+import { isIpInCidr } from "./ip-matcher.js";
+import { matchesDomain } from "./domain-matcher.js";
+import { TechniqueChecker } from "./technique-checker.js";
+export class ScopeValidator {
+    manifest;
+    dnsResolver;
+    techniqueChecker;
+    constructor(manifest, dnsResolver, techniqueChecker) {
+        this.manifest = manifest;
+        this.dnsResolver = dnsResolver ?? new DnsResolver();
+        this.techniqueChecker = techniqueChecker ?? new TechniqueChecker();
+    }
+    async validate(toolName, params) {
+        const startTime = Date.now();
+        // ─────────────────────────────────────────────────────────────────────────
+        // Step 1: Technique block check
+        // ─────────────────────────────────────────────────────────────────────────
+        if (this.techniqueChecker.isBlocked(toolName, this.manifest.excluded_techniques)) {
+            const category = this.techniqueChecker.getCategory(toolName) ?? "unknown";
+            return this.result(startTime, {
+                decision: "BLOCKED_TECHNIQUE",
+                reason: `Tool "${toolName}" belongs to the blocked technique category "${category}".`,
+            });
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Step 2: Time window check
+        // ─────────────────────────────────────────────────────────────────────────
+        const now = Date.now();
+        const windowStart = Date.parse(this.manifest.engagement_window.start);
+        const windowEnd = Date.parse(this.manifest.engagement_window.end);
+        if (now < windowStart || now > windowEnd) {
+            return this.result(startTime, {
+                decision: "BLOCKED_OUTSIDE_WINDOW",
+                reason: `Current time is outside the engagement window (${this.manifest.engagement_window.start} – ${this.manifest.engagement_window.end}).`,
+            });
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Step 3: Target extraction
+        // ─────────────────────────────────────────────────────────────────────────
+        const extraction = extractTarget(toolName, params);
+        // ─────────────────────────────────────────────────────────────────────────
+        // Step 4: If no target found → ALLOWED_NO_TARGET
+        // ─────────────────────────────────────────────────────────────────────────
+        if (extraction === null) {
+            return this.result(startTime, {
+                decision: "ALLOWED_NO_TARGET",
+                reason: "No target-like parameter found in tool call; allowing by default.",
+            });
+        }
+        const target = extraction.target;
+        // ─────────────────────────────────────────────────────────────────────────
+        // Step 5: DNS resolution
+        // ─────────────────────────────────────────────────────────────────────────
+        const resolvedIps = await this.dnsResolver.resolve(target);
+        // For hostnames (not raw IPs), an empty resolution means NXDOMAIN — fail closed.
+        // For raw IPs the resolver returns [ip] so resolvedIps will never be empty.
+        if (resolvedIps.length === 0) {
+            return this.result(startTime, {
+                decision: "BLOCKED_DNS_FAILED",
+                reason: `DNS resolution for "${target}" returned no addresses (NXDOMAIN or resolution failure). Failing closed.`,
+                extractedTarget: target,
+                resolvedIps: [],
+            });
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Step 6: Exclusion check (exclusions win — checked before authorization)
+        // ─────────────────────────────────────────────────────────────────────────
+        const excluded = this.manifest.excluded_targets;
+        // Check hostname/IP target against excluded list (case-insensitive exact match)
+        if (this.isExcluded(target, excluded)) {
+            return this.result(startTime, {
+                decision: "BLOCKED_EXCLUDED_TARGET",
+                reason: `Target "${target}" matches an excluded target.`,
+                extractedTarget: target,
+                resolvedIps,
+            });
+        }
+        // Check each resolved IP against excluded list
+        for (const ip of resolvedIps) {
+            if (this.isExcluded(ip, excluded)) {
+                return this.result(startTime, {
+                    decision: "BLOCKED_EXCLUDED_TARGET",
+                    reason: `Resolved IP "${ip}" for target "${target}" matches an excluded target.`,
+                    extractedTarget: target,
+                    resolvedIps,
+                });
+            }
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Step 7: Authorization check
+        // ─────────────────────────────────────────────────────────────────────────
+        const authorizedIpRanges = this.manifest.authorized_targets.ip_ranges;
+        const authorizedDomains = this.manifest.authorized_targets.domains;
+        // 7a: Check hostname against authorized domain patterns
+        const matchedDomain = this.findMatchingDomain(target, authorizedDomains);
+        if (matchedDomain !== null) {
+            return this.result(startTime, {
+                decision: "ALLOWED",
+                reason: `Target "${target}" matches authorized domain pattern "${matchedDomain}".`,
+                matchedScopeItem: matchedDomain,
+                extractedTarget: target,
+                resolvedIps,
+            });
+        }
+        // 7b: Check resolved IPs against authorized IP ranges.
+        //     For RFC-1918 and cloud metadata IPs: only allow if explicitly in authorized ip_ranges.
+        for (const ip of resolvedIps) {
+            const matchedRange = this.findMatchingIpRange(ip, authorizedIpRanges);
+            if (matchedRange !== null) {
+                return this.result(startTime, {
+                    decision: "ALLOWED",
+                    reason: `Resolved IP "${ip}" for target "${target}" is in authorized range "${matchedRange}".`,
+                    matchedScopeItem: matchedRange,
+                    extractedTarget: target,
+                    resolvedIps,
+                });
+            }
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Step 8: No match → BLOCKED_NOT_IN_SCOPE
+        // ─────────────────────────────────────────────────────────────────────────
+        return this.result(startTime, {
+            decision: "BLOCKED_NOT_IN_SCOPE",
+            reason: `Target "${target}" (resolved IPs: ${resolvedIps.join(", ")}) does not match any authorized target or domain.`,
+            extractedTarget: target,
+            resolvedIps,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Check whether `target` matches any entry in `excluded` (case-insensitive
+     * exact string match).
+     */
+    isExcluded(target, excluded) {
+        const lower = target.toLowerCase();
+        return excluded.some((entry) => entry.toLowerCase() === lower);
+    }
+    /**
+     * Find the first authorized domain pattern that matches `hostname`.
+     * Returns the matching pattern string, or null if no match.
+     */
+    findMatchingDomain(hostname, patterns) {
+        for (const pattern of patterns) {
+            if (matchesDomain(hostname, pattern)) {
+                return pattern;
+            }
+        }
+        return null;
+    }
+    /**
+     * Find the first authorized CIDR range that contains `ip`.
+     * Returns the matching CIDR string, or null if no match.
+     *
+     * Note: RFC-1918 and cloud metadata IPs are only allowed if they explicitly
+     * appear within an authorized ip_range entry.  This function performs an
+     * exact `isIpInCidr` check — there is no implicit deny for private ranges
+     * because the exclusion of a private IP from the authorized list naturally
+     * means it will fall through to BLOCKED_NOT_IN_SCOPE in Step 8.
+     */
+    findMatchingIpRange(ip, ranges) {
+        for (const range of ranges) {
+            if (isIpInCidr(ip, range)) {
+                return range;
+            }
+        }
+        return null;
+    }
+    /**
+     * Build a ValidationResult, automatically populating durationMs.
+     */
+    result(startTime, fields) {
+        return {
+            ...fields,
+            durationMs: Date.now() - startTime,
+        };
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/src/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/validator.ts"],"names":[],"mappings":"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"}

package/examples/claude-desktop-config.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "kali-mcp-scoped": {
+      "command": "npx",
+      "args": ["-y", "@integsec/agentic-pentest-proxy"],
+      "env": {
+        "SCOPE_MANIFEST_PATH": "/path/to/scope.json",
+        "MCP_TRANSPORT": "stdio",
+        "UPSTREAM_MCP_COMMAND": "npx",
+        "UPSTREAM_MCP_ARGS": "-y,@anthropic/kali-mcp",
+        "AUDIT_LOG_PATH": "./audit/"
+      }
+    }
+  }
+}

package/examples/scope-manifest.json

@@ -0,0 +1,18 @@
+{
+  "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"
+  }
+}

package/examples/technique-map.json

@@ -0,0 +1,10 @@
+{
+  "wireless": {
+    "exact": ["aircrack-ng", "wifite", "kismet"],
+    "patterns": ["wifi", "wireless"]
+  },
+  "physical": {
+    "exact": ["lockpick_sim"],
+    "patterns": ["physical"]
+  }
+}