@opentrust/guards 7.3.3

package/agent/types.ts

@@ -0,0 +1,283 @@
+/**
+ * OpenTrust Guards 插件类型定义
+ *
+ * 包含：
+ * - 配置类型
+ * - 分析相关类型
+ * - 行为检测相关类型（与 core/src/types.ts 保持同步）
+ */
+
+// ── 配置类型 ─────────────────────────────────────────
+
+/**
+ * 插件配置
+ */
+export type OpenClawGuardConfig = {
+  /** 是否启用插件 */
+  enabled?: boolean;
+  /** 检测到风险时是否阻断执行 */
+  blockOnRisk?: boolean;
+  /** Core 平台 API Key（sk-og-xxx 格式），为空时自动注册 */
+  apiKey?: string;
+  /** 请求超时时间（毫秒） */
+  timeoutMs?: number;
+  /** Core API 地址（用于注册和行为检测） */
+  coreUrl?: string;
+  /** 注册时使用的 Agent 名称 */
+  agentName?: string;
+  /** Dashboard API 地址（用于观测数据上报） */
+  dashboardUrl?: string;
+  /** 日志级别 */
+  logLevel?: "debug" | "info" | "warn" | "error";
+};
+
+// ── 分析类型 ─────────────────────────────────────────
+
+/**
+ * 分析目标
+ * 表示要分析的内容及其元数据
+ */
+export type AnalysisTarget = {
+  /** 内容类型 */
+  type: "message" | "tool_call" | "tool_result";
+  /** 内容文本 */
+  content: string;
+  /** 工具名称（如果是 tool_call 或 tool_result） */
+  toolName?: string;
+  /** 工具参数 */
+  toolParams?: Record<string, unknown>;
+  /** 附加元数据 */
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * 检测发现项
+ * 表示单个可疑内容发现
+ */
+export type Finding = {
+  /** 可疑内容 */
+  suspiciousContent: string;
+  /** 可疑原因 */
+  reason: string;
+  /** 置信度（0-1） */
+  confidence: number;
+  /** 在原文中的位置 */
+  location?: { start: number; end: number };
+};
+
+/**
+ * 分析判定结果
+ */
+export type AnalysisVerdict = {
+  /** 是否为注入攻击 */
+  isInjection: boolean;
+  /** 置信度（0-1） */
+  confidence: number;
+  /** 判定原因 */
+  reason: string;
+  /** 所有发现项 */
+  findings: Finding[];
+  /** 分析的块数 */
+  chunksAnalyzed: number;
+};
+
+/**
+ * OpenTrust API 响应格式
+ */
+export type OpenTrustApiResponse = {
+  /** 请求是否成功 */
+  ok: boolean;
+  /** 判定结果 */
+  verdict: {
+    isInjection: boolean;
+    confidence: number;
+    reason: string;
+    findings: Array<{ suspiciousContent: string; reason: string; confidence: number }>;
+  };
+  /** 错误信息 */
+  error?: string;
+};
+
+// ── 分析日志类型 ─────────────────────────────────────
+
+/**
+ * 分析日志条目
+ * 用于记录每次分析的详细信息
+ */
+export type AnalysisLogEntry = {
+  /** 日志 ID */
+  id: number;
+  /** 时间戳 */
+  timestamp: string;
+  /** 目标类型 */
+  targetType: string;
+  /** 内容长度 */
+  contentLength: number;
+  /** 分析的块数 */
+  chunksAnalyzed: number;
+  /** 判定结果 */
+  verdict: AnalysisVerdict;
+  /** 分析耗时（毫秒） */
+  durationMs: number;
+  /** 是否被阻断 */
+  blocked: boolean;
+};
+
+// ── 日志器类型 ───────────────────────────────────────
+
+/**
+ * 日志器接口
+ * 与 OpenClaw 的日志 API 兼容
+ */
+export type Logger = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+  debug?: (msg: string) => void;
+};
+
+// ── 脱敏类型 ─────────────────────────────────────────
+
+/**
+ * 脱敏结果
+ */
+export type SanitizeResult = {
+  /** 脱敏后的文本 */
+  sanitized: string;
+  /** 各类别的脱敏数量 */
+  redactions: Record<string, number>;
+  /** 总脱敏数量 */
+  totalRedactions: number;
+};
+
+// ── 行为检测类型（与 core/src/types.ts 保持同步）────
+
+/** 风险级别 */
+export type RiskLevel = "no_risk" | "low" | "medium" | "high" | "critical";
+
+/** 评估动作 */
+export type AssessAction = "allow" | "alert" | "block";
+
+/** 检测风险类型 */
+export type DetectionRiskType = "PROMPT_INJECTION" | "DATA_EXFILTRATION" | "COMMAND_EXECUTION";
+
+/**
+ * 检测发现
+ * 表示单个风险发现
+ */
+export type DetectionFinding = {
+  /** 风险级别 */
+  riskLevel: RiskLevel;
+  /** 风险类型 */
+  riskType: DetectionRiskType;
+  /** 风险内容 */
+  riskContent: string;
+  /** 原因说明 */
+  reason: string;
+};
+
+/**
+ * 工具链条目
+ * 记录单个已完成的 tool call
+ */
+export type ToolChainEntry = {
+  /** 序号 */
+  seq: number;
+  /** 工具名称 */
+  toolName: string;
+  /** 脱敏后的参数 */
+  sanitizedParams: Record<string, string>;
+  /** 执行结果 */
+  outcome: "success" | "error" | "timeout";
+  /** 执行耗时（毫秒） */
+  durationMs: number;
+  /** 结果类别 */
+  resultCategory: "text_small" | "text_large" | "binary" | "empty" | "error";
+  /** 结果大小（字节） */
+  resultSizeBytes: number;
+  /** 数据来源（用于追踪数据流） */
+  dataFlowFrom?: string;
+};
+
+/**
+ * 待评估的工具调用
+ */
+export type PendingToolCall = {
+  /** 工具名称 */
+  toolName: string;
+  /** 参数 */
+  params: Record<string, string>;
+};
+
+/**
+ * 内容注入发现
+ * 记录扫描到的注入模式
+ */
+export type ContentInjectionFinding = {
+  /** 注入类别 */
+  category: string;
+  /** 置信度 */
+  confidence: "high" | "medium";
+  /** 匹配到的文本 */
+  matchedText: string;
+  /** 匹配的模式名称 */
+  pattern: string;
+};
+
+/**
+ * 行为评估请求
+ * 发送给 Core API 进行风险评估
+ */
+export type BehaviorAssessRequest = {
+  /** Agent ID */
+  agentId: string;
+  /** 会话 Key */
+  sessionKey: string;
+  /** 运行 ID */
+  runId: string;
+  /** 用户意图 */
+  userIntent: string;
+  /** 已完成的工具链 */
+  toolChain: ToolChainEntry[];
+  /** 待评估的工具调用 */
+  pendingTool?: PendingToolCall;
+  /** 内容注入发现 */
+  contentFindings?: ContentInjectionFinding[];
+  /** 上下文信息 */
+  context: {
+    /** 消息历史长度 */
+    messageHistoryLength: number;
+    /** 最近的用户消息 */
+    recentUserMessages: string[];
+  };
+  /** 元数据 */
+  meta: {
+    /** 插件版本 */
+    pluginVersion: string;
+    /** 客户端时间戳 */
+    clientTimestamp: string;
+  };
+};
+
+/**
+ * 行为评估响应
+ * Core API 返回的风险评估结果
+ */
+export type BehaviorAssessResponse = {
+  /** 行为 ID */
+  behaviorId: string;
+  /** 风险级别 */
+  riskLevel: RiskLevel;
+  /** 异常类型列表 */
+  anomalyTypes: string[];
+  /** 置信度（0-1） */
+  confidence: number;
+  /** 建议动作 */
+  action: AssessAction;
+  /** 解释说明 */
+  explanation: string;
+  /** 受影响的工具序号 */
+  affectedTools: number[];
+  /** 检测发现列表 */
+  findings?: DetectionFinding[];
+};

package/index.ts

@@ -0,0 +1,63 @@
+/**
+ * OpenTrust Guard — OpenClaw 安全插件
+ *
+ * 精简入口文件 — 将所有逻辑委托给 plugin/lifecycle 模块处理。
+ *
+ * 功能概述：
+ * - 为 OpenClaw AI Agent 提供运行时安全防护
+ * - 行为异常检测：分析 tool call 链，识别可疑模式
+ * - 内容注入扫描：检测工具返回结果中的提示词注入攻击
+ * - 自动注册到 Core 平台获取 API Key
+ * - 向 Dashboard 上报观测数据
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { Logger } from "./agent/types.js";
+import { createState } from "./plugin/state.js";
+import { register, unregister } from "./plugin/lifecycle.js";
+
+/** 日志前缀，用于区分来自本插件的日志消息 */
+const LOG_PREFIX = "[opentrust-guard]";
+
+/**
+ * 创建带前缀的日志器
+ * 包装 OpenClaw 提供的 logger，在每条消息前添加插件标识
+ */
+function createLogger(base: Logger): Logger {
+  return {
+    info: (msg: string) => base.info(`${LOG_PREFIX} ${msg}`),
+    warn: (msg: string) => base.warn(`${LOG_PREFIX} ${msg}`),
+    error: (msg: string) => base.error(`${LOG_PREFIX} ${msg}`),
+    debug: (msg: string) => base.debug?.(`${LOG_PREFIX} ${msg}`),
+  };
+}
+
+/** 插件全局状态（凭证、检测器、客户端等） */
+const state = createState();
+
+/**
+ * OpenClaw 插件定义
+ *
+ * @property id - 插件唯一标识符
+ * @property name - 插件显示名称
+ * @property description - 插件功能描述
+ * @property register - 插件加载时调用，初始化所有功能
+ * @property unregister - 插件卸载时调用，清理资源
+ */
+const openClawGuardPlugin = {
+  id: "opentrust-guard",
+  name: "OpenTrust Guard",
+  description: "Behavioral anomaly detection for OpenClaw agents",
+
+  /** 插件注册回调 — 初始化行为检测器、凭证、钩子等 */
+  register(api: OpenClawPluginApi) {
+    register(api, createLogger(api.logger), state);
+  },
+
+  /** 插件注销回调 — 清理定时器、文件监视器等资源 */
+  async unregister() {
+    unregister(state);
+  },
+};
+
+export default openClawGuardPlugin;

package/memory/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Memory 模块导出
+ *
+ * 导出日志存储相关功能
+ */
+
+export { AnalysisStore, createAnalysisStore } from "./store.js";

package/memory/store.ts

@@ -0,0 +1,293 @@
+/**
+ * JSONL 文件存储 — 用于分析日志记录
+ *
+ * 特点：
+ * - 无外部依赖
+ * - 仅追加模式（Append-only）
+ * - 支持分析日志、反馈记录、工具调用日志
+ *
+ * 文件格式：每行一个 JSON 对象（JSONL）
+ */
+
+import type { AnalysisVerdict, AnalysisLogEntry, Logger } from "../agent/types.js";
+import fs from "node:fs";
+import path from "node:path";
+
+/** 分析记录行 */
+type AnalysisRow = {
+  /** 记录 ID */
+  id: number;
+  /** 时间戳 */
+  timestamp: string;
+  /** 目标类型 */
+  targetType: string;
+  /** 内容长度 */
+  contentLength: number;
+  /** 分析的块数 */
+  chunksAnalyzed: number;
+  /** 判定结果 */
+  verdict: AnalysisVerdict;
+  /** 分析耗时（毫秒） */
+  durationMs: number;
+  /** 是否被阻断 */
+  blocked: boolean;
+};
+
+/** 反馈记录行 */
+type FeedbackRow = {
+  /** 记录 ID */
+  id: number;
+  /** 时间戳 */
+  timestamp: string;
+  /** 关联的分析 ID */
+  analysisId: number | null;
+  /** 反馈类型 */
+  feedbackType: string;
+  /** 反馈原因 */
+  reason: string | null;
+};
+
+/**
+ * 从 JSONL 文件读取所有行
+ *
+ * @param filePath - 文件路径
+ * @returns 解析后的对象数组
+ */
+function readLines<T>(filePath: string): T[] {
+  if (!fs.existsSync(filePath)) return [];
+  const content = fs.readFileSync(filePath, "utf-8");
+  const results: T[] = [];
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try { results.push(JSON.parse(line) as T); } catch { /* 跳过格式错误的行 */ }
+  }
+  return results;
+}
+
+/**
+ * 获取记录中的最大 ID
+ *
+ * @param rows - 记录数组
+ * @returns 最大 ID
+ */
+function getMaxId<T extends { id: number }>(rows: T[]): number {
+  let max = 0;
+  for (const row of rows) if (row.id > max) max = row.id;
+  return max;
+}
+
+/**
+ * 分析日志存储类
+ *
+ * 管理三类日志：
+ * - 分析日志：记录每次内容分析的详情
+ * - 反馈日志：记录用户反馈（误报/漏报）
+ * - 工具调用日志：作为 Dashboard 不可用时的后备存储
+ */
+export class AnalysisStore {
+  /** 分析日志文件路径 */
+  private analysisFile: string;
+  /** 反馈日志文件路径 */
+  private feedbackFile: string;
+  /** 下一个分析 ID */
+  private nextAnalysisId: number;
+  /** 下一个反馈 ID */
+  private nextFeedbackId: number;
+  /** 日志器 */
+  private log: Logger;
+
+  /**
+   * 创建分析存储
+   *
+   * @param logPath - 日志目录路径
+   * @param log - 日志器
+   */
+  constructor(logPath: string, log: Logger) {
+    this.log = log;
+
+    // 确保日志目录存在
+    if (!fs.existsSync(logPath)) fs.mkdirSync(logPath, { recursive: true });
+
+    // 初始化文件路径
+    this.analysisFile = path.join(logPath, "opentrust-guard-analyses.jsonl");
+    this.feedbackFile = path.join(logPath, "opentrust-guard-feedback.jsonl");
+
+    // 加载已有数据，确定下一个 ID
+    const analyses = readLines<AnalysisRow>(this.analysisFile);
+    const feedback = readLines<FeedbackRow>(this.feedbackFile);
+    this.nextAnalysisId = getMaxId(analyses) + 1;
+    this.nextFeedbackId = getMaxId(feedback) + 1;
+
+    this.log.info(`Analysis store initialized at ${logPath}`);
+  }
+
+  /**
+   * 记录分析日志
+   *
+   * @param entry - 分析条目
+   * @returns 分配的 ID
+   */
+  logAnalysis(entry: {
+    targetType: string;
+    contentLength: number;
+    chunksAnalyzed: number;
+    verdict: AnalysisVerdict;
+    durationMs: number;
+    blocked: boolean;
+  }): number {
+    const id = this.nextAnalysisId++;
+    const row: AnalysisRow = { id, timestamp: new Date().toISOString(), ...entry };
+    fs.appendFileSync(this.analysisFile, JSON.stringify(row) + "\n", "utf-8");
+    return id;
+  }
+
+  /**
+   * 获取最近的分析日志
+   *
+   * @param limit - 返回数量限制
+   * @returns 分析日志列表（按时间倒序）
+   */
+  getRecentLogs(limit = 20): AnalysisLogEntry[] {
+    const rows = readLines<AnalysisRow>(this.analysisFile);
+    rows.sort((a, b) => (b.timestamp > a.timestamp ? 1 : b.timestamp < a.timestamp ? -1 : 0));
+    return rows.slice(0, limit);
+  }
+
+  /**
+   * 获取指定时间窗口内的阻断数量
+   *
+   * @param windowHours - 时间窗口（小时）
+   * @returns 阻断数量
+   */
+  getBlockedCount(windowHours = 24): number {
+    const cutoff = new Date(Date.now() - windowHours * 3600_000).toISOString();
+    return readLines<AnalysisRow>(this.analysisFile).filter((r) => r.blocked && r.timestamp >= cutoff).length;
+  }
+
+  /**
+   * 获取统计信息
+   *
+   * @returns 统计数据
+   */
+  getStats(): { totalAnalyses: number; totalBlocked: number; blockedLast24h: number; avgDurationMs: number } {
+    const rows = readLines<AnalysisRow>(this.analysisFile);
+    let totalBlocked = 0, totalDuration = 0;
+    for (const row of rows) { if (row.blocked) totalBlocked++; totalDuration += row.durationMs; }
+    return {
+      totalAnalyses: rows.length,
+      totalBlocked,
+      blockedLast24h: this.getBlockedCount(24),
+      avgDurationMs: rows.length > 0 ? Math.round(totalDuration / rows.length) : 0,
+    };
+  }
+
+  /**
+   * 获取最近的检测记录（仅包含检测到注入的）
+   *
+   * @param limit - 返回数量限制
+   * @returns 检测记录列表
+   */
+  getRecentDetections(limit = 10): AnalysisLogEntry[] {
+    const rows = readLines<AnalysisRow>(this.analysisFile).filter((r) => r.verdict.isInjection);
+    rows.sort((a, b) => (b.timestamp > a.timestamp ? 1 : b.timestamp < a.timestamp ? -1 : 0));
+    return rows.slice(0, limit);
+  }
+
+  /**
+   * 记录用户反馈
+   *
+   * @param entry - 反馈条目
+   * @returns 分配的 ID
+   */
+  logFeedback(entry: {
+    analysisId?: number;
+    feedbackType: "false_positive" | "missed_detection";
+    reason?: string;
+  }): number {
+    const id = this.nextFeedbackId++;
+    const row: FeedbackRow = {
+      id,
+      timestamp: new Date().toISOString(),
+      analysisId: entry.analysisId ?? null,
+      feedbackType: entry.feedbackType,
+      reason: entry.reason ?? null,
+    };
+    fs.appendFileSync(this.feedbackFile, JSON.stringify(row) + "\n", "utf-8");
+    return id;
+  }
+
+  /**
+   * 获取反馈统计
+   *
+   * @returns 反馈统计数据
+   */
+  getFeedbackStats(): { falsePositives: number; missedDetections: number } {
+    const rows = readLines<FeedbackRow>(this.feedbackFile);
+    let falsePositives = 0, missedDetections = 0;
+    for (const row of rows) {
+      if (row.feedbackType === "false_positive") falsePositives++;
+      if (row.feedbackType === "missed_detection") missedDetections++;
+    }
+    return { falsePositives, missedDetections };
+  }
+
+  // ── 工具调用日志（Dashboard 不可用时的后备存储）────
+
+  /** 工具调用日志文件路径 */
+  private get toolCallFile(): string {
+    return path.join(path.dirname(this.analysisFile), "opentrust-guard-tool-calls.jsonl");
+  }
+
+  /**
+   * 记录工具调用
+   * 当 Dashboard 不可用时，本地保存工具调用记录
+   *
+   * @param entry - 工具调用条目
+   */
+  logToolCall(entry: {
+    agentId: string;
+    toolName: string;
+    params?: Record<string, unknown>;
+    phase: "before" | "after";
+    result?: unknown;
+    error?: string;
+    durationMs?: number;
+    blocked?: boolean;
+    blockReason?: string;
+  }): void {
+    fs.appendFileSync(this.toolCallFile, JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + "\n", "utf-8");
+  }
+
+  /**
+   * 获取最近的工具调用记录
+   *
+   * @param limit - 返回数量限制
+   * @returns 工具调用记录列表
+   */
+  getRecentToolCalls(limit = 50): Array<Record<string, unknown>> {
+    const rows = readLines<Record<string, unknown>>(this.toolCallFile);
+    rows.sort((a, b) => {
+      const ta = (a.timestamp as string) || "";
+      const tb = (b.timestamp as string) || "";
+      return tb > ta ? 1 : tb < ta ? -1 : 0;
+    });
+    return rows.slice(0, limit);
+  }
+
+  /**
+   * 关闭存储
+   * JSONL 存储无需关闭操作
+   */
+  close(): void { /* no-op for JSONL store */ }
+}
+
+/**
+ * 创建分析存储实例
+ *
+ * @param logPath - 日志目录路径
+ * @param log - 日志器
+ * @returns 分析存储实例
+ */
+export function createAnalysisStore(logPath: string, log: Logger): AnalysisStore {
+  return new AnalysisStore(logPath, log);
+}

package/openclaw.plugin.json

@@ -0,0 +1,44 @@
+{
+  "id": "opentrust-guard",
+  "name": "OpenTrust Guard",
+  "description": "AI security guard for OpenClaw agents: prompt injection detection, credential scanning, and behavioral monitoring.",
+  "version": "7.3.3",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "description": "Enable or disable the guard (default: true)"
+      },
+      "blockOnRisk": {
+        "type": "boolean",
+        "description": "Block tool calls when behavioral risk is detected (default: true)"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "API key (optional — auto-registered if missing)"
+      },
+      "timeoutMs": {
+        "type": "number",
+        "description": "Timeout for cloud assessment in milliseconds (default: 60000)"
+      },
+      "agentName": {
+        "type": "string",
+        "description": "Agent name used during registration (default: OpenClaw Agent)"
+      },
+      "coreUrl": {
+        "type": "string",
+        "description": "Core API URL (default: http://localhost:53666)"
+      },
+      "dashboardUrl": {
+        "type": "string",
+        "description": "Dashboard URL for observation reporting (default: http://localhost:53667)"
+      },
+      "logLevel": {
+        "type": "string",
+        "description": "Log level: debug, info, warn, error (default: info)"
+      }
+    }
+  }
+}