interplains/Zero-Breach-Toolkit · 上手攻略

  • 仓库：interplains/Zero-Breach-Toolkit
  • 链接：https://github.com/interplains/Zero-Breach-Toolkit
  • 分类：security / forensic-investigation / 反监控工具
  • 作者：spark
  • 更新：2026-10-28

版本锚点：最新 release v0.1.7（发布于 2026-10-28，target commit 951efefe5310272d476103cadd6e43a75417eb0b）。下文命令与流程均按该 tag 核对；若仓库后续更新，子命令与指标数量可能变动。

一、是什么

Zero-Breach-Toolkit 是一个纯本地、只读的开源取证扫描器，用来在一台电脑、一部 Android 手机或一份 iPhone 备份里，寻找已知雇佣间谍软件（mercenary spyware）留下的痕迹。它覆盖的具体家族包括 Pegasus（以色列 NSO Group）、Predator（Predator Group）、Graphite（Paragon）、Candiru（Also Known As / NSO 的 iOS 间谍工具）等。

设计目标只有三个，写在 README 顶部：只读（不改被检查的证据文件与系统设置）；扫描期间零网络请求（Python 网络调用被阻断，无上传功能；README 说明这不是 OS 级网络沙箱，详见 PRIVACY.md）；主动声明边界（报告说清发现了什么、证据强度多大、哪些没检查到，"干净"永不表述为"你是安全的"）。

底层引擎是同组织的 Zero Breach，本仓库是它的 CLI 包装与分发层。结构上是单文件 Python 工具：scan/zero-breach-toolkit.py 是主入口，build/bundle.py 打包成单文件，build/emit_stix.py / emit_misp.py / emit_denylist.py 把指标导出成 STIX / MISP / hosts 格式。指标在 iocs/，其中 iocs/curated_mercenary.txt 是手工整理的离线子集。

二、解决什么问题

雇佣间谍软件的特点是静默、合法购买、可控：设备本身往往看不出异常，浏览器历史被删、通知被关、应用权限被悄悄提权。传统杀毒查不出"合法签名 + 未触发特征库"的工具，专有取证产品则要么收费、要么需要联网。

定位是普通人的自助初筛 + 志愿者的批量排查：记者、活动人士、人权捍卫者自查设备；安全团队收到可疑设备时做标准化初筛；事件响应需要一个能离线跑、源码可审计、结果可解释的入口工具。

它明确不是端到端取证产品：不 dump 内存、不做全盘雕刻、不重建时间线，只回答"这里有没有已公开的已知家族特征痕迹"。边界写得很直白：Prefetch 命中（execution-record）不标识文件内容或完整路径；Amcache 命中（inventory-record）不证明执行过或文件仍存在；锁定的或不支持的记录一律计入 gap（缺口）。

三、快速安装

前置条件：Python 3.8+，无需管理员权限，无需第三方包。Windows 安装时务必勾 "Add python.exe to PATH"。

方式 A：源码运行（推荐，可审计）

git clone https://github.com/interplains/Zero-Breach-Toolkit.git
cd Zero-Breach-Toolkit

务必在仓库根目录下执行后续所有命令：

python -X utf8 scan/zero-breach-toolkit.py --update   # 唯一联网的一步，建议每次都做
python -X utf8 scan/zero-breach-toolkit.py             # 跑本机标准检查

macOS / Linux 上用 python3；也可直接 sh scan/run-scan.sh（参数一致）。Windows 可双击 scan\run-scan.cmd。

方式 B：发布版单文件

从 Releases 下载 zero-breach-toolkit.py 直接跑。但 README 建议走源码路线——它"每一行执行的代码都在 clone 里，不编译也不联网拉取"。

底层是单文件 Python 工具，也是本项目最值得学习的设计：README 给出可复现的确定性构建校验。

git checkout v0.1.7
python build/bundle.py
python -c "import hashlib; print(hashlib.sha256(open('dist/zero-breach-toolkit.py','rb').read()).hexdigest())"

v0.1.7 基准值：大小 959,996 字节，SHA-256 为 1fd1c8cf194f24a295005beb96836dd3bdec522134870c8b83f4b834b83c0cfd。

构建确定性，重建一致即说明发布文件确实含那份源码且无夹带。每个 release 附 SHA256SUMS.txt、SHA256SUMS.txt.asc（GPG 签名）和公钥 archivegenocide-signing-key.asc，详见 docs/VERIFYING.md。

注意：项目匿名运营，不提供签名的 Windows 程序，也不会有——代码签名证书需要实名法律主体。

macOS 必做的一步

跑检查前给 Terminal 授"完全磁盘访问权限"：系统设置 → 隐私与安全性 → 完全磁盘访问权限 → 添加 → 应用程序 → 实用工具 → Terminal，打开开关。不给这个权限，macOS 会隐藏 Safari 的记录和部分目录，报告里列为"未检查"。

四、核心用法

桌面：标准检查

python -X utf8 scan/zero-breach-toolkit.py

打开交互菜单，先选"更新指标列表"，再回到菜单按 Enter 开始本机标准检查。README 说这一步约需 15 分钟。结果存在工具目录的 findings 文件夹（可读报告 + JSON）。

常用选项

python -X utf8 scan/zero-breach-toolkit.py --quick                 # 快速模式：跳过文件指纹
python -X utf8 scan/zero-breach-toolkit.py --phone "FOLDER"        # 手机采集包或 iPhone 备份目录
python -X utf8 scan/zero-breach-toolkit.py --json report.json      # 机器可读报告
python -X utf8 scan/zero-breach-toolkit.py --share-json summary.json  # 最小摘要，便于分享

Android 手机

工具从不直接与手机对话——它读取 AndroidQF 生成的采集包。

手机上：设置 → 关于手机 → 连点 "Build number" 七次开启开发者模式 → 设置 → 开发者选项 → 打开 "USB 调试" → 数据线连电脑并解锁，弹出 "Allow USB debugging?" 时勾 "Always allow"。

电脑上：启动工具 → "A phone" → 选 2（Collect from an Android phone connected by USB now）→ 保存到桌面并输入 YES。采集器问卷照 README 表格答：

它问 选
Backup Only SMS
Download copies of apps Only non-system packages
Remove copies of apps signed with a trusted certificate No
Intrusion Logs No
Hash files No
其他 No

手机弹出 "Back up my data" 时点它（密码留空），全程保持解锁。采集完成后工具自动开始检查。用完把 USB 调试关掉。

检查范围：应用指纹与签名证书、安装历史（已装后被删的仍会显示）、系统记录与崩溃记录、已解密支持的入侵日志（DNS 查询、TCP 连接尝试、进程启动事件——连接尝试不证明成功）、SMS/MMS 中的链接、非应用商店应用及其权限画像、设备改装迹象（解锁 bootloader、debug build、安全保护关闭）。工具能识别采集包自身痕迹（USB 调试、调试 shell 权限），不会误报为可疑。

iPhone

  1. 先在电脑上备份：Windows 用 Microsoft Store 的 "Apple Devices"，macOS 用 Finder，选中 iPhone，勾 Encrypt local backup，设一个你记得住的密码，点 "Back Up Now"。
  2. 打开备份目录：Windows 按 Win+R 粘贴 %USERPROFILE%\Apple\MobileSync\Backup；macOS Finder → 前往 → 前往文件夹 → ~/Library/Application Support/MobileSync/Backup。里面长字母数字命名的文件夹就是备份。
  3. 工具菜单 → "A phone" → 选 1 → 把那个长名字文件夹拖进窗口 → Enter。
  4. 问是否密码保护时输入 y，再输入备份密码（不回显）。

还支持已提取的文件系统与 sysdiagnose 归档。

结果怎么读

  • "No known indicators found"：工具能检查到的位置里没有已公布指标中的东西。这不是设备干净的证明——去读报告里的"未能检查的位置"清单。
  • "Something matched"：意思是要进一步看，不是"你被黑了"。不要删除任何东西，不要访问报告里点名的地址。 保留报告并联系 Access Now Digital Security Helpline（免费、24/7、多语言）或 Amnesty Security Lab。

五、典型适用场景

  • 记者/活动人士的设备自查：拿到威胁警告后先跑一次标准检查。
  • NGO / 公民社会的批量排查：为高风险同事的设备建立标准化初筛流程，--json 输出便于归档。
  • 事件响应的第一道工序：把"可能有间谍软件"收敛成"命中/未命中 + 明确 gap 清单"，再决定是否升级专业取证。
  • 安全研究与指标分发：build/emit_stix.py / emit_misp.py / emit_denylist.py 可导出 STIX 2.1、MISP 或 hosts/dnsmasq 格式，接入自己的检测管道。
  • 离线/断网环境的排查：得益于"扫描期间零网络请求"，气隙环境或取证实验室里也能用。

指标规模：约 12,400 条已公布指标，来自 29 个来源，包括 Amnesty International Security Lab、Mobile Verification Toolkit 项目、Citizen Lab 与 Echap 的 stalkerware 研究，以及从 Citizen Lab 报告手工整理、逐行带引用的子集（Candiru / DevilsTongue、Paragon 的 Graphite）。手工部分离线可用；--update 只从固定的一组官方来源下载其余部分。

六、坑与注意

坑 1：Android 采集勾了"Hash files"，拖慢并扩大数据面

现象：AndroidQF 问卷默认建议 "Hash files → No"，勾选后额外计算大量文件哈希。 影响：采集时间大幅延长、采集包体积暴涨、敏感面变大。 修复：照 README 表格答，除 "Backup → Only SMS"、"Download copies of apps → Only non-system packages" 外一律 No。

坑 2：macOS 忘开 Terminal 完全磁盘访问权限，Safari 记录被静默跳过

现象：报告里 Safari 一片 "could not be checked"，工具不报错退出。 影响：以为查全了，实际最常见的投递渠道（浏览器）完全没查。 修复：系统设置 → 隐私与安全性 → 完全磁盘访问权限 → 加 Terminal → 打开 → 关掉并重开 Terminal 再跑。

坑 3：iPhone 备份密码忘记，加密备份读不了

现象：工具问备份密码，你输不进去。 影响：iPhone 部分直接作废。 修复：密码只能在 iPhone 上重置（设置 → 通用 → 传输或还原 iPhone → 还原 → 还原所有设置），然后重做一次备份。

坑 4：命中≠感染，误删破坏唯一证据

现象：报告出现 "Something matched"，第一反应是"赶紧删掉那个文件"。 影响：删除破坏取证链条，访问报告点名的地址还可能暴露你已经发现。 修复：不要删、不要访问、不要自行清理。保留报告并联系 Access Now 或 Amnesty Security Lab。

坑 5：Prefetch / Amcache 命中的证据强度被系统性高估

现象：execution-record / inventory-record 很容易被读成"这台电脑运行过 Pegasus"。 影响：误判带来不必要的恐慌与数据清除。 修复：读证据强度字段而非"有没有命中"，同时看 gap 清单。

坑 6：Windows 上 Python 没勾 PATH，双击 run-scan.cmd 什么也不发生

现象：窗口一闪而过，或报 'python' is not recognized。 影响：新手直接卡死。 修复：重跑 Python 安装器 → Modify → 勾 "Add Python to environment variables" → 重启电脑。

坑 7：扫描前忘了关浏览器和聊天软件

现象：Chrome / Edge / WhatsApp / Signal 还开着。 影响：数据库被占用，记录锁住，变成静默的 gap。 修复：关掉所有浏览器和聊天应用再跑（README 在 Windows 和 Mac 两节都列为前置步骤）。

坑 8：报告含私密信息，不要放进同步盘

现象：报告存到 Dropbox / iCloud / OneDrive。 影响：浏览器历史、短信链接、设备指纹同步到云端第三方——违背"只留本地"的承诺。 修复：报告留本地，用 --share-json summary.json 生成最小摘要后再分享。

坑 9：指标列表过期，"未命中"可能只是没更新

现象：三个月前更新过指标，中间 NSO 发布了新 IOC。 影响：结果看起来干净，实际是旧库跑的。 修复：README 建议每隔几周重跑 --update（唯一联网的命令）。

坑 10：没有签名版 Windows 可执行文件，这是设计而非缺陷

现象：想找 "download the .exe" 或验证代码签名。 影响：SmartScreen 会对未签名脚本告警。 修复：项目匿名运营，不会提供签名程序（代码签名证书需实名主体）。走源码运行 + 确定性构建校验。

七、与同类对比

维度 Zero-Breach-Toolkit MVT (mobile-security-toolkit) 商业取证产品 通用杀毒
目标 已知雇佣间谍软件痕迹初筛 已知间谍软件痕迹初筛 全维度取证 恶意软件通用检测
联网 扫描期间零请求 视模块而定 通常需要 常态需要
价格 免费开源 免费开源 昂贵 分层付费
证据可解释性 高（标注 gap 与证据强度） 中 高 低
内存分析 / 时间线 ❌ 部分 ✅ ❌
目标用户 非技术用户可上手 需技术背景 调查员 所有人
可审计性 极高（单文件 + 确定性构建 + GPG） 中 低（闭源） 低

和 MVT 的关系：同源同生态——指标来源里就含 MVT 项目的 mvt-indicators。差别在于本工具把"零技术门槛"放第一位（逐步图文指引、Windows 双击入口），MVT 更偏研究人员命令行工作流。

和商业取证产品：不是竞品，是层级不同。商业产品能做内存分析、影子拷贝、完整时间线，这个工具做不到。它的价值在于"零成本、零联网、源码可审计的第一道筛子"，以及诚实标注 gap 的报告格式。

和通用杀毒：互补而非替代。签名合法的间谍软件不触发杀毒特征库；本工具也不做通用恶意软件检测。

八、一句话推荐

如果你是记者、活动人士、人权工作者，或需要在一台不联网的设备上快速确认有没有已知间谍软件痕迹，这是目前少数几个免费、开源、只读、且报告诚实标注自身局限的工具——直接用，从源码跑起；如果你是安全工程师需要内存取证或完整时间线，请把它当 triage 第一步，后面接专业工具。

本文的不确定处（诚实标注）： - ⚠️ 文中命令、选项名、报告语义均取自 v0.1.7 tag（commit 951efefe5310272d476103cadd6e43a75417eb0b）的 README 与仓库树，未实际执行（本次为只读研究，不 clone、不跑代码）。 - ⚠️ 指标数量"约 12,400 条 / 29 个来源"为 README 原文表述，属浮动值，会随 --update 变化；本次未运行 --update 复核。 - ⚠️ "约 15 分钟"是 README 对本机标准检查的估计值，随机器与文件数量波动，未实测。 - ⚠️ star 数 1141 为 2026-10-28 经 GitHub API 读取的快照，非长期稳定值。 - ⚠️ 未核查的子模块：docs/COVERAGE.md、docs/METHODOLOGY.md、docs/PATTERNS.md、iocs/VALIDATOR-GAP.md、scan/CONTRACT.md（仅确认文件存在于仓库树），可能含本文未覆盖的细节。