`。
## 您将获得什么
每次运行都会写入一个独立的 case 目录：
| Artifact | 它是什么 |
|---|---|
| `audit.jsonl` | 每个工具调用和 Finding 的只追加、哈希链日志（每条记录包含 `prev_hash`） |
| `verdict.json` | 绑定证据的结论和 Findings，每个都引用了 `tool_call_id` 和置信度层级 |
| `coverage_manifest.json` | 按 artifact 类别划分的范围台账：可用 / 已尝试 / 已解析 / 失败 / 不支持 / 未提供 —— 明确的防过度声明边界 |
| `run.manifest.json` | 规范化工具输出的 Merkle root 以及签名元数据 —— 可离线验证 |
| `REPORT.md` / `REPORT.html` / `REPORT.pdf` | 分析师报告：Findings、ATT&CK 覆盖率、标准化时间线、后续行动。`REPORT.md` 总会被写入；当系统中存在相应工具时，将生成 `REPORT.html`（需要 pandoc）和 `REPORT.pdf`（需要 headless Chrome） |
Each run seals into a hash-chained audit log, a Merkle root over canonical tool outputs, and a signed manifest — verifiable offline with manifest_verify.
## 查看运行过程
下方的每一次捕获都是真实运行，而非模拟。完整图库：[`docs/showcase/`](docs/showcase/)。
One command, the typed DFIR pipeline, a signed SUSPICIOUS verdict with manifest_verify = PASS.
The NIST SCHARDT.dd case through SIFT: SUSPICIOUS with 8 confirmed tool executions (cain.exe, mIRC, Ethereal, NetStumbler), each tool-cited, in a signed report.
A 22-host compromised-enterprise case (SRL-2018, 198 GB) run host-by-host with the toolchain executing inside the SANS SIFT VM over SSH. Showcase walkthrough (4:35).
Cross-host fleet rollup, and the base-file server flagged SUSPICIOUS on a confirmed Security-log wipe (EID 1102), with PowerShell-LOLBin and service-install leads held at HYPOTHESIS.
## 工作原理
每个 Case 都运行相同的九阶段 pipeline，每个阶段完成后都会实时显示在仪表板上：
1. **Evidence locked** — `case_open` 对证据进行 SHA-256 计算并打开一个只读的 Case。
2. **Persistence pool** — 第一个分析 pool 作为 subagent 分支并搜寻持久化机制；每个 Finding 都会引用生成它的 `tool_call_id`。
3. **Exfiltration pool** — 第二个 pool 以倾向于数据渗出的先验假设并行处理相同的证据，因此相互竞争的假设会浮出水面，而不是隐藏在共识中。
4. **Cross-check** — `detect_contradictions` 在任何内容合并之前标记出存在分歧的 Findings。
5. **Verify** — 验证器重新运行每个被引用的工具并比较输出哈希；输出发生漂移的 Finding 将被拒绝。
6. **Weigh** — `judge_findings` 按声明以可信度加权进行合并；执行声明需要 ≥2 种 artifact 类别，否则保持为 `HYPOTHESIS`。
7. **Correlate** — `correlate_findings` 将幸存的发现整合为一个连贯的攻击故事。
8. **Sign** — `manifest_finalize` 将运行封装为哈希链、Merkle root 和签名的 manifest。
9. **Report** — 分析师报告和结论。
三个设计选择承载了核心重任：
1. **类型化的 MCP 工具表面 —— 没有 `execute_shell`。** 43 个狭窄的、经过 schema 验证的产品工具：31 个
Rust DFIR 工具（`case_open`、`vol_pslist`/`psscan`/`psxview`、`mft_timeline`、`evtx_query`、
`hayabusa_scan`、`yara_scan`、`registry_query`、`prefetch_parse`、`pcap_triage` 以及允许列表内的
长尾封装器）加上 12 个 Python 加密/分析工具。Copyleft 和源码可用的引擎
（Hayabusa、pandoc、tshark、Volatility 3、Velociraptor）仅作为 subprocess 被调用，从而保持
Apache-2.0 代码树的许可证纯净。
2. **加密的证据保管链。** 哈希链审计日志 → 基于 canonical-JSON 工具输出的 Merkle root
（由 Python manifest 构建器计算，映射 `rs_merkle` 语义） → 签名的
manifest。默认签名者是可以离线验证的本地 Ed25519 密钥；Sigstore/Rekor 是
身份和透明度日志层。`manifest_verify` 离线检查链和 root，并且
客户发布候选版本携带专家签名包。该保管模型是为
FRE 902(14) 自我认证证据而构建的 —— 参见
[`docs/cryptographic-attestation.md`](docs/cryptographic-attestation.md)。
3. **将竞争性假设分析作为 agent 拓扑。** 两个 pool 以相反的先验假设调查相同的证据。
它们的分歧将作为第一类 `kind=contradiction` 记录输出，然后再由可信度加权的裁判合并它们 —— 浮出水面，而非隐藏。两个 pool 并不能证明
真相；可重放的工具输出链才能做到。
Findings 遵循严格的认知层级 —— **CONFIRMED**（≥2 种确凿的 artifact 类别，
验证器通过） > **INFERRED**（从已确认的事实推导而来） > **HYPOTHESIS** —— 并且执行
声明至少需要两种 artifact 类别。
## 功能
- **在一个 Case 中同时处理磁盘和内存。** 借助本地 Sleuth Kit/libewf 支持或在 SIFT 模式下，它可以只读地打开
原始/E01 镜像，并提取 `$MFT`、注册表 hive、EVTX 和 Prefetch
（`disk_mount` / `disk_extract_artifacts` / `disk_unmount`），然后在同一个 Case 中分析内存。
没有支持已挂载/提取内容的原始磁盘将保持仅为保管状态，并诚实地标记为 `INDETERMINATE`。
当前提条件具备时，支持的磁盘镜像可以通过 Sleuth Kit 直接读取在本地解析；仅运行 `case_open` 依然只保持保管状态，而不支持的 artifact 类别将作为指定的限制保留。
（[工具清单](docs/reference/mcp-and-tools.md))
- **自我验证的 Findings。** `verify_finding` 重新运行每个被引用的工具调用，并确认输出
SHA-256 仍然匹配；`detect_contradictions` 在裁判合并之前将 pool 冲突作为第一类记录提出
—— 因此第三方可以独立重放该链条。（[工具](agent-config/TOOLS.md))
- **大规模 fleet 扫描。** 运行整个资产，而不只是一台机器：investigate → correlate → render pipeline
生成单个跨主机的 `FLEET_REPORT`，显示仅出现在多台机器上的信号 ——
多台主机上运行的相同罕见进程、近乎同时的进程创建浪潮、MITRE 技术的
传播。可在 SANS SIFT VM 中运行（[fleet 分析](docs/using/fleet-analysis.md)）或在本地逐主机运行而无需 VM（[全 case 本地运行](docs/using/whole-case-local-run.md)）。
- **可选的判定后操作。** 当操作员部署了 n8n 工作流时，判定可以驱动
通知、工单或遏制步骤。开箱即用时不会部署任何工作流，因此该步骤
记录为已跳过。无论哪种情况，它都位于审计链之外 —— 既不是证据，也不是 Finding。
## 准确性与范围
如果没有解析器或工具能提取出某个 artifact 类别，VERDICT 就无法对其进行推理 —— 这就是信任
边界，而不是脚注。每次运行都会写入一个 `coverage_manifest.json` sidecar（并将相同的
对象嵌入到 `verdict.json` 中），每个 artifact 类别对应一行。最强有力的声明不是“AI
审查了整个镜像”；而是通过可重放的工具检查了被引用的 artifact。
有争议或不支持的线索保持可见，表现为矛盾、`HYPOTHESIS` 或
`analysis_limitations`。
准确性是根据公布的答案标准进行衡量的，而非断言。该仓库在 `goldens/` 下附带了小型答案标准；
大型测试集使用 `scripts/fetch-fixtures.sh` 进行分阶段处理，然后使用
`scripts/score-recall.py tmp/auto-runs/ --golden goldens/` 进行评分。方法、语料库形态、
误报控制以及客观限制详见 [`docs/accuracy-report.md`](docs/accuracy-report.md)；
对抗性挑战详见 [`docs/red-team-challenge.md`](docs/red-team-challenge.md)。
## 开始使用
单条命令即可安装产品前提条件并验证环境：
```
bash scripts/setup
```
它将安装工具链（Rust、uv、Node、pnpm）以及它能管理的受支持的本地 DFIR 二进制文件
（Volatility 3、Hayabusa、Chainsaw、Velociraptor、Sleuth Kit、tshark、pandoc —— YARA 内置于
Rust 二进制文件中），构建并验证两个 MCP 服务器，运行 preflight `doctor`，并打印出客观的
绿色/黄色摘要。常见变体：
```
bash scripts/setup --run # install, then watch evidence/ and investigate on drop
bash scripts/setup --with-sift # install local prerequisites and provision the SANS SIFT VM
bash scripts/setup --json # machine-readable status for scripts/CI
```
scripts/doctor.sh: one preflight, an honest green/amber summary, then you are ready to run.
**SANS SIFT VM** 是参考取证环境，并为磁盘镜像一致性提供完整的工作站基准；
`--with-sift` 以无头模式获取受限的 9.3 GB OVA 并构建 VM，
遇到任何故障时都会干净地回退到本地模式（内存、EVTX、PCAP、Velociraptor 和受支持的磁盘工件）。
完整的前提条件见 [INSTALL.md](INSTALL.md)；各环境（本地 vs.
SIFT VM）的详细信息见 [QUICKSTART.md](QUICKSTART.md)。
要运行 Case，请将 `verdict` 指向单个镜像或混合的 case 目录（内存 + EVTX + 磁盘 +
网络 + Velociraptor）：
```
scripts/verdict
# --sift 在 SANS SIFT VM 内运行 DFIR 工具（默认：local host）
# --watch 监视 evidence/ 并在下次放入时进行调查
# --no-dashboard 不要自动打开浏览器
```
位于 `http://localhost:3000` 的仪表板会实时流式传输运行过程。证据文件绝不会被提交
（它们被 gitignore 忽略），因此全新的克隆不包含任何证据文件 —— 使用
`bash scripts/fetch-fixtures.sh` 暂存公共数据集（来源和 SHA-256 见 [docs/DATASET.md](docs/DATASET.md)）或者将
您自己的镜像拖放到 `evidence/` 中。每次运行都是一次实时测试：确认 `tmp/auto-runs//verdict.json`
包含真实的结论，且 `manifest_verify.json` 报告 `overall: true`。
Agent mode: one prompt scopes the evidence (four EVTX samples — lateral movement, defense evasion, credential access) and bootstraps the pipeline.
## 仓库结构
```
.
├── agent-config/ — runtime agent identity (SOUL / AGENTS / PLAYBOOK / TOOLS / MEMORY)
├── services/mcp/ — Rust MCP server (31 typed DFIR tools)
├── services/agent_mcp/ — Python MCP server (12 crypto / ACH / memory tools)
├── services/agent/ — findevil_agent package (crypto chain + ACH primitives)
├── apps/web/ — Next.js dashboard (live audit-stream viewer + design system)
├── scripts/ — verdict launcher, report renderer, CI smoke runners
├── docs/ — reference/ (tools + deps + env), using/ (how to run), architecture, crypto attestation
└── .mcp.json — Claude Code auto-spawn registry: 6 MCP servers (2 product + 4 non-product helpers)
```
## 文档
- [已发布的文档](https://timothyvang.github.io/verdict-dfir/) — GitHub Pages 站点
- [docs/README.md](docs/README.md) — 官方文档索引
- [docs/using/running-verdict.md](docs/using/running-verdict.md) — 所有标志、运行模式和输出文件
- [docs/reference/mcp-and-tools.md](docs/reference/mcp-and-tools.md) — 完整的 MCP-server 和工具清单（[依赖项](docs/reference/dependencies.md)）
- [docs/architecture.md](docs/architecture.md) — 信任边界和 agent 拓扑
- [docs/cryptographic-attestation.md](docs/cryptographic-attestation.md) — 证据保管链和 FRE 902()
- [docs/verdict-semantics.md](docs/verdict-semantics.md) — `SUSPICIOUS` / `INDETERMINATE` / `NO_EVIL` 的含义
- [docs/false-positives.md](docs/false-positives.md) — VERDICT 如何避免过度声明
- [docs/release-surface.md](docs/release-surface.md) — 发布渠道和公开来源边界
## 许可证
Apache-2.0。见 [LICENSE](LICENSE)。
VERDICT 最初是为 SANS Find Evil! 2026 挑战赛开发的，并作为一个
独立的 DFIR 工具进行维护。内部标识符（findevil-mcp、@findevil/web、
scripts/find-evil）保留了该名称；标准的操作员命令是
scripts/verdict。
