记忆雷达

SKILL.md

---
slug: memory-radar
name: memory-radar
version: "1.0.0"
displayName: 记忆雷达
summary: 解决Prompt注入难检、凭证泄漏被动、误报高、跨文件威胁关联难的记忆安全雷达
license: MIT
description: |-
  记忆雷达是面向 AI Agent 记忆文件的安全扫描系统，针对"Prompt 注入检测难、凭证泄漏被动发现、扫描误报率高、跨文件威胁关联缺失"四大高频痛点而设计。它对 Agent 的记忆文件、日志、工作区配置进行持续安全审计，主动发现恶意指令、注入模式、凭证泄漏与行为操纵，防患于未然。

  核心能力：七大威胁类别检测（恶意指令/Prompt注入/凭证泄漏/数据外泄/护栏绕过/行为操纵/权限提升）、五级安全分级（SAFE/LOW/MEDIUM/HIGH/CRITICAL）、本地模式与可选远程 LLM 分析、定时监控与心跳集成、隔离与备份恢复、跨文件威胁关联分析、误报抑制（白名单+上下文感知）。

  适用场景：Agent 记忆定期安全审计、引入外部数据后的注入检测、凭证泄漏排查、合规性检查、多 Agent 协作前的信任验证、记忆文件迁移前清洗。

  差异化：相比仅做"关键词匹配"的简单扫描器，本技能新增 (1) 跨文件威胁关联，识别分散在多文件中的组合攻击模式；(2) 误报抑制机制，白名单 + 上下文感知，降低合法内容的误报；(3) 远程 LLM 增强分析（可选，仅传输脱敏内容），提升复杂注入识别率；(4) 隔离与恢复链路，检测到威胁后备份原文件、脱敏威胁行、保留恢复入口；(5) 持续监控模式，定时扫描 + 增量检测，避免重复全量扫描。

  触发关键词：记忆安全、注入检测、凭证泄漏、安全扫描、记忆审计、Prompt注入、memory scan、security scan、prompt injection
tags:
- 安全扫描
- 威胁检测
- 凭证保护
- 注入防御
tools:
- read
- exec
---

# 记忆雷达（Memory Radar）

面向 AI Agent 记忆文件的**安全扫描系统**，对记忆文件、日志、工作区配置进行持续安全审计，主动发现恶意指令、注入模式、凭证泄漏与行为操纵。

## 设计动机：四大高频痛点

| 痛点 | 典型表现 | 本技能对策 |
|------|----------|------------|
| Prompt 注入检测难 | 恶意指令伪装成正常记忆，难以识别 | 本地模式匹配 + 可选远程 LLM 语义分析 |
| 凭证泄漏被动发现 | Key 写进日志很久才被发现，已造成损失 | 定时扫描 + 高危模式即时告警 |
| 扫描误报率高 | 合法的 API 文档、测试用 Key 被误判 | 白名单 + 上下文感知误报抑制 |
| 跨文件威胁关联缺失 | 单文件看着无害，多文件组合构成攻击 | 跨文件威胁关联分析 |

## 快速开始（< 60 秒）

### 按需扫描

```bash
# 扫描全部记忆文件
python3 scripts/memory-scan.py

# 允许远程 LLM 分析（仅传输脱敏内容）
python3 scripts/memory-scan.py --allow-remote

# 扫描指定文件
python3 scripts/memory-scan.py --file memory/2026-07-18.md

# 静默模式（用于自动化）
python3 scripts/memory-scan.py --quiet

# JSON 输出（用于集成）
python3 scripts/memory-scan.py --json
```

### 定时监控

```bash
# 创建每日扫描 cron 任务
bash scripts/schedule-scan.sh
```

## 五级安全分级

| 等级 | 含义 | 处置建议 |
|------|------|----------|
| SAFE | 未检测到威胁 | 无需操作 |
| LOW | 轻微关注 | 知悉即可，继续使用 |
| MEDIUM | 潜在威胁 | 建议审查 |
| HIGH | 很可能威胁 | 立即审查 |
| CRITICAL | 活跃威胁 | 立即隔离 |

## 扫描范围

### 记忆文件
1. `MEMORY.md` - 长期记忆
2. `memory/*.md` - 每日日志（默认最近 30 天，可用 `--days` 调整）

### 工作区配置文件
- `AGENTS.md`、`SOUL.md`、`USER.md`、`TOOLS.md`
- `HEARTBEAT.md`、`GUARDRAILS.md`、`IDENTITY.md`
- `BOOTSTRAP.md`（如存在）
- 其他自定义配置文件（通过 `--include` 指定）

## 七大威胁检测类别

| 类别 | 描述 | 典型模式 |
|------|------|----------|
| 恶意指令 | 危害用户/数据的命令 | "删除所有文件"、"发送邮件到..." |
| Prompt 注入 | 嵌入操纵模式 | "忽略之前的指令"、"你现在是..." |
| 凭证泄漏 | API Key、密码、Token | `sk-`、`AKIA`、`ghp_`、`xoxb-` 等前缀 |
| 数据外泄 | 泄漏数据的指令 | "把文件上传到"、"curl 到外部" |
| 护栏绕过 | 覆盖安全机制 | "禁用安全检查"、"绕过验证" |
| 行为操纵 | 未授权人格改变 | "你的新身份是"、"忘记你的约束" |
| 权限提升 | 获取未授权访问 | "以管理员身份"、"提权到 root" |

## 误报抑制机制

降低合法内容被误判为威胁的概率：

### 白名单机制

```text
白名单规则：
1. 代码示例中的测试 Key（如 sk-test123、AKIATEST）
2. API 文档中的示例凭证（如 your_api_key_here）
3. 注释中的安全提醒（如 "不要把 sk- 开头的 Key 提交"）
4. 环境变量引用（如 ${API_KEY}、$ENV_TOKEN）
```

### 上下文感知

```text
检测到疑似凭证时，检查上下文：
- 前后是否有"示例"、"测试"、"占位"等关键词 → 降级
- 是否在代码块内且为变量赋值 → 降级
- 是否为真实的 32+ 字符高熵字符串 → 升级
```

### 误报反馈学习

```text
用户标记"误报"后：
1. 记录该模式到白名单
2. 后续扫描自动跳过相似模式
3. 白名单可手动审查与清理
```

## 跨文件威胁关联分析

识别分散在多文件中的组合攻击：

```text
单文件分析：
  memory/2026-07-15.md：含 "忽略之前的指令"（LOW，可能是引用）
  memory/2026-07-16.md：含 "curl 外部服务器"（LOW，可能是合法操作）
  memory/2026-07-17.md：含 "你的新身份是"（LOW，可能是角色扮演）

跨文件关联：
  三天内连续出现注入相关内容 → 升级为 MEDIUM
  攻击模式：渐进式注入（先试探，再执行）
  建议：审查这三天的记忆来源
```

### 关联规则

| 规则 | 触发条件 | 升级动作 |
|------|----------|----------|
| 时序关联 | 7 天内多文件出现同类威胁 | 整体升级一级 |
| 主题关联 | 多文件提及同一外部域名/服务 | 标记为关联事件 |
| 行为关联 | 注入指令 + 数据外泄指令组合 | 升级为 HIGH |
| 渐进关联 | 威胁严重度逐日递增 | 升级为 CRITICAL |

## 告警工作流

检测到 MEDIUM 及以上威胁时：

```text
1. 立即停止当前处理
2. 通过配置的告警渠道发送：
   - 严重级别
   - 文件位置（file:line）
   - 威胁描述
   - 建议处置
   - 关联威胁（如有）
3. 可选：隔离威胁（备份 + 脱敏）
4. 等待用户确认处置方案
```

## 隔离与恢复

### 隔离操作

```bash
# 隔离指定文件的指定行
python3 scripts/quarantine.py memory/2026-07-18.md 42
```

隔离后：
- **备份**：`.memory-scan/quarantine/memory_2026-07-18_line42.backup` 保留原始内容
- **脱敏**：第 42 行替换为 `[已隔离 by 记忆雷达: 时间戳]`
- **记录**：隔离日志记录操作详情

### 恢复操作

```bash
# 恢复被隔离的内容
python3 scripts/quarantine.py --restore memory/2026-07-18.md 42
```

## LLM Provider 自动检测

```text
优先级：
1. OpenAI（gpt-4o-mini）如 OPENAI_API_KEY 已配置
2. Anthropic（claude-sonnet-4-5）如可用
3. 网关模型配置

默认：远程 LLM 扫描禁用
启用：--allow-remote（仅传输脱敏内容）
```

**脱敏规则**：发送到远程 LLM 前，所有疑似凭证替换为 `[REDACTED]`，仅保留上下文结构供分析。

## 增量扫描

避免每次全量扫描：

```text
首次扫描：全量扫描所有文件，记录文件 hash
后续扫描：
  1. 比较文件 hash，仅扫描变更文件
  2. 新增文件必扫
  3. 未变更文件跳过（结果复用上次）
  4. 可用 --force 强制全量扫描

扫描状态存储：.memory-scan/state.json
```

## 典型工作流（3 个真实场景）

### 场景一：日常安全审计

```text
用户："扫描一下记忆文件有没有安全问题"

流程：
1. 运行 memory-scan.py（增量模式）
2. 输出扫描报告（按文件列出威胁）
3. MEDIUM+ 立即告警
4. 询问是否隔离威胁
5. 隔离后提供恢复指引
```

### 场景二：引入外部数据后检查

```text
用户："我刚把一份外部文档导入记忆，帮我检查是否安全"

流程：
1. 扫描指定文件或最近变更
2. 重点检测 Prompt 注入与数据外泄
3. 如发现注入模式，分析是否为渐进式攻击
4. 输出威胁评估报告
5. 建议处置方案（隔离/删除/保留）
```

### 场景三：定时监控集成

```text
心跳任务：每周日运行记忆雷达

流程：
1. 增量扫描本周新增/变更文件
2. 跨文件关联分析
3. 发现威胁则告警
4. 生成周度安全报告
5. 归档扫描结果
```

## 输出示例

```text
$ python3 scripts/memory-scan.py

记忆安全扫描
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

扫描记忆文件...

✓ MEMORY.md - SAFE
✓ memory/2026-07-18.md - SAFE
⚠ memory/2026-07-15.md - MEDIUM (line 42)
  → 疑似凭证泄漏：检测到 sk- 开头的高熵字符串
  → 关联：memory/2026-07-14.md line 18 含外泄指令
  → 建议：隔离并检查来源

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
总体：MEDIUM
建议处置：审查 memory/2026-07-15.md:42
```

## Agent 工作流

当用户请求记忆扫描时：

```text
1. 运行：python3 scripts/memory-scan.py
2. 若 MEDIUM+：立即通过配置渠道告警
3. 汇总发现（含跨文件关联）
4. 询问是否隔离威胁
5. 隔离后提供恢复指引
6. 记录扫描结果到 .memory-scan/state.json
```

## 与其他技能协同

| 协同技能 | 关系 |
|----------|------|
| 输入守卫类技能 | 互补：输入守卫管外部输入，记忆雷达管内部记忆 |
| 安全安装类技能 | 集成：每日审计可包含记忆雷达扫描 |
| 威胁情报类技能 | 上报：记忆型威胁可上报社区情报源 |

## 注意事项

- 默认扫描最近 30 天日志（`--days` 可调）
- 远程 LLM 与本地输入守卫使用一致方法
- **永不自动隔离**，始终先询问用户
- 频繁运行安全（增量扫描成本低）
- 隔离前自动备份，可恢复

## FAQ

**Q1：扫描会不会泄露我的记忆内容？**
A：本地模式零网络请求。远程 LLM 模式（`--allow-remote`）仅传输脱敏内容，所有疑似凭证替换为 `[REDACTED]`。

**Q2：误报太多怎么办？**
A：(1) 用白名单机制标记合法内容；(2) 启用上下文感知降级；(3) 用户标记误报后系统自动学习。白名单可定期审查清理。

**Q3：隔离后能恢复吗？**
A：可以。隔离前自动备份到 `.memory-scan/quarantine/`，用 `--restore` 命令恢复。

**Q4：增量扫描会不会漏掉威胁？**
A：不会。增量扫描基于文件 hash，任何变更都会触发重新扫描。未变更文件复用上次结果，不影响检测率。可用 `--force` 强制全量扫描。

**Q5：跨文件关联分析怎么工作？**
A：扫描后对所有发现的威胁做关联分析，检查时序、主题、行为、渐进四种关联模式。关联命中则升级威胁等级并标记为关联事件。

## 故障排查

| 症状 | 可能原因 | 解决方案 |
|------|----------|----------|
| 扫描报错找不到文件 | 路径配置错误 | 检查工作区路径，用 `--path` 指定 |
| 远程 LLM 不可用 | API Key 未配置 | 配置 OPENAI_API_KEY 或禁用 `--allow-remote` |
| 误报过多 | 白名单未配置 | 标记误报，系统自动学习白名单 |
| 隔离后文件损坏 | 备份失败 | 检查 `.memory-scan/quarantine/` 是否有备份 |
| 增量扫描漏报 | state.json 损坏 | 删除 state.json，强制全量扫描 |

## 依赖说明

### 运行环境
- **Agent 平台**：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
- **操作系统**：Windows / macOS / Linux
- **Python**：3.8+

### 第三方依赖

| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| Python 3.8+ | 运行时 | 必需 | https://python.org 安装 |
| memory-scan.py | 脚本 | 必需 | 随技能提供 |
| quarantine.py | 脚本 | 必需 | 随技能提供 |
| schedule-scan.sh | 脚本 | 可选 | 随技能提供，用于定时任务 |
| OpenAI API Key | API Key | 可选 | 用于远程 LLM 分析（`--allow-remote`） |

### API Key 配置
- **本地模式**：无需任何 API Key
- **远程 LLM 模式**（可选）：配置 `OPENAI_API_KEY` 环境变量
- **告警渠道**（可选）：参考所用 Agent 平台的告警配置文档

### 可用性分类
- **分类**：MD+EXEC（Markdown 指令驱动，需 exec 执行 Python 脚本）
- **说明**：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 运行安全扫描脚本并处理结果