@integsec/agentic-pentest-proxy 0.1.0

package/dist/src/config.js

@@ -0,0 +1,26 @@
+export function loadConfig() {
+    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 || "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",
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAwBA,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;QAC7C,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;QAC7C,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB;QACxD,mBAAmB,EAAE,OAAO,CAAC,GAAG,CAAC,2BAA2B;QAC5D,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB;QACxD,SAAS,EAAG,OAAO,CAAC,GAAG,CAAC,aAAiC,IAAI,OAAO;QACpE,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAC5C,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;QACpD,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,KAAK,CAAC,GAAG,CAAC;QAC1D,SAAS,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,MAAM,EAAE,EAAE,CAAC;QACzD,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,UAAU;QACtD,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa;QACtC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU;QACjC,mBAAmB,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB;QACvD,mBAAmB,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB;QACvD,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,yBAAyB;QAClF,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;QAC5C,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB;QAChD,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,IAAI,EAAE,EAAE,CAAC;QAC5D,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;QACzC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO;KACnD,CAAC;AACJ,CAAC"}

package/dist/src/dns-resolver.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DNS resolver with TTL-based caching.
+ *
+ * - Raw IP addresses are returned immediately without any DNS lookup.
+ * - Both A (IPv4) and AAAA (IPv6) records are resolved in parallel.
+ * - Results are cached for `ttlSeconds`; a TTL of 0 disables caching.
+ * - If both record types fail the method returns an empty array (never throws).
+ * - In-flight requests for the same hostname are de-duplicated so that
+ *   concurrent callers share a single DNS round-trip.
+ */
+export declare class DnsResolver {
+    private readonly ttlMs;
+    private readonly cache;
+    /** Promises for in-flight lookups, keyed by hostname. */
+    private readonly inflight;
+    constructor(ttlSeconds?: number);
+    resolve(target: string): Promise<string[]>;
+    /** Perform the actual A + AAAA DNS queries in parallel. Never throws. */
+    private _lookup;
+}
+//# sourceMappingURL=dns-resolver.d.ts.map

package/dist/src/dns-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns-resolver.d.ts","sourceRoot":"","sources":["../../src/dns-resolver.ts"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;gBAErD,UAAU,GAAE,MAAW;IAI7B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAoChD,yEAAyE;YAC3D,OAAO;CAkBtB"}

package/dist/src/dns-resolver.js

@@ -0,0 +1,68 @@
+import { isIP } from "net";
+import dns from "dns/promises";
+/**
+ * DNS resolver with TTL-based caching.
+ *
+ * - Raw IP addresses are returned immediately without any DNS lookup.
+ * - Both A (IPv4) and AAAA (IPv6) records are resolved in parallel.
+ * - Results are cached for `ttlSeconds`; a TTL of 0 disables caching.
+ * - If both record types fail the method returns an empty array (never throws).
+ * - In-flight requests for the same hostname are de-duplicated so that
+ *   concurrent callers share a single DNS round-trip.
+ */
+export class DnsResolver {
+    ttlMs;
+    cache = new Map();
+    /** Promises for in-flight lookups, keyed by hostname. */
+    inflight = new Map();
+    constructor(ttlSeconds = 60) {
+        this.ttlMs = ttlSeconds * 1000;
+    }
+    async resolve(target) {
+        // 1. Raw IP — return immediately, no lookup, no caching needed.
+        if (isIP(target) !== 0) {
+            return [target];
+        }
+        // 2. Cache hit — return if still within TTL.
+        const cached = this.cache.get(target);
+        if (cached !== undefined && Date.now() < cached.expiresAt) {
+            return cached.addresses;
+        }
+        // 3. In-flight de-duplication — if there is already a pending lookup for
+        //    this hostname, piggyback on it rather than issuing a second request.
+        const existing = this.inflight.get(target);
+        if (existing !== undefined) {
+            return existing;
+        }
+        // 4. Issue a fresh lookup and register it as in-flight.
+        const lookupPromise = this._lookup(target).then((addresses) => {
+            // Store in cache (even an empty result, to avoid hammering failed names).
+            if (this.ttlMs > 0) {
+                this.cache.set(target, {
+                    addresses,
+                    expiresAt: Date.now() + this.ttlMs,
+                });
+            }
+            this.inflight.delete(target);
+            return addresses;
+        });
+        this.inflight.set(target, lookupPromise);
+        return lookupPromise;
+    }
+    /** Perform the actual A + AAAA DNS queries in parallel. Never throws. */
+    async _lookup(hostname) {
+        const [v4Result, v6Result] = await Promise.allSettled([
+            dns.resolve4(hostname),
+            dns.resolve6(hostname),
+        ]);
+        const addresses = [];
+        if (v4Result.status === "fulfilled") {
+            addresses.push(...v4Result.value);
+        }
+        if (v6Result.status === "fulfilled") {
+            addresses.push(...v6Result.value);
+        }
+        return addresses;
+    }
+}
+//# sourceMappingURL=dns-resolver.js.map

package/dist/src/dns-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns-resolver.js","sourceRoot":"","sources":["../../src/dns-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAC3B,OAAO,GAAG,MAAM,cAAc,CAAC;AAO/B;;;;;;;;;GASG;AACH,MAAM,OAAO,WAAW;IACL,KAAK,CAAS;IACd,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IACvD,yDAAyD;IACxC,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEjE,YAAY,aAAqB,EAAE;QACjC,IAAI,CAAC,KAAK,GAAG,UAAU,GAAG,IAAI,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,gEAAgE;QAChE,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,MAAM,CAAC,CAAC;QAClB,CAAC;QAED,6CAA6C;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;YAC1D,OAAO,MAAM,CAAC,SAAS,CAAC;QAC1B,CAAC;QAED,yEAAyE;QACzE,0EAA0E;QAC1E,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,wDAAwD;QACxD,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE;YAC5D,0EAA0E;YAC1E,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;gBACnB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE;oBACrB,SAAS;oBACT,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;iBACnC,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC7B,OAAO,SAAS,CAAC;QACnB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;QACzC,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,yEAAyE;IACjE,KAAK,CAAC,OAAO,CAAC,QAAgB;QACpC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;YACpD,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACtB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;SACvB,CAAC,CAAC;QAEH,MAAM,SAAS,GAAa,EAAE,CAAC;QAE/B,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACpC,SAAS,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACpC,SAAS,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/src/domain-matcher.d.ts

@@ -0,0 +1,35 @@
+/**
+ * domain-matcher.ts
+ *
+ * Utilities for matching hostnames against domain patterns used in scope
+ * enforcement.  This is a SECURITY-CRITICAL module — an incorrect match means
+ * attacking the wrong target.
+ *
+ * Supported pattern forms:
+ *   - Exact:    "acme-staging.example.com"
+ *   - Wildcard: "*.acme.com"  (matches exactly ONE subdomain level, not the
+ *               apex and not deeper nesting)
+ *
+ * All comparisons are case-insensitive.  Trailing DNS dots are stripped from
+ * both inputs before any comparison.
+ */
+/**
+ * Match a hostname against a single pattern.
+ *
+ * Rules:
+ *  - Both inputs are normalized (lower-cased, trailing dot stripped).
+ *  - Empty strings never match.
+ *  - Wildcard prefix `*.` is the ONLY supported wildcard form.
+ *    `*.acme.com` matches `foo.acme.com` but NOT `acme.com` and NOT
+ *    `foo.bar.acme.com`.
+ *  - Any pattern that does not start with `*.` is treated as an exact match.
+ *  - Unicode labels (non-ASCII) are compared byte-for-byte after lower-casing;
+ *    they will only match an identical unicode pattern, not an ASCII wildcard.
+ */
+export declare function matchesDomain(hostname: string, pattern: string): boolean;
+/**
+ * Return true if the hostname matches at least one pattern in the array.
+ * Returns false immediately for an empty patterns array.
+ */
+export declare function matchesAnyDomain(hostname: string, patterns: string[]): boolean;
+//# sourceMappingURL=domain-matcher.d.ts.map

package/dist/src/domain-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-matcher.d.ts","sourceRoot":"","sources":["../../src/domain-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAeH;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CA2DxE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAE9E"}

package/dist/src/domain-matcher.js

@@ -0,0 +1,97 @@
+/**
+ * domain-matcher.ts
+ *
+ * Utilities for matching hostnames against domain patterns used in scope
+ * enforcement.  This is a SECURITY-CRITICAL module — an incorrect match means
+ * attacking the wrong target.
+ *
+ * Supported pattern forms:
+ *   - Exact:    "acme-staging.example.com"
+ *   - Wildcard: "*.acme.com"  (matches exactly ONE subdomain level, not the
+ *               apex and not deeper nesting)
+ *
+ * All comparisons are case-insensitive.  Trailing DNS dots are stripped from
+ * both inputs before any comparison.
+ */
+/**
+ * Normalize a hostname or pattern by:
+ *  1. Lower-casing it (DNS is case-insensitive).
+ *  2. Stripping a single trailing dot (absolute FQDN notation).
+ */
+function normalize(value) {
+    let s = value.toLowerCase();
+    if (s.endsWith(".")) {
+        s = s.slice(0, -1);
+    }
+    return s;
+}
+/**
+ * Match a hostname against a single pattern.
+ *
+ * Rules:
+ *  - Both inputs are normalized (lower-cased, trailing dot stripped).
+ *  - Empty strings never match.
+ *  - Wildcard prefix `*.` is the ONLY supported wildcard form.
+ *    `*.acme.com` matches `foo.acme.com` but NOT `acme.com` and NOT
+ *    `foo.bar.acme.com`.
+ *  - Any pattern that does not start with `*.` is treated as an exact match.
+ *  - Unicode labels (non-ASCII) are compared byte-for-byte after lower-casing;
+ *    they will only match an identical unicode pattern, not an ASCII wildcard.
+ */
+export function matchesDomain(hostname, pattern) {
+    // Reject empty inputs immediately — they are meaningless in scope checking.
+    if (!hostname || !pattern) {
+        return false;
+    }
+    const normalizedHost = normalize(hostname);
+    const normalizedPattern = normalize(pattern);
+    // A second empty-check after normalization (e.g. input was just ".")
+    if (!normalizedHost || !normalizedPattern) {
+        return false;
+    }
+    // Wildcard pattern: must start with "*."
+    if (normalizedPattern.startsWith("*.")) {
+        const base = normalizedPattern.slice(2); // the part after "*."
+        // The base itself must be non-empty.
+        if (!base) {
+            return false;
+        }
+        // The hostname must end with ".<base>" — i.e. it has exactly one extra
+        // label prepended.  We verify this by checking:
+        //   1. The hostname ends with ".<base>".
+        //   2. After stripping ".<base>" from the right, the remaining prefix
+        //      contains no dots (so it is exactly one label, not multiple).
+        const suffix = "." + base;
+        if (!normalizedHost.endsWith(suffix)) {
+            return false;
+        }
+        const prefix = normalizedHost.slice(0, normalizedHost.length - suffix.length);
+        // The prefix must be non-empty (rules out the apex domain itself) and
+        // must contain no dots (rules out deeper nesting).
+        // Additionally, we guard against non-ASCII characters in the prefix
+        // matching a pure ASCII wildcard — the prefix must be composed only of
+        // valid ASCII label characters when the base pattern is ASCII-only.
+        if (!prefix || prefix.includes(".")) {
+            return false;
+        }
+        // Security guard: if the base pattern is pure ASCII but the prefix
+        // contains non-ASCII characters, do not allow the match.  This prevents
+        // unicode/IDN hostnames from silently satisfying an ASCII wildcard.
+        const isBaseAscii = /^[\x00-\x7F]+$/.test(base);
+        const isPrefixAscii = /^[\x00-\x7F]+$/.test(prefix);
+        if (isBaseAscii && !isPrefixAscii) {
+            return false;
+        }
+        return true;
+    }
+    // Exact match.
+    return normalizedHost === normalizedPattern;
+}
+/**
+ * Return true if the hostname matches at least one pattern in the array.
+ * Returns false immediately for an empty patterns array.
+ */
+export function matchesAnyDomain(hostname, patterns) {
+    return patterns.some((pattern) => matchesDomain(hostname, pattern));
+}
+//# sourceMappingURL=domain-matcher.js.map

package/dist/src/domain-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-matcher.js","sourceRoot":"","sources":["../../src/domain-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,SAAS,SAAS,CAAC,KAAa;IAC9B,IAAI,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAC5B,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACpB,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,OAAe;IAC7D,4EAA4E;IAC5E,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,cAAc,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,iBAAiB,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAE7C,qEAAqE;IACrE,IAAI,CAAC,cAAc,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yCAAyC;IACzC,IAAI,iBAAiB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,sBAAsB;QAE/D,qCAAqC;QACrC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACf,CAAC;QAED,uEAAuE;QACvE,gDAAgD;QAChD,yCAAyC;QACzC,sEAAsE;QACtE,oEAAoE;QACpE,MAAM,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC;QAE1B,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAE9E,sEAAsE;QACtE,mDAAmD;QACnD,oEAAoE;QACpE,uEAAuE;QACvE,oEAAoE;QACpE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,mEAAmE;QACnE,wEAAwE;QACxE,oEAAoE;QACpE,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,aAAa,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACpD,IAAI,WAAW,IAAI,CAAC,aAAa,EAAE,CAAC;YAClC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED,eAAe;IACf,OAAO,cAAc,KAAK,iBAAiB,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,QAAkB;IACnE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/src/extractor.d.ts

@@ -0,0 +1,30 @@
+/**
+ * extractor.ts
+ *
+ * Target Extractor for the MCP Scope Enforcement Proxy.
+ *
+ * Extracts the target host/IP/domain from a tool call's parameters so that the
+ * scope-enforcement layer can decide whether to allow or block the call.
+ *
+ * SECURITY NOTE: Incorrect extraction means attacking the wrong target.
+ * Every code path here has a corresponding unit test — do not modify without
+ * updating tests/unit/extractor.test.ts.
+ */
+export interface ExtractionResult {
+    /** The extracted target (hostname, IP, CIDR, etc.) — never a full URL. */
+    target: string;
+    /** The parameter name the target was read from. */
+    source: string;
+    /** True when the tool was not in the known-tool mapping and the generic
+     *  fallback parameter list was used instead. */
+    usedFallback: boolean;
+}
+/**
+ * Extract the primary target from a tool call's parameters.
+ *
+ * @param toolName  The MCP tool name as received (case-insensitive).
+ * @param params    The raw tool parameters object.
+ * @returns An ExtractionResult, or null if no target-like parameter was found.
+ */
+export declare function extractTarget(toolName: string, params: Record<string, unknown>): ExtractionResult | null;
+//# sourceMappingURL=extractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../src/extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf;oDACgD;IAChD,YAAY,EAAE,OAAO,CAAC;CACvB;AAsKD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,gBAAgB,GAAG,IAAI,CAmBzB"}

package/dist/src/extractor.js

@@ -0,0 +1,176 @@
+/**
+ * extractor.ts
+ *
+ * Target Extractor for the MCP Scope Enforcement Proxy.
+ *
+ * Extracts the target host/IP/domain from a tool call's parameters so that the
+ * scope-enforcement layer can decide whether to allow or block the call.
+ *
+ * SECURITY NOTE: Incorrect extraction means attacking the wrong target.
+ * Every code path here has a corresponding unit test — do not modify without
+ * updating tests/unit/extractor.test.ts.
+ */
+const TOOL_MAPPINGS = [
+    { match: "nmap", params: ["target", "host", "hosts"] },
+    { match: "nmap_scan", params: ["target", "host", "hosts"] },
+    { match: "burp_scan", params: ["url", "target_url", "base_url"] },
+    { match: "burp_active_scan", params: ["url", "target_url", "base_url"] },
+    { match: "sqlmap", params: ["url", "target"] },
+    { match: "curl", params: ["url", "uri"] },
+    { match: "http_request", params: ["url", "uri"] },
+    { match: "nikto", params: ["host", "target", "url"] },
+    { match: "gobuster", params: ["url", "target"] },
+    { match: "ffuf", params: ["url", "target"] },
+    { match: "dirb", params: ["url", "target"] },
+    { match: "netcat", params: ["host", "target"] },
+    { match: "nc", params: ["host", "target"] },
+    { match: "ping", params: ["host", "target"] },
+    { match: "traceroute", params: ["host", "target"] },
+    // Metasploit — prefix match covers msf_exploit, msf_run, msf_payload, etc.
+    { match: "msf_*", params: ["rhost", "rhosts", "target"] },
+    { match: "metasploit", params: ["rhost", "rhosts", "target"] },
+    { match: "nuclei", params: ["target", "targets", "url"] },
+];
+/**
+ * Fallback parameter names tried (in priority order) when the tool name does
+ * not match any entry in TOOL_MAPPINGS.
+ */
+const FALLBACK_PARAMS = [
+    "target",
+    "host",
+    "url",
+    "rhost",
+    "destination",
+    "uri",
+];
+// ---------------------------------------------------------------------------
+// URL parsing helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when the value looks like an http or https URL.
+ */
+function isHttpUrl(value) {
+    return value.startsWith("http://") || value.startsWith("https://");
+}
+/**
+ * Given an http/https URL, extract just the hostname (no port, no credentials).
+ * Returns null if the URL cannot be parsed.
+ *
+ * Examples:
+ *   https://admin:pass@example.com:8443/path  →  example.com
+ *   http://[::1]:80/test                       →  ::1
+ *   http://192.168.1.1/admin                   →  192.168.1.1
+ */
+function extractHostname(rawUrl) {
+    try {
+        const parsed = new URL(rawUrl);
+        let host = parsed.hostname;
+        // Strip IPv6 brackets if present (some Node versions keep them)
+        if (host.startsWith("[") && host.endsWith("]")) {
+            host = host.slice(1, -1);
+        }
+        return host.length > 0 ? host : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Parameter value resolution
+// ---------------------------------------------------------------------------
+/**
+ * Coerce a raw parameter value to a string candidate.
+ *
+ * - Arrays: take the first element and recurse.
+ * - Numbers: convert to string (e.g., numeric IPs are unusual but tolerated).
+ * - Strings: return as-is.
+ * - Everything else (null, undefined, boolean, object): return null.
+ */
+function coerceToString(value) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return null;
+        return coerceToString(value[0]);
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return null;
+}
+/**
+ * Given a raw param value, return the resolved target string.
+ *
+ * - If the value is a URL (http/https), extract the hostname.
+ * - Otherwise return the coerced string directly.
+ * - Returns null for empty strings or unparseable URLs.
+ */
+function resolveParamValue(value) {
+    const raw = coerceToString(value);
+    if (raw === null || raw.trim() === "")
+        return null;
+    if (isHttpUrl(raw)) {
+        return extractHostname(raw);
+    }
+    return raw;
+}
+// ---------------------------------------------------------------------------
+// Tool-name matching
+// ---------------------------------------------------------------------------
+/**
+ * Find the candidate parameter list for a given tool name.
+ * Returns null when no mapping is found (caller should use fallback).
+ *
+ * Matching is case-insensitive.
+ * Supports prefix wildcards (e.g. "msf_*" matches "msf_exploit").
+ */
+function findMapping(toolName) {
+    const lower = toolName.toLowerCase();
+    for (const mapping of TOOL_MAPPINGS) {
+        const pattern = mapping.match;
+        if (pattern.endsWith("*")) {
+            // Prefix match: e.g. "msf_*" → prefix "msf_"
+            const prefix = pattern.slice(0, -1);
+            if (lower.startsWith(prefix)) {
+                return mapping.params;
+            }
+        }
+        else {
+            if (lower === pattern) {
+                return mapping.params;
+            }
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Extract the primary target from a tool call's parameters.
+ *
+ * @param toolName  The MCP tool name as received (case-insensitive).
+ * @param params    The raw tool parameters object.
+ * @returns An ExtractionResult, or null if no target-like parameter was found.
+ */
+export function extractTarget(toolName, params) {
+    const knownParams = findMapping(toolName);
+    const usedFallback = knownParams === null;
+    const candidates = knownParams ?? FALLBACK_PARAMS;
+    for (const paramName of candidates) {
+        if (!(paramName in params))
+            continue;
+        const resolved = resolveParamValue(params[paramName]);
+        if (resolved === null)
+            continue;
+        return {
+            target: resolved,
+            source: paramName,
+            usedFallback,
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=extractor.js.map

package/dist/src/extractor.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+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 declare const VERSION = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACxF,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,7 @@
+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 const VERSION = "0.1.0";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/src/ip-matcher.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ip-matcher.ts
+ *
+ * IP / CIDR matching utilities for scope enforcement.
+ * Used to determine whether a target IP is in-scope, private, or a cloud
+ * metadata endpoint.  This is security-critical code: every edge case matters.
+ */
+/**
+ * Check whether `ip` falls within the CIDR `cidr`.
+ *
+ * - Bare IPs (no slash) are treated as an exact-host match (/32 or /128).
+ * - Returns `false` for any invalid input rather than throwing.
+ * - An IPv4 address will never match an IPv6 range and vice-versa.
+ */
+export declare function isIpInCidr(ip: string, cidr: string): boolean;
+/**
+ * Check whether `ip` falls within any of the provided CIDR/IP `ranges`.
+ *
+ * - An empty `ranges` array always returns `false`.
+ * - Invalid individual ranges are silently skipped.
+ * - Returns `false` for any invalid `ip`.
+ */
+export declare function isIpInAnyRange(ip: string, ranges: string[]): boolean;
+/**
+ * Return true if `ip` is a private/link-local IPv4 address as defined by
+ * RFC 1918 and RFC 3927 (169.254.0.0/16).
+ *
+ * Returns `false` for invalid inputs and for IPv6 addresses.
+ */
+export declare function isRfc1918(ip: string): boolean;
+/**
+ * Return true if `ip` is a known cloud metadata endpoint.
+ *
+ * Performs exact-host matching only — no subnet expansion.
+ * Returns `false` for invalid inputs.
+ */
+export declare function isCloudMetadata(ip: string): boolean;
+//# sourceMappingURL=ip-matcher.d.ts.map

package/dist/src/ip-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-matcher.d.ts","sourceRoot":"","sources":["../../src/ip-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuCH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAiB5D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAOpE;AAgBD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAS7C;AAYD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKnD"}