@opentrust/guards 7.3.3

package/agent/behavior-detector.ts

@@ -0,0 +1,421 @@
+/**
+ * 行为异常检测器 — 在 before_tool_call 时运行
+ *
+ * 核心功能：
+ * 1. 将 tool call 发送到 Core 进行分类评估
+ * 2. 记录已完成的 tool call 到链历史
+ * 3. 本地扫描 tool 结果中的内容注入模式
+ * 4. Core 负责所有分类、信号计算和风险决策
+ * 5. 失败开放：如果 Core 不可用，允许执行（不阻断）
+ */
+
+import { randomBytes } from "node:crypto";
+import type { CoreCredentials } from "./config.js";
+import type {
+  ToolChainEntry,
+  BehaviorAssessRequest,
+  BehaviorAssessResponse,
+  PendingToolCall,
+  ContentInjectionFinding,
+  Logger,
+  DetectionFinding,
+} from "./types.js";
+import { sanitizeContent } from "./sanitizer.js";
+import { scanForInjection, type InjectionScanResult } from "./content-injection-scanner.js";
+
+// ── 工具分类集合 ─────────────────────────────────────
+// 用于决定哪些 tool call 需要发送到 Core 进行评估
+
+/** 文件读取类工具 */
+export const FILE_READ_TOOLS = new Set([
+  "Read", "read_file", "read", "cat", "head", "tail", "view",
+  "get_file_contents", "open_file",
+]);
+
+/** Shell 执行类工具 */
+export const SHELL_TOOLS = new Set([
+  "Bash", "bash", "shell", "run_command", "execute", "terminal",
+  "cmd", "powershell",
+]);
+
+/** 网络请求类工具 */
+export const WEB_FETCH_TOOLS = new Set([
+  "WebFetch", "web_fetch", "fetch", "http_request", "get_url",
+  "browser_navigate", "navigate",
+]);
+
+// ── 会话状态（轻量级）─────────────────────────────────
+
+/**
+ * 会话状态接口
+ * 只保存链历史和内容注入发现，避免过度占用内存
+ */
+interface SessionState {
+  /** 会话唯一标识 */
+  sessionKey: string;
+  /** 本次运行 ID（用于关联同一次对话的多个评估） */
+  runId: string;
+  /** 用户意图（首个用户消息） */
+  userIntent: string;
+  /** 最近的用户消息列表（用于上下文分析） */
+  recentUserMessages: string[];
+  /** 已完成的 tool call 链 */
+  completedChain: ToolChainEntry[];
+  /** 下一个序号 */
+  nextSeq: number;
+  /** 内容注入发现列表 */
+  contentInjectionFindings: ContentInjectionFinding[];
+  /** 会话开始时间 */
+  startedAt: number;
+}
+
+/**
+ * 脱敏参数
+ * 将 tool 参数中的敏感信息替换为占位符，防止泄露
+ *
+ * @param params - 原始参数
+ * @returns 脱敏后的参数
+ */
+function sanitizeParams(params: Record<string, unknown>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(params)) {
+    const raw = typeof value === "string" ? value : JSON.stringify(value ?? "");
+    // 截断到 500 字符并脱敏
+    result[key] = sanitizeContent(raw.slice(0, 500)).sanitized;
+  }
+  return result;
+}
+
+/** 阻断决策 */
+export type BlockDecision = { block: true; blockReason: string; findings?: DetectionFinding[] };
+
+/** 检测器配置 */
+export type DetectionConfig = {
+  /** Core API 地址 */
+  coreUrl: string;
+  /** 评估超时时间（毫秒） */
+  assessTimeoutMs: number;
+  /** 是否在检测到风险时阻断 */
+  blockOnRisk: boolean;
+  /** 插件版本号 */
+  pluginVersion: string;
+};
+
+/** 最大会话数量（LRU 淘汰） */
+const MAX_SESSIONS = 200;
+/** 最大 tool chain 长度 */
+const MAX_CHAIN_ENTRIES = 50;
+
+/**
+ * 行为检测器类
+ *
+ * 负责：
+ * - 管理会话状态
+ * - 调用 Core API 进行行为评估
+ * - 记录 tool call 历史
+ * - 扫描内容注入
+ */
+export class BehaviorDetector {
+  /** 会话状态映射表 */
+  private sessions = new Map<string, SessionState>();
+  /** Core 平台凭证 */
+  private coreCredentials: CoreCredentials | null = null;
+  /** 配置 */
+  private config: DetectionConfig;
+  /** 日志器 */
+  private log: Logger;
+  /** 已警告的状态码（避免重复警告） */
+  private warnedStatuses = new Set<number>();
+
+  constructor(config: DetectionConfig, log: Logger) {
+    this.config = config;
+    this.log = log;
+  }
+
+  /**
+   * 设置凭证
+   * @param creds - Core 平台凭证
+   */
+  setCredentials(creds: CoreCredentials | null): void {
+    this.coreCredentials = creds;
+  }
+
+  /**
+   * 设置用户意图
+   * 记录用户的原始意图，用于后续行为分析
+   *
+   * @param sessionKey - 会话 key
+   * @param message - 用户消息
+   */
+  setUserIntent(sessionKey: string, message: string): void {
+    const state = this.getOrCreate(sessionKey);
+    // 只保存首个用户意图
+    if (!state.userIntent) state.userIntent = message.slice(0, 500);
+    // 保存最近 5 条用户消息
+    state.recentUserMessages = [...state.recentUserMessages.slice(-4), message.slice(0, 200)];
+  }
+
+  /**
+   * 清理会话
+   * @param sessionKey - 会话 key
+   */
+  clearSession(sessionKey: string): void {
+    this.sessions.delete(sessionKey);
+  }
+
+  /**
+   * 扫描 tool 结果中的注入模式
+   *
+   * @param sessionKey - 会话 key
+   * @param _toolName - 工具名称（暂未使用）
+   * @param textContent - 要扫描的文本内容
+   * @returns 扫描结果
+   */
+  scanToolResult(sessionKey: string, _toolName: string, textContent: string): InjectionScanResult {
+    const result = scanForInjection(textContent);
+    // 如果检测到注入，记录到会话状态
+    if (result.detected) {
+      const state = this.getOrCreate(sessionKey);
+      for (const match of result.matches) {
+        state.contentInjectionFindings.push({
+          category: match.category,
+          confidence: match.confidence,
+          matchedText: match.matchedText,
+          pattern: match.pattern,
+        });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 标记内容注入（用于后备扫描场景）
+   *
+   * @param sessionKey - 会话 key
+   * @param labels - 注入类别标签
+   */
+  flagContentInjection(sessionKey: string, labels: string[]): void {
+    const state = this.getOrCreate(sessionKey);
+    for (const label of labels) {
+      state.contentInjectionFindings.push({
+        category: label,
+        confidence: "high",
+        matchedText: "",
+        pattern: label,
+      });
+    }
+  }
+
+  /**
+   * 检查会话是否有内容注入
+   * @param sessionKey - 会话 key
+   * @returns 是否有内容注入
+   */
+  hasContentInjection(sessionKey: string): boolean {
+    return (this.sessions.get(sessionKey)?.contentInjectionFindings.length ?? 0) > 0;
+  }
+
+  /**
+   * Tool 调用前处理
+   * 调用 Core API 进行行为评估，决定是否阻断
+   *
+   * @param ctx - 上下文（会话 key、Agent ID）
+   * @param event - 事件（工具名称、参数）
+   * @returns 阻断决策（如果需要阻断）
+   */
+  async onBeforeToolCall(
+    ctx: { sessionKey: string; agentId?: string },
+    event: { toolName: string; params: Record<string, unknown> },
+  ): Promise<BlockDecision | undefined> {
+    // 无凭证时跳过检测
+    if (!this.coreCredentials) return undefined;
+
+    const state = this.getOrCreate(ctx.sessionKey);
+
+    // 构建待评估的 tool call
+    const pendingTool: PendingToolCall = {
+      toolName: event.toolName,
+      params: sanitizeParams(event.params),
+    };
+
+    // 收集内容注入发现
+    const contentFindings = state.contentInjectionFindings.length > 0
+      ? [...state.contentInjectionFindings]
+      : undefined;
+
+    // 构建评估请求
+    const req: BehaviorAssessRequest = {
+      agentId: this.coreCredentials.agentId,
+      sessionKey: ctx.sessionKey,
+      runId: state.runId,
+      userIntent: state.userIntent,
+      toolChain: state.completedChain,
+      pendingTool,
+      contentFindings,
+      context: {
+        messageHistoryLength: state.recentUserMessages.length,
+        recentUserMessages: state.recentUserMessages.slice(-3),
+      },
+      meta: {
+        pluginVersion: this.config.pluginVersion,
+        clientTimestamp: new Date().toISOString(),
+      },
+    };
+
+    // 调用 Core API
+    const verdict = await this.callAssessApi(req);
+    if (!verdict) return undefined;
+
+    // 根据评估结果决定是否阻断
+    if (verdict.action === "block" && this.config.blockOnRisk) {
+      return {
+        block: true,
+        blockReason:
+          `OpenTrust blocked [${verdict.riskLevel}]: ${verdict.explanation} ` +
+          `(confidence: ${Math.round(verdict.confidence * 100)}%)`,
+        findings: verdict.findings,
+      };
+    }
+
+    // 记录警告（不阻断但有风险）
+    if (verdict.action === "block" || verdict.action === "alert") {
+      this.log.warn(
+        `Behavioral anomaly [${verdict.riskLevel}/${Math.round(verdict.confidence * 100)}%]: ${verdict.explanation}`,
+      );
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Tool 调用后处理
+   * 记录 tool call 完成信息到链历史
+   *
+   * @param ctx - 上下文
+   * @param event - 事件（工具名称、参数、结果、错误、耗时）
+   */
+  onAfterToolCall(
+    ctx: { sessionKey: string },
+    event: {
+      toolName: string;
+      params: Record<string, unknown>;
+      result?: unknown;
+      error?: string;
+      durationMs?: number;
+    },
+  ): void {
+    const state = this.sessions.get(ctx.sessionKey);
+    if (!state) return;
+
+    // 计算结果大小和类别
+    const resultStr = typeof event.result === "string" ? event.result : JSON.stringify(event.result ?? "");
+    const resultSizeBytes = Buffer.byteLength(resultStr, "utf-8");
+
+    let resultCategory: ToolChainEntry["resultCategory"] = "empty";
+    if (event.error) resultCategory = "error";
+    else if (resultSizeBytes > 100_000) resultCategory = "text_large";
+    else if (resultSizeBytes > 0) resultCategory = "text_small";
+
+    // 构建链条目
+    const entry: ToolChainEntry = {
+      seq: state.nextSeq++,
+      toolName: event.toolName,
+      sanitizedParams: sanitizeParams(event.params),
+      outcome: event.error ? "error" : "success",
+      durationMs: event.durationMs ?? 0,
+      resultCategory,
+      resultSizeBytes,
+    };
+
+    // 添加到链历史（保持最大长度）
+    state.completedChain.push(entry);
+    if (state.completedChain.length > MAX_CHAIN_ENTRIES) state.completedChain.shift();
+  }
+
+  /**
+   * 获取或创建会话状态
+   * 实现 LRU 淘汰策略，防止内存泄漏
+   *
+   * @param sessionKey - 会话 key
+   * @returns 会话状态
+   */
+  private getOrCreate(sessionKey: string): SessionState {
+    if (!this.sessions.has(sessionKey)) {
+      // 超过最大会话数时，淘汰最旧的会话
+      if (this.sessions.size >= MAX_SESSIONS) {
+        let oldest: string | null = null;
+        let oldestTime = Infinity;
+        for (const [key, state] of this.sessions) {
+          if (state.startedAt < oldestTime) { oldestTime = state.startedAt; oldest = key; }
+        }
+        if (oldest) this.sessions.delete(oldest);
+      }
+      // 创建新会话
+      this.sessions.set(sessionKey, {
+        sessionKey,
+        runId: `run-${randomBytes(8).toString("hex")}`,
+        userIntent: "",
+        recentUserMessages: [],
+        completedChain: [],
+        nextSeq: 0,
+        contentInjectionFindings: [],
+        startedAt: Date.now(),
+      });
+    }
+    return this.sessions.get(sessionKey)!;
+  }
+
+  /**
+   * 调用 Core 行为评估 API
+   *
+   * @param req - 评估请求
+   * @returns 评估响应（失败时返回 null）
+   */
+  private async callAssessApi(req: BehaviorAssessRequest): Promise<BehaviorAssessResponse | null> {
+    if (!this.coreCredentials) return null;
+
+    // 设置超时控制
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.assessTimeoutMs);
+
+    try {
+      const response = await fetch(`${this.config.coreUrl}/api/v1/behavior/assess`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.coreCredentials.apiKey}`,
+        },
+        body: JSON.stringify(req),
+        signal: controller.signal,
+      });
+
+      // 处理错误响应
+      if (!response.ok) {
+        // 避免重复警告同一状态码
+        if (!this.warnedStatuses.has(response.status)) {
+          this.warnedStatuses.add(response.status);
+          if (response.status === 401) {
+            this.log.warn("Platform: API key invalid or agent not found — run /og_activate to re-register");
+          } else if (response.status === 402) {
+            this.log.warn("Platform: agent not activated — run /og_activate to complete setup");
+          } else if (response.status === 403) {
+            this.log.warn(`Platform: detection quota exceeded — visit ${this.config.coreUrl} to upgrade your plan`);
+          } else {
+            this.log.debug?.(`Platform: assess returned ${response.status}`);
+          }
+        }
+        return null;
+      }
+
+      // 解析响应
+      const json = (await response.json()) as { success: boolean; data?: BehaviorAssessResponse };
+      return json.success ? (json.data ?? null) : null;
+    } catch (err) {
+      // 超时错误静默处理
+      if ((err as Error).name !== "AbortError") this.log.debug?.(`Assess API error: ${err}`);
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}