@aumos/agentshield 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# @aumos/agentshield
+
+TypeScript client for the [AumOS AgentShield](https://github.com/invincible-jha/agentshield)
+defense layer. Scan agent inputs and outputs for prompt-injection, PII, and malicious
+payloads — and validate tool calls before execution.
+
+## Requirements
+
+- Node.js 18+ (uses native Fetch API)
+- TypeScript 5.3+ (strict mode)
+
+## Installation
+
+```bash
+npm install @aumos/agentshield
+```
+
+## Usage
+
+### HTTP client
+
+```ts
+import { createAgentShieldClient } from "@aumos/agentshield";
+
+const client = createAgentShieldClient({
+  baseUrl: "http://localhost:8091",
+  timeoutMs: 10_000,
+});
+
+// Scan an incoming user message
+const inputScan = await client.scanInput({
+  agent_id: "my-agent",
+  content: userMessage,
+  session_id: "session-abc123",
+});
+
+if (inputScan.ok && inputScan.data.blocked) {
+  console.warn("Input blocked. Findings:", inputScan.data.findings);
+  // Do not forward the message to the LLM.
+}
+
+// Scan an LLM response before returning it to the user
+const outputScan = await client.scanOutput({
+  agent_id: "my-agent",
+  content: llmResponse,
+  session_id: "session-abc123",
+});
+
+// Validate a tool call before execution
+const toolCheck = await client.validateToolCall({
+  agent_id: "my-agent",
+  tool_name: "web_search",
+  tool_arguments: { query: userQuery },
+  session_id: "session-abc123",
+});
+
+if (toolCheck.ok && !toolCheck.data.allowed) {
+  console.warn("Tool call blocked:", toolCheck.data.block_reason);
+}
+
+// Retrieve aggregated threat report
+const report = await client.getThreatReport({
+  agentId: "my-agent",
+  windowStart: "2026-02-01T00:00:00Z",
+  windowEnd: "2026-02-28T23:59:59Z",
+});
+if (report.ok) {
+  console.log("Blocked scans:", report.data.blocked_count);
+}
+```
+
+### Local input scanner (no network required)
+
+```ts
+import { createInputScanner } from "@aumos/agentshield";
+
+const scanner = createInputScanner();
+const options = { agentId: "my-agent", sessionId: "session-abc123" };
+
+// Check for prompt injection
+const injectionFindings = scanner.checkPromptInjection(userInput, options);
+if (injectionFindings.length > 0) {
+  console.warn("Injection attempt detected:", injectionFindings[0].rule_id);
+}
+
+// Check for PII
+const piiFindings = scanner.checkPII(llmOutput, options);
+
+// Check for malicious payloads
+const payloadFindings = scanner.checkMaliciousPayload(toolResult, options);
+
+// Run all checks at once (sorted by severity)
+const allFindings = scanner.scanAll(content, options);
+for (const finding of allFindings) {
+  console.log(`[${finding.level}] ${finding.rule_id}: ${finding.description}`);
+}
+```
+
+## API reference
+
+### `createAgentShieldClient(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | `string` | required | AgentShield server URL |
+| `timeoutMs` | `number` | `10000` | Request timeout (ms) |
+| `headers` | `Record<string, string>` | `{}` | Extra HTTP headers |
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `scanInput(request)` | Scan content arriving as agent input |
+| `scanOutput(request)` | Scan content produced as agent output |
+| `getThreatReport(options)` | Aggregated threat statistics for an agent |
+| `validateToolCall(request)` | Validate a tool call before execution |
+
+### `createInputScanner()`
+
+| Method | Description |
+|--------|-------------|
+| `checkPromptInjection(text, options)` | Detect instruction-override patterns |
+| `checkPII(text, options)` | Detect email, SSN, credit-card, phone, IP |
+| `checkMaliciousPayload(text, options)` | Detect shell injection, SQL injection, path traversal |
+| `scanAll(text, options)` | Run all checks, results sorted by severity |
+
+### Threat levels
+
+| Level | Description |
+|-------|-------------|
+| `critical` | Immediate block recommended (jailbreak, SSN, shell injection) |
+| `high` | Block recommended (instruction override, SQL injection) |
+| `medium` | Review recommended (role-switch, base64 obfuscation) |
+| `low` | Log and monitor (phone numbers) |
+| `info` | Informational only (IP addresses) |
+
+## License
+
+Apache-2.0. See [LICENSE](../../LICENSE) for details.

package/dist/client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * HTTP client for the AgentShield defense API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentShieldClient } from "@aumos/agentshield";
+ *
+ * const client = createAgentShieldClient({ baseUrl: "http://localhost:8091" });
+ *
+ * const result = await client.scanInput({
+ *   agent_id: "my-agent",
+ *   content: userMessage,
+ *   session_id: "session-abc",
+ * });
+ *
+ * if (result.ok && result.data.blocked) {
+ *   console.warn("Input blocked:", result.data.findings);
+ * }
+ * ```
+ */
+import type { ApiResult, ScanResult, ThreatDetectionResult, ToolCallValidationRequest, ToolCallValidationResult } from "./types.js";
+/** Configuration options for the AgentShieldClient. */
+export interface AgentShieldClientConfig {
+    /** Base URL of the AgentShield server (e.g. "http://localhost:8091"). */
+    readonly baseUrl: string;
+    /** Optional request timeout in milliseconds (default: 10000). */
+    readonly timeoutMs?: number;
+    /** Optional extra HTTP headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Request body for input or output scanning. */
+export interface ContentScanRequest {
+    /** Agent that produced or received the content. */
+    readonly agent_id: string;
+    /** Raw content string to scan. */
+    readonly content: string;
+    /** Optional session context. */
+    readonly session_id?: string;
+    /** Arbitrary metadata forwarded to rule implementations. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Typed HTTP client for the AgentShield defense server. */
+export interface AgentShieldClient {
+    /**
+     * Scan content arriving as agent input (e.g. user messages, tool results).
+     *
+     * @param request - Content and context to scan.
+     * @returns ScanResult with findings and a blocked flag.
+     */
+    scanInput(request: ContentScanRequest): Promise<ApiResult<ScanResult>>;
+    /**
+     * Scan content produced as agent output (e.g. LLM responses, tool invocations).
+     *
+     * @param request - Content and context to scan.
+     * @returns ScanResult with findings and a blocked flag.
+     */
+    scanOutput(request: ContentScanRequest): Promise<ApiResult<ScanResult>>;
+    /**
+     * Retrieve aggregated threat detection statistics for an agent.
+     *
+     * @param options - Agent and optional time-window filters.
+     * @returns ThreatDetectionResult summarising threat activity.
+     */
+    getThreatReport(options: {
+        agentId: string;
+        windowStart?: string;
+        windowEnd?: string;
+    }): Promise<ApiResult<ThreatDetectionResult>>;
+    /**
+     * Validate a proposed tool call before it is executed.
+     *
+     * @param request - Tool name, arguments, and calling-agent context.
+     * @returns ToolCallValidationResult indicating whether execution is permitted.
+     */
+    validateToolCall(request: ToolCallValidationRequest): Promise<ApiResult<ToolCallValidationResult>>;
+}
+/**
+ * Create a typed HTTP client for the AgentShield server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentShieldClient instance.
+ */
+export declare function createAgentShieldClient(config: AgentShieldClientConfig): AgentShieldClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAEV,SAAS,EACT,UAAU,EACV,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAMpB,uDAAuD;AACvD,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAMD,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AA0DD,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IAEvE;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IAExE;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,gBAAgB,CACd,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAAC,CAAC;CACjD;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,uBAAuB,GAC9B,iBAAiB,CAkEnB"}

package/dist/client.js

@@ -0,0 +1,110 @@
+/**
+ * HTTP client for the AgentShield defense API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentShieldClient } from "@aumos/agentshield";
+ *
+ * const client = createAgentShieldClient({ baseUrl: "http://localhost:8091" });
+ *
+ * const result = await client.scanInput({
+ *   agent_id: "my-agent",
+ *   content: userMessage,
+ *   session_id: "session-abc",
+ * });
+ *
+ * if (result.ok && result.data.blocked) {
+ *   console.warn("Input blocked:", result.data.findings);
+ * }
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function fetchJson(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeoutId);
+        const body = await response.json();
+        if (!response.ok) {
+            const errorBody = body;
+            return {
+                ok: false,
+                error: {
+                    error: errorBody.error ?? "Unknown error",
+                    detail: errorBody.detail ?? "",
+                },
+                status: response.status,
+            };
+        }
+        return { ok: true, data: body };
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: { error: "Network error", detail: message },
+            status: 0,
+        };
+    }
+}
+function buildHeaders(extraHeaders) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...extraHeaders,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed HTTP client for the AgentShield server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentShieldClient instance.
+ */
+export function createAgentShieldClient(config) {
+    const { baseUrl, timeoutMs = 10_000, headers: extraHeaders } = config;
+    const baseHeaders = buildHeaders(extraHeaders);
+    return {
+        async scanInput(request) {
+            return fetchJson(`${baseUrl}/scan/input`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async scanOutput(request) {
+            return fetchJson(`${baseUrl}/scan/output`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async getThreatReport(options) {
+            const params = new URLSearchParams({ agent_id: options.agentId });
+            if (options.windowStart !== undefined) {
+                params.set("window_start", options.windowStart);
+            }
+            if (options.windowEnd !== undefined) {
+                params.set("window_end", options.windowEnd);
+            }
+            return fetchJson(`${baseUrl}/threats/report?${params.toString()}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async validateToolCall(request) {
+            return fetchJson(`${baseUrl}/validate/tool-call`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @aumos/agentshield
+ *
+ * TypeScript client for the AumOS AgentShield defense layer.
+ * Provides HTTP client, synchronous input scanner, and threat-detection type definitions.
+ */
+export type { AgentShieldClient, AgentShieldClientConfig, ContentScanRequest } from "./client.js";
+export { createAgentShieldClient } from "./client.js";
+export type { ThreatLevel, DefenseLayer, ThreatFinding, ScanResult, ThreatDetectionResult, ToolCallValidationRequest, ToolCallValidationResult, ApiError, ApiResult, } from "./types.js";
+export type { InputScanner, ScanOptions } from "./scanner.js";
+export { createInputScanner } from "./scanner.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAClG,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAGtD,YAAY,EACV,WAAW,EACX,YAAY,EACZ,aAAa,EACb,UAAU,EACV,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACxB,QAAQ,EACR,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aumos/agentshield
+ *
+ * TypeScript client for the AumOS AgentShield defense layer.
+ * Provides HTTP client, synchronous input scanner, and threat-detection type definitions.
+ */
+export { createAgentShieldClient } from "./client.js";
+export { createInputScanner } from "./scanner.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAiBtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/scanner.d.ts

@@ -0,0 +1,60 @@
+/**
+ * InputScanner — pure, synchronous content-scanning utilities.
+ *
+ * These functions operate on plain strings and return typed finding arrays.
+ * They do not make network calls and have no side effects.
+ *
+ * Defensive-only framing: detects patterns associated with known attack
+ * categories so that the caller can decide whether to block or log.
+ */
+import type { ThreatFinding } from "./types.js";
+/** Options shared by all scanner methods. */
+export interface ScanOptions {
+    /** Agent performing or receiving the content. */
+    readonly agentId: string;
+    /** Optional session context passed through to findings metadata. */
+    readonly sessionId?: string;
+}
+/** Synchronous content-scanning utilities. */
+export interface InputScanner {
+    /**
+     * Detect prompt-injection patterns in the given text.
+     *
+     * @param text - Raw input string to analyse.
+     * @param options - Agent and session context.
+     * @returns Array of ThreatFindings for any injection patterns found.
+     */
+    checkPromptInjection(text: string, options: ScanOptions): readonly ThreatFinding[];
+    /**
+     * Detect personally identifiable information in the given text.
+     *
+     * @param text - Raw content string to analyse.
+     * @param options - Agent and session context.
+     * @returns Array of ThreatFindings for any PII patterns found.
+     */
+    checkPII(text: string, options: ScanOptions): readonly ThreatFinding[];
+    /**
+     * Detect indicators of malicious payloads in the given text.
+     *
+     * @param text - Raw content string to analyse.
+     * @param options - Agent and session context.
+     * @returns Array of ThreatFindings for any suspicious patterns found.
+     */
+    checkMaliciousPayload(text: string, options: ScanOptions): readonly ThreatFinding[];
+    /**
+     * Run all checks and return the combined, deduplicated findings list
+     * sorted by severity (critical first).
+     *
+     * @param text - Raw content string to analyse.
+     * @param options - Agent and session context.
+     * @returns All findings across all defense layers.
+     */
+    scanAll(text: string, options: ScanOptions): readonly ThreatFinding[];
+}
+/**
+ * Create an InputScanner instance.
+ *
+ * @returns An InputScanner with all check methods.
+ */
+export declare function createInputScanner(): InputScanner;
+//# sourceMappingURL=scanner.d.ts.map

package/dist/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAgB,aAAa,EAAe,MAAM,YAAY,CAAC;AAM3E,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAkND,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,GACnB,SAAS,aAAa,EAAE,CAAC;IAE5B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,SAAS,aAAa,EAAE,CAAC;IAEvE;;;;;;OAMG;IACH,qBAAqB,CACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,GACnB,SAAS,aAAa,EAAE,CAAC;IAE5B;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,SAAS,aAAa,EAAE,CAAC;CACvE;AAkBD;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAsCjD"}

package/dist/scanner.js

@@ -0,0 +1,208 @@
+/**
+ * InputScanner — pure, synchronous content-scanning utilities.
+ *
+ * These functions operate on plain strings and return typed finding arrays.
+ * They do not make network calls and have no side effects.
+ *
+ * Defensive-only framing: detects patterns associated with known attack
+ * categories so that the caller can decide whether to block or log.
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+let findingIdCounter = 0;
+function nextFindingId() {
+    findingIdCounter += 1;
+    return `finding-${Date.now()}-${findingIdCounter}`;
+}
+function buildFinding(layer, level, ruleId, description, text, offset, metadata) {
+    // Produce a redacted excerpt — never expose the raw payload.
+    const excerpt = text.length > 80
+        ? `${text.slice(0, 40)}...[redacted]...${text.slice(-20)}`
+        : text.replace(/./g, "*");
+    return {
+        finding_id: nextFindingId(),
+        layer,
+        level,
+        rule_id: ruleId,
+        description,
+        offset,
+        excerpt,
+        metadata,
+    };
+}
+// ---------------------------------------------------------------------------
+// Prompt-injection detection patterns
+// ---------------------------------------------------------------------------
+/**
+ * Patterns that signal an attempt to override system instructions.
+ * Each entry is [ruleId, description, pattern, level].
+ */
+const PROMPT_INJECTION_RULES = [
+    [
+        "PI-001",
+        "Instruction-override attempt detected",
+        /ignore\s+(all\s+)?previous\s+instructions?/i,
+        "high",
+    ],
+    [
+        "PI-002",
+        "System-prompt disclosure request detected",
+        /reveal\s+(your\s+)?(system\s+)?prompt/i,
+        "high",
+    ],
+    [
+        "PI-003",
+        "Role-switch injection attempt detected",
+        /you\s+are\s+now\s+(a|an)\s+\w/i,
+        "medium",
+    ],
+    [
+        "PI-004",
+        "Jailbreak keyword detected",
+        /\b(jailbreak|dan\s+mode|developer\s+mode)\b/i,
+        "critical",
+    ],
+    [
+        "PI-005",
+        "Fake-completion injection pattern detected",
+        /<\/?(?:system|assistant|user)\s*>/i,
+        "high",
+    ],
+];
+// ---------------------------------------------------------------------------
+// PII detection patterns
+// ---------------------------------------------------------------------------
+/**
+ * Patterns for common PII categories.
+ * Each entry is [ruleId, description, pattern, level].
+ */
+const PII_RULES = [
+    [
+        "PII-EMAIL",
+        "Email address detected",
+        /\b[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}\b/,
+        "medium",
+    ],
+    [
+        "PII-SSN",
+        "US Social Security Number pattern detected",
+        /\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b/,
+        "critical",
+    ],
+    [
+        "PII-CREDIT-CARD",
+        "Credit card number pattern detected",
+        /\b(?:\d[ -]?){13,16}\b/,
+        "critical",
+    ],
+    [
+        "PII-PHONE",
+        "Phone number pattern detected",
+        /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/,
+        "low",
+    ],
+    [
+        "PII-IP-ADDRESS",
+        "IP address detected",
+        /\b(?:\d{1,3}\.){3}\d{1,3}\b/,
+        "info",
+    ],
+];
+// ---------------------------------------------------------------------------
+// Malicious payload patterns
+// ---------------------------------------------------------------------------
+/**
+ * Patterns for known malicious payload indicators.
+ * Defensive framing: these detect encoded or obfuscated content.
+ * Each entry is [ruleId, description, pattern, level].
+ */
+const MALICIOUS_PAYLOAD_RULES = [
+    [
+        "MPL-001",
+        "Base64-encoded block detected — possible payload obfuscation",
+        /\b[A-Za-z0-9+/]{40,}={0,2}\b/,
+        "medium",
+    ],
+    [
+        "MPL-002",
+        "Shell command injection pattern detected",
+        /(?:;\s*(?:rm|curl|wget|bash|sh|python|perl|nc)\b|&&\s*(?:rm|curl|wget|bash|sh)\b)/i,
+        "critical",
+    ],
+    [
+        "MPL-003",
+        "SQL injection pattern detected",
+        /(?:';\s*(?:drop|delete|update|insert|select)\b|--\s*$|\bUNION\s+SELECT\b)/i,
+        "critical",
+    ],
+    [
+        "MPL-004",
+        "Path traversal pattern detected",
+        /(?:\.\.\/|\.\.\\){2,}/,
+        "high",
+    ],
+    [
+        "MPL-005",
+        "Excessive token repetition detected — possible resource-exhaustion attempt",
+        /(\b\w+\b)(?:\s+\1){20,}/i,
+        "medium",
+    ],
+];
+// ---------------------------------------------------------------------------
+// Generic pattern-matching runner
+// ---------------------------------------------------------------------------
+function runPatternRules(text, rules, layer, options) {
+    const findings = [];
+    for (const [ruleId, description, pattern, level] of rules) {
+        const match = pattern.exec(text);
+        if (match !== null) {
+            findings.push(buildFinding(layer, level, ruleId, description, match[0], match.index, {
+                agent_id: options.agentId,
+                session_id: options.sessionId ?? null,
+                match_length: match[0].length,
+            }));
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Severity ordering helper
+// ---------------------------------------------------------------------------
+const THREAT_LEVEL_ORDER = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    info: 4,
+};
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an InputScanner instance.
+ *
+ * @returns An InputScanner with all check methods.
+ */
+export function createInputScanner() {
+    return {
+        checkPromptInjection(text, options) {
+            return runPatternRules(text, PROMPT_INJECTION_RULES, "prompt_injection", options);
+        },
+        checkPII(text, options) {
+            return runPatternRules(text, PII_RULES, "pii_detection", options);
+        },
+        checkMaliciousPayload(text, options) {
+            return runPatternRules(text, MALICIOUS_PAYLOAD_RULES, "malicious_payload", options);
+        },
+        scanAll(text, options) {
+            const all = [
+                ...runPatternRules(text, PROMPT_INJECTION_RULES, "prompt_injection", options),
+                ...runPatternRules(text, PII_RULES, "pii_detection", options),
+                ...runPatternRules(text, MALICIOUS_PAYLOAD_RULES, "malicious_payload", options),
+            ];
+            return all.sort((a, b) => THREAT_LEVEL_ORDER[a.level] - THREAT_LEVEL_ORDER[b.level]);
+        },
+    };
+}
+//# sourceMappingURL=scanner.js.map

package/dist/scanner.js.map

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