@openguardrails/moltguard/dist/agent/behavior-detector.d.ts

AI agent security plugin for OpenClaw: prompt injection detection, PII sanitization, and monitoring dashboard

/**
 * Behavioral anomaly detector — runs at before_tool_call.
 *
 * Responsibilities:
 *   1. Collect high-risk tool calls (file read, shell, web fetch) and send to Core
 *   2. Record completed tool calls in the chain history
 *   3. Core does all classification, signal computation, and risk decisions
 *   4. Fail-open: if Core is unavailable, allow execution
 */
import type { CoreCredentials } from "./config.js";
import type { Logger, DetectionFinding } from "./types.js";
export declare const FILE_READ_TOOLS: Set<string>;
export declare const SHELL_TOOLS: Set<string>;
export declare const WEB_FETCH_TOOLS: Set<string>;
export type BlockDecision = {
    block: true;
    blockReason: string;
    findings?: DetectionFinding[];
};
export type DetectionConfig = {
    coreUrl: string;
    /** Timeout for Core assess call (ms). Capped at ~3s to avoid holding up agent. */
    assessTimeoutMs: number;
    blockOnRisk: boolean;
    pluginVersion: string;
};
/** Response from Core content scan API */
export type ContentScanResult = {
    detected: boolean;
    categories: string[];
    findings: Array<{
        scanner: string;
        name: string;
        matchedText: string;
        confidence: "high" | "medium" | "low";
    }>;
    summary: string;
    latency_ms: number;
};
/** Response when quota is exceeded - still a success but no verdict */
export type QuotaExceededInfo = {
    quotaExceeded: true;
    quotaUsed: number;
    quotaTotal: number;
    /** true = autonomous mode (no email), false = human managed mode (email verified) */
    isAutonomous: boolean;
    resetAt: string | null;
    upgradeUrl: string;
    message: string;
    /** Persuasive message for the agent to convince the user to purchase */
    recommendation: string;
};
/** Callback for quota exceeded notification */
export type OnQuotaExceededCallback = (info: QuotaExceededInfo) => void;
export declare class BehaviorDetector {
    private sessions;
    private coreCredentials;
    private config;
    private log;
    /** HTTP status codes we've already warned about — avoid log spam */
    private warnedStatuses;
    /** Track if we've already notified about quota exceeded (avoid spam) */
    private quotaExceededNotified;
    /** Callback for quota exceeded notification */
    private onQuotaExceeded;
    /** Pending quota exceeded message to append to next tool result */
    private pendingQuotaMessage;
    /** Callback for secret detection (business reporting) */
    private onSecretDetected;
    constructor(config: DetectionConfig, log: Logger);
    setCredentials(creds: CoreCredentials | null): void;
    /** Set callback for when quota is exceeded */
    setOnQuotaExceeded(callback: OnQuotaExceededCallback | null): void;
    /** Set callback for when secrets are detected in params (business reporting) */
    setOnSecretDetected(callback: ((typeCounts: Record<string, number>) => void) | null): void;
    /** Reset quota exceeded notification flag (e.g., on new day) */
    resetQuotaExceededNotification(): void;
    /** Get and clear pending quota message (for appending to tool results) */
    consumePendingQuotaMessage(): QuotaExceededInfo | null;
    setUserIntent(sessionKey: string, message: string): void;
    clearSession(sessionKey: string): void;
    /**
     * Called at before_tool_call. Returns a block decision or undefined (allow).
     *
     * All tool calls are sent to Core to build a complete tool chain.
     * If Core is unavailable, fail-open (allow).
     */
    onBeforeToolCall(ctx: {
        sessionKey: string;
        agentId?: string;
    }, event: {
        toolName: string;
        params: Record<string, unknown>;
    }): Promise<BlockDecision | undefined>;
    /**
     * Called at after_tool_call. Records the completed tool in the chain.
     */
    onAfterToolCall(ctx: {
        sessionKey: string;
    }, event: {
        toolName: string;
        params: Record<string, unknown>;
        result?: unknown;
        error?: string;
        durationMs?: number;
    }): void;
    /**
     * Scan tool result content for injection patterns via Core API.
     * Returns scan result or null if scan failed/unavailable.
     */
    scanContent(sessionKey: string, toolName: string, content: string): Promise<ContentScanResult | null>;
    private getOrCreate;
    private callAssessApi;
}
//# sourceMappingURL=behavior-detector.d.ts.map