aptwatcher/APTWatcher

# APTWatcher DFIR APTWatcher 是一个防御性 AI agent，它以机器速度对受损主机进行分诊，关联多个情报来源的取证工件，并生成具备分析师水准且带审计追踪的 IR 报告 —— 没有幻觉，且绝不触碰证据。 ## 为什么需要 在 2025 年，GTG-1002 攻击活动展示了一次国家支持的攻击行动，其中 agentic LLM 执行了大约 80–90% 的攻击链 —— 侦察、初始访问、横向移动、数据暂存 —— 无需任何人类按键。传统的防御者循环（一个工单、一名人类分析师、一个长达数天的分诊窗口）无法与在几分钟内即可完成目标的对手相抗衡。请参阅 [`docs/SCOPE.md`](docs/SCOPE.md) 中的威胁模型。 APTWatcher 的答案是速度对等，而非自主性对等。它运行与攻击者相同的操作原语 —— agentic 编排、MCP 工具接口、迭代的“计划-执行-验证”循环 —— 但受到严格的只读证据模式、经授权方可进行的状态更改以及仅追加的签名审计日志的约束。防御者保留对监管链和发布的控制权；而 agent 提供速度。 ## 快速开始 只需一个幂等安装器，即可适用于任何带有 Python 3.11+ 的 Linux 主机（SIFT 工作站会自动探测完整的工具链）。它拒绝以 root 身份运行，且绝不写入 `~/APTWatcher` 之外的任何位置： ``` curl -fsSL https://raw.githubusercontent.com/aptwatcher/APTWatcher/main/install.sh | bash source ~/APTWatcher/.venv/bin/activate ``` 这三个命令可以立即工作 —— 无需取证 VM，无需 API 密钥，无需真实证据： ``` aptwatcher version # build and environment info aptwatcher profiles # list the bundled triage profiles aptwatcher eval # run the accuracy harness against shipped fixtures ``` 完整的十分钟面向评委的演练 —— 演练分诊、分析包、存根发布、自我评分 —— 位于 [`docs/TRY-IT-OUT.md`](docs/TRY-IT-OUT.md) 中。 ## 内部构成 | 组件 | 数量 | 备注 | |---|---|---| | MCP 工具 | 51 | 42 个 tier-0 只读取证工具 + 9 个 tier-1 情报工具 | | CLI 子命令 | 9 | `version`, `profiles`, `preflight`, `knowledge-search`, `run`, `analyze`, `publish`, `eval`, `audit-render` | | SIFT 工具封装 | 10/10 | volatility3, plaso, bulk_extractor, sleuthkit, yara, hayabusa, regripper, chainsaw, timesketch, sift_update | | 知识库条目 | 32 | 洁净室编写，在调查结果中被引用 | | 准确度固定数据 | 8 | 在种子固定数据上的平均 F1 为 1.000 —— 这验证的是底层管道，而非现场准确度；请参阅 [`docs/ACCURACY.md`](docs/ACCURACY.md) | | 发布适配器 | 5 | Netcraft, MISP, GLPI, TAXII 2.1, stub —— 默认全部为演练状态 | | 测试 | 746 个通过 | 1 个被跳过；ruff 检查通过；在 `src/core` 上 mypy 严格模式检查通过；Python 3.11+ | ## 架构 APTWatcher 以**三种部署模式共享同一个大脑**的形式发布： - **模式 A — Direct Agent Extension** 面向 Claude Code / OpenClaw 用户 - **模式 B — Custom MCP Server** 用于严格的架构护栏 - **模式 C — Hybrid** 结合了两者（推荐） 所有这三种模式都由相同且经过精心管理的知识库、情报适配器、审计记录器和自我纠正 prompt 提供支持。请参阅 [`docs/design/deployment-modes.md`](docs/design/deployment-modes.md)。 各项能力按层级划分并采用选择性启用： | 层级 | 能力 | 默认状态 | 来源 | |------|---------------------------------|-------------|------------------------------------------| | 0 | 核心取证分诊 | **启用** | Protocol SIFT 工具，`knowledge/` 基础库 | | 1 | 外部威胁情报 | 选择性启用 | APT Watch API, MS Threat Analytics MCP | | 2 | IR 工作流集成 | 选择性启用 | GLPI MCP（工单、知识库） | | 3 | 防御性遏制 | 选择性启用 | cnc_disruptor（管道终止，会话 RST） | | 4 | 攻击性遏制 | **受限启用** | cnc_disruptor（法律/道德警告） | Tier 0 在构造上是只读的；tier 1 及以上层级在任何工具触发前，都需要一个明确的 `consent_granted` 审计事件。完整的设计位于 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 中，而 agent 本身运行所依据的操作契约 —— 包含最高指令、角色允许列表和故障模式 playbook 的编排器大脑 —— 位于 [`CLAUDE.md`](CLAUDE.md) 中。 ## 演示 - [`demo/SCRIPT.md`](demo/SCRIPT.md) — 现场演示脚本。 - [`docs/demo/WALKTHROUGH.md`](docs/demo/WALKTHROUGH.md) — 带有预期输出的端到端注释 演练。 - [`docs/scenarios/`](docs/scenarios/README.md) — 评分规则场景 S01–S03 （单台 Windows 受损，多主机横向移动，勒索软件预引爆）。 - [`scenarios/`](scenarios/README.md) — 演示场景 S04–S05 （签名的离线到在线包交接；在 14.5 分钟预算内的一次性 E01 分诊至签名的 IncidentBundle）。 ## 提交文档 专为黑客马拉松评委准备，四个提交文档集中在此： - [`docs/TRY-IT-OUT.md`](docs/TRY-IT-OUT.md) — 针对内置固定数据进行分步本地运行 （设计上无实际部署：只读、离线）。 - [`docs/DATASET.md`](docs/DATASET.md) — 证据数据集清单、来源以及洁净室策略。 - [`docs/ACCURACY.md`](docs/ACCURACY.md) — 准确度方法论、基准线及客观存在的局限性。 - [`docs/DEVPOST.md`](docs/DEVPOST.md) — 项目叙述。 ## 护栏 - **默认只读。** 所有 42 个 tier-0 取证工具绝不修改证据，也绝不产生外部网络流量。衍生数据只会进入 `work/` 和 `out/`，绝不与工件放在一起。 - **授权许可机制。** Tier 1+ 工具需要匹配的 `consent_granted` 审计事件，这在 MCP 服务器中强制执行 —— 工具无法绕过它。请参阅 [`docs/design/tier-gating.md`](docs/design/tier-gating.md)。 - **演练式发布。** 所有五个适配器默认为 `dry_run=True`；要进行实时发布，需要 `--live` 标志以及一个签名的 IncidentBundle。 - **签名审计日志。** 每一个计划/执行/验证/自我纠正步骤都会发出一个仅追加、带有 token 遥测数据的签名 AuditEvent；使用 `aptwatcher audit-render` 进行渲染。调查结果必须引用事件 ID，否则不视为有效结果。 - **签名包。** 经过 Ed25519 签名的 IncidentBundle 可跨过离线到在线的鸿沟传递结果，并在导入时进行篡改检测。请参阅 [`docs/design/evidence-integrity.md`](docs/design/evidence-integrity.md)。 - **无 shell 转义。** 工具通过绝对路径调用二进制文件并采用 arg-vector 调用方式 —— 没有 `shell=True`，没有 `eval`，也不进行针对 shell 的字符串插值。 ## APTWatcher DFIR 不是 APTWatch 使用 `DFIR` 限定词是为了将本项目与一个名称相似的项目区分开来。APTWatcher DFIR（本项目）是一个**防御性数字取证与应急响应 agent**。APTWatch (`aptwatch.org`) 是一个独立的威胁情报平台，对外提供 `api.aptwatch.org`。APTWatcher 将该 API 作为其 MCP 工具之一进行调用 —— 它们是同一品牌家族下的独立项目。包名、CLI (`aptwatcher`) 和代码库保留了简短的名称 `APTWatcher`；`APTWatcher DFIR` 是完整的显示名称。 ## 状态 开发中。有关提交前的检查关卡，请参阅 [`SUBMISSION-CHECKLIST.md`](SUBMISSION-CHECKLIST.md)；有关当前的工作进展，请查看 GitHub issue 跟踪器。 ## 许可证 MIT — 请参阅 [`LICENSE`](LICENSE)。

标签：AI智能体, 威胁情报, 库, 应急响应, 开发者工具, 电子取证, 自动化防御