Ishannaik/agent-sweep

## 问题所在 Claude Code（以及所有其他 AI 编码 CLI）会将您的完整对话记录以纯文本 JSONL 的形式存储在磁盘上 — Claude Code 位于 `~/.claude/projects/` 下，OpenAI Codex 位于 `~/.codex/sessions/` 下。您粘贴的任何内容 — AWS 密钥、`.env` 文件、数据库 URL — 都会无限期地以明文形式存在。一个典型的开发者的历史记录在几个月内会积累数十个机密信息，而他们往往自己都没意识到。 `agentsweep` 会扫描这些历史记录，告诉您哪些信息泄露了，并且可以在保持 JSONL 结构逐字节不变的前提下，原地脱敏机密值。它还会告诉您哪些密钥需要轮换，并为每个提供商提供正确的撤销 URL。 ## 为什么现在这很重要 供应链攻击正在加速。在 2024–2025 年，一波恶意的 npm 和 PyPI 包 — `sha256-universal`、`shailulid`、数以百计的拼写抢注包 — 被发现都在做同一件事：**从安装它们的机器上窃取开发者凭证**。它们的目标是环境变量、`.env` 文件、shell 历史记录、SSH 密钥，以及现在的 AI agent 历史文件。 AI 编码助手创造了一种在两年前还不存在的全新凭证暴露类别： - 您将一个生产环境的 API key 粘贴到 Claude Code 中进行调试 → 它现在会永远留在 `~/.claude/projects/*/conversations/*.jsonl` 中 - 一个被篡改的 npm 包运行 `postinstall` → 扫描常见路径 → 找到您的 JSONL 历史记录 → 通过一次请求窃取 50 个 API key - 您轮换了在公开场合使用过的密钥，却忘记了历史记录中的其他十几个密钥 - 与此同时，您的历史记录在不断增长：您让 AI 帮忙处理的每一个 `.env`，您为调试而分享的每个数据库 URL，您为了一次性使用而粘贴的每个 token **AI agent 历史记录就是新的 `.bash_history` — 不同的是它包含了完整上下文，而不仅仅是命令。** 攻击工具已经知道了这一点。`agentsweep` 的存在就是为了在被利用之前进行清理。 ## 快速开始 ``` pip install uv # get uv (skip if you already have it) uv tool install agentsweep # install — adds `agentsweep` and `asweep` to PATH asweep # run — interactive menu guides you through everything ``` 就这么简单。无需激活 virtualenv，无需调整 PATH — `uv tool install` 会为该命令提供自己独立的环境。 ## 工作原理 agentsweep 运行固定的 5 阶段 pipeline。`scan` 在第 3 阶段后停止；`fix` 则继续执行脱敏。 ``` flowchart LR A("🔍 DISCOVER\nwalk history dirs\nstream file list") --> B("⚡ SCAN\nAho-Corasick pre-filter\n191 regex rules + BIP-39") B --> C{"secrets\nfound?"} C -- "none" --> D("✅ CLEAN\nexit 0") C -- "found" --> E("📋 FINDINGS\nshow report\nexit 1") E -. "scan only" .-> F("⚠️ ROTATE\nkeys still live") E -- "type REDACT" --> G("✏️ REDACT\natomic write · .bak backup\npost-write JSON validation") G --> H("🔑 ROTATE\nper-provider\nrevocation links") style A fill:#1e3a5f,color:#fff,stroke:#2d5986 style B fill:#1e3a5f,color:#fff,stroke:#2d5986 style C fill:#4a3728,color:#fff,stroke:#7a5c3f style D fill:#1a4731,color:#fff,stroke:#2d7a52 style E fill:#4a3a1e,color:#fff,stroke:#7a6030 style F fill:#4a2020,color:#fff,stroke:#8b3a3a style G fill:#1e3a5f,color:#fff,stroke:#2d5986 style H fill:#2d1e4a,color:#fff,stroke:#5a3a8b ``` 每一次写入都受到 8 项安全原则的保护 — 原子替换、强制的 `.bak` 备份、符号链接拒绝、mtime/进程限制，以及写入后的 JSONL 验证。`agentsweep undo` 会从备份中恢复。 ## 安装 **推荐 — 独立环境，无 venv 冲突：** ``` uv tool install agentsweep # one-time install uv tool upgrade agentsweep # update to latest ``` **免安装尝试（始终运行最新版本）：** ``` uvx agentsweep@latest ``` **经典 pip：** ``` pip install agentsweep pip install --upgrade agentsweep ``` ## 使用方法 ### 交互模式 在终端中不带参数运行，您将获得完整的体验 — 横幅、 带编号的菜单、在执行任何破坏性操作前要求输入确认，以及 一键撤销（恢复 `.bak` 备份）。任何发现机密信息的交互式扫描 最后都会提示您是否原地脱敏它们（输入 `REDACT` 以确认）： ``` agentsweep ``` 脚本执行不受影响：任何 flag，或者通过管道/重定向的流， 都会完全跳过菜单，并严格按照下文的文档说明运行。 ### 动词 | 命令 | 功能说明 | |---|---| | `agentsweep scan` | 仅扫描 — 只读，不修改任何文件（未指定动词时的默认行为） | | `agentsweep fix` | 扫描，然后提示是否原地脱敏发现的机密（输入 `REDACT` 以确认） | | `agentsweep undo` | 恢复所有 `.bak` 备份，撤销之前所有的脱敏操作 | | `agentsweep purge` | 在轮换泄露的密钥后删除所有 `.bak` 备份（永久操作 — `undo` 将失效） | | `agentsweep --version` / `-V` | 打印已安装的版本号 | | `agentsweep --update` | 检查 PyPI 上是否有更新的版本 | 传统的 flag 形式 `agentsweep --fix` 仍然被接受，其行为与 `agentsweep fix` 完全相同。 ### 源选择 使用 `--source` 选择要定位其历史记录的 agent。默认为 `claude-code`。 ``` agentsweep scan --source claude-code # ~/.claude/projects/ (default) agentsweep scan --source codex # ~/.codex/sessions/ agentsweep scan --source opencode # OpenCode SQLite store agentsweep scan --source cursor # Cursor history agentsweep scan --source windsurf # Windsurf history agentsweep scan --source aider # ~/.aider/ agentsweep scan --source cline # Cline history agentsweep scan --source gemini-cli # Gemini CLI history agentsweep scan --source continue-vscode # Continue (VS Code) history agentsweep scan --source github-copilot-chat # GitHub Copilot Chat history agentsweep scan --source openclaw # OpenClaw ~/.openclaw/ agentsweep scan --source hermes # Hermes Agent ~/.hermes/state.db agentsweep scan --source goose # Goose ~/.local/share/goose/ ``` 覆盖默认的根目录以扫描任意文件夹： ``` agentsweep scan --root ~/backups/claude-history agentsweep fix --root /tmp/history-copy --allow-production ``` ### 扫描 / 修复 flag ``` # 输出 Machine-readable JSON 到 stdout（exit 0 = 干净，1 = 发现结果，2 = 错误） agentsweep scan --json # 将 findings JSON 写入文件而不是 stdout agentsweep scan --json -o findings.json agentsweep scan --json --output /tmp/report.json # 跳过 .agentsweepignore 文件 agentsweep scan --no-ignore ``` ### 仅修复 flag ``` # 就地 Redact Claude Code 历史（alpha 阶段默认 roots 需要 --allow-production） agentsweep fix --allow-production # 跳过创建 .bak 备份（不推荐） agentsweep fix --allow-production --no-backup # 绕过软安全检查：mtime gate（修改时间 <60 秒前的文件）和 running-process gate agentsweep fix --allow-production --force # 组合：针对自定义 root 的非交互式 JSON-mode redaction agentsweep fix --root ~/history-copy --json ``` ### 撤销 flag ``` # 针对特定 source 撤销 redactions agentsweep undo --source codex # 针对自定义 root 撤销 agentsweep undo --root ~/history-copy ``` ## 防损坏保证 一个会损坏您历史记录的脱敏工具，绝对比它正在修复的泄密更糟糕。agentsweep 在每次执行 `--fix` 时都会强制执行以下原则： 1. **脱敏在解析后的 JSON 中进行，而不是在原始字节上。** 机密信息在解析后的结构中作为字符串*值*被替换，然后重新序列化。从构造上就杜绝了结构性损坏的可能。 2. **原子写入。** 每次重写的过程是：临时文件 → `fsync()` → 通过 `os.replace()` 覆盖原文件。在任何时刻发生崩溃，留下的都会是完整的旧文件或完整的新文件 — 绝不会出现写穿（torn write）的情况。 3. **写入后验证。** 在提交之前，新内容必须通过格式感知检查：JSONL — 每一个非空行都能解析为 JSON，并且行数与原始文件匹配；整文件 JSON — 文档能够解析；markdown/纯文本 — 行数与原始文件匹配；SQLite — 重写的副本通过 `PRAGMA integrity_check`。如果检查失败，则中止写入，且原文件保持不变。 4. **默认创建 `.bak` 备份。** 创建时仅限所有者可读（模式 `0600`），因为其中包含脱敏前的机密；如果 `.bak` 已经存在，则拒绝运行（从而防止之前的备份被覆盖）。 5. **路径限制。** 拒绝任何无法解析到源的历史记录树（例如 Windsurf 的 User 目录及其 `~/.codeium/windsurf/memories/`）内部的目标。 6. **拒绝符号链接。** 直接拒绝处理符号链接。 7. **mtime 时间窗口。** 拒绝处理在过去 60 秒内被修改过的文件（可能是活动会话）。可通过 `--force` 覆盖。 8. **运行进程检查。** 如果检测到 Claude Code 进程正在运行，则拒绝执行。可通过 `--force` 覆盖。 9. **Alpha 阶段生产环境门控。** 在 v1.0 版本之前，针对默认的 `~/.claude/projects/` 根目录执行 `--fix` 需要使用 `--allow-production`。 10. **审计日志。** 每次写入都会将操作前后的 SHA256 和文件路径追加到 `~/.agentsweep/audit.jsonl` 中。 ## 恢复 每个脱敏后的文件都有一个包含原始字节的同级 `*.bak` 文件。撤销某个源的所有脱敏操作的最简单方法是： ``` agentsweep undo # undo Claude Code (default) agentsweep undo --source codex # undo a specific source agentsweep undo --root ~/history-copy # undo against a custom root ``` 如果您需要手动恢复单个文件（例如，您删除了撤销命令的源）： ``` mv session.jsonl.bak session.jsonl ``` 备份中保存了**脱敏前的原始内容 — 即明文机密信息**，因此只要泄露的密钥还没有被轮换、备份还没有被删除，清理工作就不算完成。一旦您完成了轮换： ``` agentsweep purge # delete Claude Code backups (asks first) agentsweep purge --source windsurf # delete a specific source's backups agentsweep purge --yes # non-interactive (scripts / CI) ``` ## 检测范围 191 种高置信度模式 **加上经过校验和验证的加密助记词检测器** — BIP-39 助记词（12/15/18/21/24 个单词；BTC、ETH、SOL、BNB、ADA、DOGE、LTC、DOT、AVAX 以及几乎所有主流链背后的钱包格式）和 Electrum 助记词都经过了加密学验证（BIP-39 校验和 / Electrum 版本标签），因此恰巧使用了钱包词汇的普通英文文本绝不会发生误报（假阳性）。 这些模式包括：AWS 访问密钥、GitHub token（PAT/OAuth/App/fine-grained）、Stripe live/test、OpenAI、Anthropic、Google API、Slack bot/user/webhook、Hugging Face、JWT、PEM 私钥、内嵌密码的数据库 URL、npm/PyPI/SendGrid/Twilio token — 另外还有 167 条从 [gitleaks](https://github.com/gitleaks/gitleaks) 规则包移植过来的规则，涵盖了 GitLab、Grafana、HashiCorp Vault/Terraform、DigitalOcean、Shopify、PlanetScale、Databricks、Atlassian、Azure AD、1Password、Sentry、New Relic、Mailgun、Datadog、Twilio、Twitter/X、Twitch、Yandex、JFrog、Snyk、Mailchimp、命令行中的 curl 凭证等等。模式精度很高 — 误报极为罕见，并且提供商上下文规则受关键字控制，因此即使是大量粘贴的内容也能保持处理速度。 ## 不检测的内容 - 没有可识别前缀的自定义/专有机密信息。 - Monero 助记词（来自 Monero 自定义词表的 25 个单词 — 已在计划中）。 - 看起来像任意 base64 的未知 token。 - 分散在多条消息中的机密信息。 - 二进制/非 UTF-8 文件中的任何内容。 如需更深度的检测，可将 `gitleaks` 或 `trufflehog` 与 agentsweep 结合使用 — 它们的规则包更加全面。agentsweep 的价值在于其针对 **agent 历史记录的独特覆盖面**，而不是检测引擎本身。 ## 常见问题解答 **为什么 `uvx agentsweep` 显示的是旧版本？** uvx 会在本地缓存工具。请使用 `uvx agentsweep@latest` 以始终运行最新版本（推荐），或者使用 `uvx --reinstall agentsweep` 强制刷新缓存。 **菜单里有 OpenCode 吗？** OpenCode 的支持是在 v0.1.1 版本中加入的。运行 `pip install --upgrade agentsweep` 或 `uvx agentsweep@latest` 即可获取。 **agentsweep 会把我的数据发送到其他地方吗？** 不会。它是完全离线的 — 在扫描或脱敏过程中没有任何网络调用。唯一可选的网络调用是后台更新检查，它仅从 PyPI 获取最新的版本号。 ## 贡献者 感谢所有贡献了代码、提交了 Bug 报告和提供了想法的人。 [](https://github.com/Ishannaik/agent-sweep/graphs/contributors) ## 许可证 MIT。详见 LICENSE。

标签：AI编程助手, Python, StruQ, 安全助手, 数据脱敏, 无后门, 时序数据库, 网络安全, 逆向工具, 隐私保护