MaxHu-xuan/chat-archive-guard

什么是 ChatArchiveGuard？

ChatArchiveGuard 是一个小型纯 Python 命令行工具，用于审计包含导出的聊天记录的本地目录（或单个文件）。它在不修改文件或向任何地方发送数据的情况下扫描文件，并报告：

1. 潜在的秘密或个人数据模式 – 例如：API 密钥、Bearer 令牌、电子邮件地址、电话号码、类似信用卡的号码。
2. 格式问题 – 格式错误的 UTF-8、损坏的 JSON/JSONL 文件。
3. SQLite 健康检查 – 在数据库的私有副本（包括 WAL/SHM 辅助文件）上运行 SQLite 的 PRAGMA quick_check(1)，并查找普通表和 FTS 表中的可读文本。
4. 覆盖缺口 – 告知您每个可以检查的文件是否确实被扫描，或者扫描是否因权限问题、资源限制或不支持的文件类型而被截断。

该工具旨在作为交付前检查：在将聊天导出交给分析师、备份管道或第三方服务之前，您可以运行快速本地审计，以捕获意外的凭据泄漏或损坏的文件。

---

主要功能（如 README 中所述）

功能	工作原理	输出中您会看到的内容
秘密和 PII 检测	基于正则表达式的模式，用于私钥、提供商令牌、JWT、电子邮件地址、类似电话号码、IP、身份证号码、Luhn 验证的卡号等。	类别计数，如 secret.provider_key 或 pii.email（不显示实际值）。
格式验证	检查 UTF-8 有效性并解析 JSON/JSONL 文件。	类别如 format.invalid_json 或 format.invalid_jsonl。
SQLite 完整性	将主数据库以及任何 WAL/SHM 文件复制到私有临时目录，打开副本，运行 PRAGMA quick_check(1)，并扫描文本列（包括 FTS 虚拟表）。	sqlite.* 下的类别（例如 sqlite.quick_check_failed）。
目录覆盖报告	跟踪 files_seen（遇到的所有文件）与 files_scanned（进入内容检查的文件），并在限制或错误阻止完整覆盖时标记 complete/truncated。	JSON/文本报告中的布尔标志和数字计数器。
仅摘要模式	--summary-only 删除文件路径和单个发现的详细信息，仅保留聚合计数 – 适用于不想暴露文件名或数据的 CI 管道。	相同的退出代码，但 details_omitted/findings_omitted 设置为 true。
硬资源限制	文件大小、文件数量、SQLite 行数、值大小和总发现数的上限，以保持扫描可预测。	达到限制时添加特殊发现，truncated 变为 true。
跨平台安全	仅使用 Python 标准库；在无法安全打开 SQLite 而不遵循符号链接的平台上（Windows），工具会中止该文件并将其标记为不安全，而不是冒数据泄漏的风险。	Windows 上的 sqlite.sidecar_unsafe 类别。

---

谁可能使用它？

• 数据工程师或 ML 运维团队 – 接收聊天导出转储（例如来自 Slack、Teams、Discord），需要确保没有秘密意外发送到下游管道。
• 安全审计员 – 在归档或共享之前执行离线隐私检查。
• CI/CD 管道 – 如果聊天导出包含任何标记的秘密或格式错误的文件，自动拒绝构建。
• 个人开发者 – 希望在将聊天存档提交到版本控制之前进行快速离线健全性检查。

---

如何开始

1. 安装（需要 Python 3.11+）：

   python3 -m venv .venv && . .venv/bin/activate
   python -m pip install chat-archive-guard
   

2. 在目录上运行扫描：

   chat-archive-guard /path/to/export          # 人类可读的文本报告
   chat-archive-guard /path/to/export --json   # JSON 报告
   chat-archive-guard /path/to/export --json --summary-only   # CI 友好的仅聚合
   

3. 解释退出代码：
   • 0 – 没有发现，扫描覆盖了所有内容。
   • 1 – 至少有一个发现或覆盖不完整。
   • 2 – 无效的路径/参数。

---

限制和它不做什么

• 它不验证聊天消息是否完整、真实或未被篡改。
• 它不读取压缩存档、加密文件、图像、音频或专有二进制格式。
• 它不充当完整的 DLP 或取证工具；发现基于模式，可能包含误报/漏报。
• 它不上传数据；唯一的网络活动是可选的包安装。

---

在哪里找到更多信息

• 源代码和问题跟踪器：https://github.com/MaxHu-xuan/chat-archive-guard
• 许可证：Apache 2.0（参见 LICENSE）
• 详细威胁模型：THREAT_MODEL.md
• 发布说明和变更日志：RELEASE_NOTES.md、CHANGELOG.md

---

摘要

ChatArchiveGuard 是一个轻量级的离线 Python 工具，可安全扫描聊天导出文件中的秘密、个人数据、格式错误的 JSON/UTF-8 和 SQLite 完整性问题，提供清晰的聚合报告和 CI 兼容的退出代码。对于任何需要在共享或处理聊天日志之前进行快速隐私优先检查的人来说，它都很有用。