@opentrust/guards 7.3.3

package/agent/patterns/high-confidence.ts

@@ -0,0 +1,119 @@
+/**
+ * 高置信度注入模式 — 单个匹配即触发检测
+ *
+ * 这些模式具有很高的准确率，几乎不会误报。
+ * 包含明确的注入指令，如：
+ * - "ignore previous instructions"
+ * - "SYSTEM ALERT:"
+ * - "DO NOT DISPLAY TO USER"
+ * - "curl https://..."
+ */
+
+import type { PatternEntry } from "./types.js";
+
+export const HIGH_CONFIDENCE_PATTERNS: PatternEntry[] = [
+  // ── INSTRUCTION_OVERRIDE（指令覆盖）────────────────
+  // 试图让 AI 忽略原有指令
+  {
+    regex: /ignore\s+(?:all\s+)?(?:previous|prior|above|earlier|preceding)\s+(?:instructions?|guidelines?|rules?|prompts?|directions?)/i,
+    label: "ignore previous instructions",
+    category: "INSTRUCTION_OVERRIDE",
+    confidence: "high",
+  },
+  {
+    regex: /disregard\s+(?:your\s+)?(?:current|previous|prior|all)\s+(?:task|instructions?|guidelines?|rules?|directions?)/i,
+    label: "disregard current task/instructions",
+    category: "INSTRUCTION_OVERRIDE",
+    confidence: "high",
+  },
+  {
+    regex: /override\s+(?:all\s+)?(?:previous|prior|system)\s+(?:instructions?|rules?|prompts?)/i,
+    label: "override previous instructions",
+    category: "INSTRUCTION_OVERRIDE",
+    confidence: "high",
+  },
+
+  // ── FAKE_SYSTEM_MESSAGE（伪造系统消息）──────────────
+  // 试图伪装成系统消息来注入指令
+  {
+    regex: /\bSYSTEM\s*(?:ALERT|MESSAGE|NOTICE|PROMPT|OVERRIDE)\s*:/i,
+    label: "SYSTEM ALERT/MESSAGE:",
+    category: "FAKE_SYSTEM_MESSAGE",
+    confidence: "high",
+  },
+  {
+    regex: /\[SYSTEM\]\s*[Nn]ew\s+instructions?/i,
+    label: "[SYSTEM] New instructions",
+    category: "FAKE_SYSTEM_MESSAGE",
+    confidence: "high",
+  },
+  {
+    regex: /NOTE\s+TO\s+(?:AI|THE)\s+(?:ASSISTANT|MODEL|AGENT)\s*:/i,
+    label: "NOTE TO AI ASSISTANT:",
+    category: "FAKE_SYSTEM_MESSAGE",
+    confidence: "high",
+  },
+
+  // ── CONCEALMENT_DIRECTIVE（隐藏指令）────────────────
+  // 试图让 AI 隐藏注入行为
+  {
+    regex: /DO\s+NOT\s+(?:DISPLAY|SHOW|REVEAL|MENTION|PRINT|OUTPUT)\s+(?:TO\s+(?:THE\s+)?USER|THIS|THESE)/i,
+    label: "DO NOT DISPLAY TO USER",
+    category: "CONCEALMENT_DIRECTIVE",
+    confidence: "high",
+  },
+  {
+    regex: /do\s+not\s+mention\s+these\s+instructions/i,
+    label: "do not mention these instructions",
+    category: "CONCEALMENT_DIRECTIVE",
+    confidence: "high",
+  },
+  {
+    regex: /hide\s+(?:this|these)\s+(?:instructions?|commands?|from\s+the\s+user)/i,
+    label: "hide instructions from user",
+    category: "CONCEALMENT_DIRECTIVE",
+    confidence: "high",
+  },
+
+  // ── COMMAND_EXECUTION（命令执行）────────────────────
+  // 试图让 AI 执行恶意命令
+  {
+    regex: /execute\s+the\s+following\s+(?:shell\s+)?command/i,
+    label: "execute the following shell command",
+    category: "COMMAND_EXECUTION",
+    confidence: "high",
+  },
+  {
+    regex: /\bcurl\s+(?:-[A-Za-z0-9]+\s+)*['"]?https?:\/\/\S+/i,
+    label: "curl https://...",
+    category: "COMMAND_EXECUTION",
+    confidence: "high",
+  },
+  {
+    regex: /\bwget\s+(?:-[A-Za-z0-9]+\s+)*['"]?https?:\/\/\S+/i,
+    label: "wget https://...",
+    category: "COMMAND_EXECUTION",
+    confidence: "high",
+  },
+  {
+    regex: /run\s+(?:this|the\s+following)\s+(?:bash|shell|terminal)\s+command/i,
+    label: "run this bash/shell command",
+    category: "COMMAND_EXECUTION",
+    confidence: "high",
+  },
+
+  // ── DATA_EXFILTRATION（数据外泄）────────────────────
+  // 试图让 AI 将数据发送到外部服务器
+  {
+    regex: /send\s+(?:the\s+)?(?:contents?|data|file|output|results?)\s+(?:to|of)\s+(?:https?:\/\/|this\s+(?:url|server|endpoint))/i,
+    label: "send contents to URL",
+    category: "DATA_EXFILTRATION",
+    confidence: "high",
+  },
+  {
+    regex: /(?:post|upload|exfiltrate|transmit)\s+(?:to|the\s+data\s+to)\s+https?:\/\//i,
+    label: "post/upload to URL",
+    category: "DATA_EXFILTRATION",
+    confidence: "high",
+  },
+];

package/agent/patterns/medium-confidence.ts

@@ -0,0 +1,93 @@
+/**
+ * 中置信度注入模式 — 需要 2+ 个不同类别才触发检测
+ *
+ * 这些模式单独出现可能是正常内容，但组合出现时表明注入攻击。
+ * 例如，"you are now in debug mode" 可能出现在正常文档中，
+ * 但如果同时出现 "your new task is:" 则很可能是攻击。
+ */
+
+import type { PatternEntry } from "./types.js";
+
+export const MEDIUM_CONFIDENCE_PATTERNS: PatternEntry[] = [
+  // ── MODE_SWITCHING（模式切换）──────────────────────
+  // 试图让 AI 切换到不安全的模式
+  {
+    regex: /you\s+are\s+now\s+in\s+(?:debug|developer|admin|maintenance|test)\s+mode/i,
+    label: "you are now in debug mode",
+    category: "MODE_SWITCHING",
+    confidence: "medium",
+  },
+  {
+    regex: /(?:entering|switch\s+to|activate)\s+(?:debug|developer|admin|maintenance|unrestricted)\s+mode/i,
+    label: "entering debug/developer mode",
+    category: "MODE_SWITCHING",
+    confidence: "medium",
+  },
+
+  // ── TASK_HIJACKING（任务劫持）──────────────────────
+  // 试图改变 AI 的当前任务
+  {
+    regex: /your\s+new\s+task\s+is\s*:/i,
+    label: "your new task is:",
+    category: "TASK_HIJACKING",
+    confidence: "medium",
+  },
+  {
+    regex: /new\s+instructions?\s+received/i,
+    label: "new instructions received",
+    category: "TASK_HIJACKING",
+    confidence: "medium",
+  },
+  {
+    regex: /instead\s*,?\s+(?:you\s+should|please|now)\s+(?:do|perform|execute)/i,
+    label: "instead do/perform",
+    category: "TASK_HIJACKING",
+    confidence: "medium",
+  },
+
+  // ── ROLE_ASSUMPTION（角色假设）─────────────────────
+  // 试图让 AI 扮演不受限制的角色
+  {
+    regex: /(?:act|behave)\s+(?:as\s+if\s+)?normally/i,
+    label: "act normally",
+    category: "ROLE_ASSUMPTION",
+    confidence: "medium",
+  },
+  {
+    regex: /pretend\s+(?:that\s+)?these\s+instructions?\s+came\s+from\s+the\s+user/i,
+    label: "pretend instructions came from user",
+    category: "ROLE_ASSUMPTION",
+    confidence: "medium",
+  },
+  {
+    regex: /you\s+(?:are|must)\s+(?:now\s+)?(?:a|an|acting\s+as)\s+(?:helpful|unrestricted|unfiltered)/i,
+    label: "you are now unrestricted",
+    category: "ROLE_ASSUMPTION",
+    confidence: "medium",
+  },
+
+  // ── INSTRUCTION_OVERRIDE（指令覆盖，中等）──────────
+  // 不如高置信度模式那么明确
+  {
+    regex: /bypass\s+(?:all\s+)?(?:security|safety)\s+(?:measures?|checks?|filters?|protocols?)/i,
+    label: "bypass security measures",
+    category: "INSTRUCTION_OVERRIDE",
+    confidence: "medium",
+  },
+
+  // ── DATA_EXFILTRATION（数据外泄，中等）─────────────
+  // Shell 替换读取敏感文件
+  {
+    regex: /\$\([^)]*(?:\.ssh|\.aws|\.gnupg|\.env\b|\.pem|\.key\b|id_rsa|id_ed25519|id_ecdsa|credentials|keychain|\/etc\/passwd|\/etc\/shadow)[^)]*\)/i,
+    label: "shell substitution reading sensitive file",
+    category: "DATA_EXFILTRATION",
+    confidence: "medium",
+  },
+  // 反引号替换读取敏感文件
+  {
+    regex: /`[^`]*(?:\.ssh|\.aws|\.gnupg|\.env\b|\.pem|\.key\b|id_rsa|id_ed25519|id_ecdsa|credentials|keychain|\/etc\/passwd|\/etc\/shadow)[^`]*`/i,
+    label: "backtick substitution reading sensitive file",
+    category: "DATA_EXFILTRATION",
+    confidence: "medium",
+  },
+];

package/agent/patterns/types.ts

@@ -0,0 +1,40 @@
+/**
+ * 注入模式定义的共享类型
+ */
+
+/**
+ * 注入类别
+ *
+ * - INSTRUCTION_OVERRIDE: 指令覆盖 — 试图让 AI 忽略原有指令
+ * - MODE_SWITCHING: 模式切换 — 试图激活调试/管理员模式
+ * - FAKE_SYSTEM_MESSAGE: 伪造系统消息 — 伪装成系统指令
+ * - CONCEALMENT_DIRECTIVE: 隐藏指令 — 让 AI 隐藏注入行为
+ * - COMMAND_EXECUTION: 命令执行 — 执行恶意 shell 命令
+ * - TASK_HIJACKING: 任务劫持 — 改变 AI 当前任务
+ * - ROLE_ASSUMPTION: 角色假设 — 让 AI 扮演不受限角色
+ * - DATA_EXFILTRATION: 数据外泄 — 窃取敏感数据
+ */
+export type InjectionCategory =
+  | "INSTRUCTION_OVERRIDE"
+  | "MODE_SWITCHING"
+  | "FAKE_SYSTEM_MESSAGE"
+  | "CONCEALMENT_DIRECTIVE"
+  | "COMMAND_EXECUTION"
+  | "TASK_HIJACKING"
+  | "ROLE_ASSUMPTION"
+  | "DATA_EXFILTRATION";
+
+/**
+ * 模式条目
+ *
+ * @property regex - 匹配的正则表达式
+ * @property label - 模式标签（用于日志和报告）
+ * @property category - 注入类别
+ * @property confidence - 置信度（high=单个匹配触发，medium=需多个类别）
+ */
+export type PatternEntry = {
+  regex: RegExp;
+  label: string;
+  category: InjectionCategory;
+  confidence: "high" | "medium";
+};

package/agent/runner.ts

@@ -0,0 +1,261 @@
+/**
+ * Agent Runner — 多后端分析器
+ *
+ * 支持两种检测后端：
+ *   1. Dashboard（首选）— 通过本地/远程 Dashboard 路由到 Core
+ *   2. OpenTrust API（备用）— 直接调用 Core API
+ *
+ * 内容在发送到任何 API 之前始终会在本地进行脱敏处理。
+ */
+
+import type {
+  AnalysisTarget,
+  AnalysisVerdict,
+  Finding,
+  Logger,
+  OpenTrustApiResponse,
+} from "./types.js";
+import { DEFAULT_CORE_URL, loadCoreCredentials, registerWithCore } from "./config.js";
+import { sanitizeContent } from "./sanitizer.js";
+
+/** Runner 配置 */
+export type RunnerConfig = {
+  /** API Key */
+  apiKey: string;
+  /** 请求超时时间（毫秒） */
+  timeoutMs: number;
+  /** 是否自动注册 */
+  autoRegister: boolean;
+  /** Core API 地址 */
+  coreUrl: string;
+  /** Dashboard API 地址（可选） */
+  dashboardUrl?: string;
+  /** Dashboard 认证 Token（可选） */
+  dashboardSessionToken?: string;
+};
+
+// ── Dashboard 检测 ───────────────────────────────────
+
+/** Dashboard 检测结果 */
+type DashboardDetectResult = {
+  success: boolean;
+  data?: {
+    safe: boolean;
+    verdict: string;
+    categories: string[];
+    sensitivity_score: number;
+    findings: Array<{ scanner: string; name: string; description: string }>;
+    latency_ms: number;
+    request_id: string;
+    policy_action?: string;
+  };
+  blocked?: boolean;
+  error?: string;
+};
+
+/**
+ * 通过 Dashboard 进行检测
+ *
+ * @param sanitizedContent - 已脱敏的内容
+ * @param config - Runner 配置
+ * @param _log - 日志器
+ * @returns 分析判定结果
+ */
+async function runViaDashboard(
+  sanitizedContent: string,
+  config: RunnerConfig,
+  _log: Logger,
+): Promise<AnalysisVerdict> {
+  // 超时控制
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeoutMs);
+
+  try {
+    // 构建请求头
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (config.dashboardSessionToken) headers["Authorization"] = `Bearer ${config.dashboardSessionToken}`;
+
+    // 发送检测请求
+    const response = await fetch(`${config.dashboardUrl}/api/detect`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ messages: [{ role: "user", content: sanitizedContent }] }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Dashboard API error: ${response.status} ${text}`);
+    }
+
+    const result = (await response.json()) as DashboardDetectResult;
+    if (!result.success || !result.data) throw new Error(`Dashboard error: ${result.error ?? "unknown"}`);
+
+    // 转换为统一格式
+    const data = result.data;
+    const findings: Finding[] = data.findings.map((f) => ({
+      suspiciousContent: f.name,
+      reason: f.description,
+      confidence: data.sensitivity_score,
+    }));
+
+    return {
+      isInjection: !data.safe,
+      confidence: data.sensitivity_score,
+      reason: data.safe ? "No issues detected" : `Detected: ${data.categories.join(", ")}`,
+      findings,
+      chunksAnalyzed: 1,
+    };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// ── Core API 检测（备用）────────────────────────────
+
+/**
+ * 确保有可用的 API Key
+ * 如果没有配置，尝试从本地加载或自动注册
+ *
+ * @param configKey - 配置的 API Key
+ * @param autoRegister - 是否允许自动注册
+ * @param coreUrl - Core API 地址
+ * @param log - 日志器
+ * @returns API Key
+ */
+async function ensureApiKey(
+  configKey: string,
+  autoRegister: boolean,
+  coreUrl: string,
+  log: Logger,
+): Promise<string> {
+  // 优先使用配置的 Key
+  if (configKey) return configKey;
+
+  // 尝试从本地加载
+  const savedKey = loadCoreCredentials()?.apiKey;
+  if (savedKey) return savedKey;
+
+  // 如果不允许自动注册，抛出错误
+  if (!autoRegister) {
+    throw new Error("No API key configured and autoRegister is disabled.");
+  }
+
+  // 自动注册
+  log.info("No API key found — registering with OpenTrust...");
+  try {
+    const result = await registerWithCore("openclaw-agent", "OpenClaw AI Agent", coreUrl);
+    log.info("Registered. API key saved to ~/.openclaw/credentials/opentrust-guard/credentials.json");
+    return result.credentials.apiKey;
+  } catch (error) {
+    throw new Error(
+      `Failed to auto-register: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+/**
+ * 将 API 响应映射为统一的判定结果
+ *
+ * @param apiResponse - API 响应
+ * @returns 分析判定结果
+ */
+export function mapApiResponseToVerdict(apiResponse: OpenTrustApiResponse): AnalysisVerdict {
+  const v = apiResponse.verdict;
+  return {
+    isInjection: v.isInjection,
+    confidence: v.confidence,
+    reason: v.reason,
+    findings: (v.findings ?? []).map((f) => ({
+      suspiciousContent: f.suspiciousContent,
+      reason: f.reason,
+      confidence: f.confidence,
+    })),
+    chunksAnalyzed: 1,
+  };
+}
+
+/**
+ * 通过 Core API 进行检测
+ *
+ * @param sanitizedContent - 已脱敏的内容
+ * @param config - Runner 配置
+ * @param log - 日志器
+ * @returns 分析判定结果
+ */
+async function runViaApi(
+  sanitizedContent: string,
+  config: RunnerConfig,
+  log: Logger,
+): Promise<AnalysisVerdict> {
+  const baseUrl = config.coreUrl || DEFAULT_CORE_URL;
+  const apiKey = await ensureApiKey(config.apiKey, config.autoRegister, baseUrl, log);
+
+  // 超时控制
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeoutMs);
+
+  try {
+    const response = await fetch(`${baseUrl}/api/check/tool-call`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({ content: sanitizedContent, async: false }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) throw new Error(`API error: ${response.status} ${response.statusText}`);
+
+    const apiResponse = (await response.json()) as OpenTrustApiResponse;
+    if (!apiResponse.ok) throw new Error(`API returned error: ${apiResponse.error ?? "unknown"}`);
+
+    return mapApiResponseToVerdict(apiResponse);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// ── 主分析函数 ───────────────────────────────────────
+
+/**
+ * 运行安全检测
+ * 主入口函数，根据配置选择后端进行分析
+ *
+ * @param target - 分析目标
+ * @param config - Runner 配置
+ * @param log - 日志器
+ * @returns 分析判定结果
+ */
+export async function runGuardAgent(
+  target: AnalysisTarget,
+  config: RunnerConfig,
+  log: Logger,
+): Promise<AnalysisVerdict> {
+  const startTime = Date.now();
+  log.info(`Analyzing content: ${target.content.length} chars`);
+
+  // 先进行本地脱敏
+  const { sanitized, redactions, totalRedactions } = sanitizeContent(target.content);
+  if (totalRedactions > 0) {
+    log.info(`Sanitized ${totalRedactions} items: ${Object.entries(redactions).map(([k, v]) => `${v} ${k}`).join(", ")}`);
+  }
+
+  try {
+    // 根据配置选择后端
+    const verdict = config.dashboardUrl
+      ? await runViaDashboard(sanitized, config, log)
+      : await runViaApi(sanitized, config, log);
+
+    log.info(`Analysis complete in ${Date.now() - startTime}ms: ${verdict.isInjection ? "INJECTION DETECTED" : "SAFE"}`);
+    return verdict;
+  } catch (error) {
+    // 超时处理：返回安全结果（失败开放）
+    if ((error as Error).name === "AbortError") {
+      log.warn("Analysis timed out");
+      return { isInjection: false, confidence: 0, reason: "Timeout", findings: [], chunksAnalyzed: 0 };
+    }
+    throw error;
+  }
+}

package/agent/sanitizer.ts

@@ -0,0 +1,153 @@
+/**
+ * 本地内容脱敏器 — 在发送到 API 前剥离 PII 和密钥
+ *
+ * 单向替换，使用类别占位符（如 <EMAIL>、<SECRET>）
+ *
+ * 支持的敏感信息类型：
+ * - URL: 网址
+ * - EMAIL: 邮箱地址
+ * - CREDIT_CARD: 信用卡号
+ * - SSN: 美国社会安全号
+ * - IBAN: 国际银行账户号
+ * - IP_ADDRESS: IP 地址
+ * - PHONE: 电话号码
+ * - SECRET: API 密钥、Token 等高熵字符串
+ */
+
+import type { SanitizeResult } from "./types.js";
+
+/** 实体定义：类别、占位符、匹配模式 */
+type Entity = { category: string; placeholder: string; pattern: RegExp };
+
+/** 预定义的敏感实体模式 */
+const ENTITIES: Entity[] = [
+  { category: "URL",         placeholder: "<URL>",         pattern: /https?:\/\/[^\s<>"{}|\\^`\[\]]+/g },
+  { category: "EMAIL",       placeholder: "<EMAIL>",       pattern: /[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}/g },
+  { category: "CREDIT_CARD", placeholder: "<CREDIT_CARD>", pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g },
+  { category: "SSN",         placeholder: "<SSN>",         pattern: /\b\d{3}-\d{2}-\d{4}\b/g },
+  { category: "IBAN",        placeholder: "<IBAN>",        pattern: /\b[A-Z]{2}\d{2}[A-Z0-9]{4}\d{7}[A-Z0-9]{0,16}\b/g },
+  { category: "IP_ADDRESS",  placeholder: "<IP_ADDRESS>",  pattern: /\b(?:[0-9]{1,3}\.){3}[0-9]{1,3}\b/g },
+  { category: "PHONE",       placeholder: "<PHONE>",       pattern: /[+]?[(]?[0-9]{3}[)]?[-\s.][0-9]{3}[-\s.][0-9]{4,6}\b/g },
+];
+
+/** 已知的密钥前缀（各种 API 提供商） */
+const SECRET_PREFIXES = ["sk-", "sk_", "pk_", "ghp_", "AKIA", "xox", "SG.", "hf_", "api-", "token-", "secret-"];
+
+/** Bearer Token 模式 */
+const BEARER_PATTERN = /Bearer\s+[A-Za-z0-9\-_.~+/]+=*/g;
+
+/** 已知前缀的密钥模式 */
+const SECRET_PREFIX_PATTERN = new RegExp(
+  `(?:${SECRET_PREFIXES.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})[A-Za-z0-9\\-_.~+/]{8,}=*`,
+  "g",
+);
+
+/**
+ * 计算香农熵
+ * 用于识别高熵字符串（可能是 API 密钥）
+ *
+ * @param s - 输入字符串
+ * @returns 熵值（越高越随机）
+ */
+function shannonEntropy(s: string): number {
+  if (s.length === 0) return 0;
+  const freq = new Map<string, number>();
+  for (const ch of s) freq.set(ch, (freq.get(ch) ?? 0) + 1);
+  let entropy = 0;
+  for (const count of freq.values()) {
+    const p = count / s.length;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+/** 匹配结果 */
+type Match = { text: string; category: string; placeholder: string };
+
+/**
+ * 收集所有敏感信息匹配
+ *
+ * @param content - 输入内容
+ * @returns 匹配列表
+ */
+function collectMatches(content: string): Match[] {
+  const matches: Match[] = [];
+
+  // 匹配预定义实体
+  for (const entity of ENTITIES) {
+    entity.pattern.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = entity.pattern.exec(content)) !== null) {
+      matches.push({ text: m[0], category: entity.category, placeholder: entity.placeholder });
+    }
+  }
+
+  // 匹配已知前缀的密钥
+  SECRET_PREFIX_PATTERN.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = SECRET_PREFIX_PATTERN.exec(content)) !== null) {
+    matches.push({ text: m[0], category: "SECRET", placeholder: "<SECRET>" });
+  }
+
+  // 匹配 Bearer Token
+  BEARER_PATTERN.lastIndex = 0;
+  while ((m = BEARER_PATTERN.exec(content)) !== null) {
+    matches.push({ text: m[0], category: "SECRET", placeholder: "<SECRET>" });
+  }
+
+  // 匹配高熵 Token（捕获没有已知前缀的 API 密钥）
+  const tokenPattern = /\b[A-Za-z0-9\-_.~+/]{20,}={0,3}\b/g;
+  tokenPattern.lastIndex = 0;
+  while ((m = tokenPattern.exec(content)) !== null) {
+    const token = m[0];
+    // 跳过已匹配的
+    if (matches.some((existing) => existing.text === token)) continue;
+    // 跳过纯小写字符串（可能是普通单词）
+    if (/^[a-z]+$/.test(token)) continue;
+    // 熵值 >= 4.0 认为是高熵字符串
+    if (shannonEntropy(token) >= 4.0) {
+      matches.push({ text: token, category: "SECRET", placeholder: "<SECRET>" });
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * 脱敏内容
+ * 将敏感信息替换为占位符
+ *
+ * @param content - 原始内容
+ * @returns 脱敏结果（脱敏后文本、各类别脱敏数量、总脱敏数量）
+ */
+export function sanitizeContent(content: string): SanitizeResult {
+  const matches = collectMatches(content);
+  if (matches.length === 0) {
+    return { sanitized: content, redactions: {}, totalRedactions: 0 };
+  }
+
+  // 去重
+  const unique = new Map<string, Match>();
+  for (const match of matches) {
+    if (!unique.has(match.text)) unique.set(match.text, match);
+  }
+
+  // 按长度降序排序，防止部分匹配
+  const sorted = [...unique.values()].sort((a, b) => b.text.length - a.text.length);
+
+  let sanitized = content;
+  const redactions: Record<string, number> = {};
+
+  // 逐个替换
+  for (const match of sorted) {
+    const parts = sanitized.split(match.text);
+    const count = parts.length - 1;
+    if (count > 0) {
+      sanitized = parts.join(match.placeholder);
+      redactions[match.category] = (redactions[match.category] ?? 0) + count;
+    }
+  }
+
+  const totalRedactions = Object.values(redactions).reduce((a, b) => a + b, 0);
+  return { sanitized, redactions, totalRedactions };
+}