tejcodes-rex/verdict
GitHub: tejcodes-rex/verdict
VERDICT 是一个基于 Claude Code 和自定义 MCP Server 的自主 DFIR 调查分析 agent，通过只读架构和确定性验证引擎在 SIFT Workstation 上实现可追溯、自纠正的数字取证。
Stars: 0 | Forks: 0
# VERDICT
**用于 DFIR 调查、关联和分流的可验证证据推理**
这是一个专为 SANS SIFT Workstation 设计的自主 incident response 分析师。VERDICT 扩展了 Protocol SIFT，引入了一个只读的 Custom MCP Server，将 SIFT 工具链转化为类型化的、对证据安全的函数；同时引入了一个 Claude Code agent，用于形成假设，根据实际工具输出验证每一项声明，并在信息源不一致时进行自我纠正。它的构建旨在匹配对手的速度，同时绝不牺牲响应者不能失去的一样东西：证据的完整性和发现的真实性。
Find Evil 旨在弥合机器速度攻击与人类速度响应之间的差距。2025 年 11 月，Anthropic 记录了 GTG-1002，这是一次国家级支持的行动，该行动驱动 Claude Code 进行侦察、漏洞利用和横向移动，实现了 80% 到 90% 的自主性，请求速率被 Anthropic 称为人类操作员在物理上不可能达到的。那是攻击方。Protocol SIFT 是防御方的答案，Rob Lee 的定位非常准确：用防御性 AI 编排来应对 AI 威胁速度。VERDICT 通过使自主响应者的两种失效模式（修改证据，以及自信地报告不真实的事物）在结构上变得不可能，而不仅仅是予以劝阻，从而强化了这种编排。
## 提交合规性（请先阅读此部分）
包含所有必需组件及其确切位置。本项目是完整的，每一项都在下面提供了链接。
| # | 必需组件 | 所在位置 |
|---|--------------------|-------------|
| 1 | **公共代码仓库，开源** | 本仓库。许可证见下文。 |
| 2 | **MIT 或 Apache 2.0 许可证文件** | [`LICENSE`](LICENSE) (MIT)，独立位于仓库根目录，可在 About 部分检测到。 |
| 3 | **包含设置说明的 README** | 本文件。请参阅 [设置](#setup-two-paths) 和 [运行它](#run-an-investigation-for-judges)。 |
| 4 | **实时部署或分步运行说明** | [运行调查](#run-an-investigation-for-judges)：一条 Docker 命令，或在 SIFT 上原生运行。 |
| 5 | **功能和特性的文本描述** | 下方的 [它的作用](#what-it-does)，以及 Devpost 项目页面。 |
| 6 | **演示视频（实时终端、语音旁白、自我纠正）** | 链接位于 Devpost 页面顶部。一个真实的 asciinema 终端录制（原始 cast 文件提交于 [`logs/examples/demo_session.cast`](logs/examples/demo_session.cast)，可通过 `asciinema play` 回放，证明它是真实的终端捕获）。脚本位于 [`docs/demo_script.md`](docs/demo_script.md)。 |
| 7 | **架构图** | [`docs/architecture.png`](docs/architecture.png) (及源文件 [`docs/architecture.svg`](docs/architecture.svg))，叙述见 [`docs/architecture.md`](docs/architecture.md)。标出了全部五种元素类型和两个信任边界。 |
| 8 | **证据数据集文档** | [`docs/datasets.md`](docs/datasets.md)：来源、哈希值，以及 agent 发现的内容。 |
| 9 | **准确性报告** | [`docs/accuracy_report.md`](docs/accuracy_report.md)，加上每次运行时在每个 run 目录中自动生成的 `accuracy_report.md`。 |
| 10 | **Agent 执行日志（可追溯到工具执行）** | [`logs/examples/`](logs/examples/)：包含完整运行的 agent 流 (`agent_stream.jsonl`) 和工具来源 (`provenance.jsonl`)。 |
使用的架构模式（根据简报）：**模式 2，Custom MCP Server**，以 Claude Code 作为代理引擎。三个必需的能力（无需人工干预的自我纠正、可追溯到特定工件的准确性验证，以及结构化的调查叙述）在 [设计如何映射到评估标准](#how-the-design-maps-to-the-judging-criteria) 中进行了演示和描述。
针对官方第一阶段资格提示（评委运行的确切 12 项检查，来自 Judge Pack 附录 A）的完整自我审计位于 [`SUBMISSION_CHECKLIST.md`](SUBMISSION_CHECKLIST.md) 中。评委不可妥协的“将任何发现追溯到其工具执行”检查已为您完成，并在 [`docs/three_claim_trace.md`](docs/three_claim_trace.md) 中提供了三个具体示例。
## 它的作用
您将 VERDICT 指向一个案件（一个磁盘镜像、一个内存捕获、一个数据包捕获，或者来自同一主机的多个内容），它会像资深分析师一样执行完整的分流：
1. **定位**证据，在接触任何对象之前记录每个对象的只读监管链哈希值。
2. **形成可证伪的假设**，关于发生了什么，并指出能够确认或推翻每一个假设的工件。
3. **自适应地编排工具。**它运行能够决定某个假设的最廉价的工具，读取结果，并让该结果决定下一个工具。没有固定的 pipeline。
4. **验证每一个发现。**在任何声明被允许写入报告之前，一个确定性引擎会重新读取已归档的工具输出，并检查所断言的值是否真实存在于两个独立的来源中，之后才会将任何内容称为已确认。
5. **自我纠正。**当引用的输出不支持某项声明时，该声明会被视为可能的幻觉并被撤回。当两个来源不一致时，agent 会运行第三个来源来打破僵局。每一次思路的改变都会连同触发它的执行过程一起被记录下来。
6. **交叉检查来源。**给定一台主机的磁盘和内存镜像，它会比较它们并标记差异，而这正是真实入侵隐藏的地方。
7. **证明完整性并生成报告。**它对原始文件重新进行哈希处理以证明它们从未被修改过，然后生成结构化的调查叙述和诚实的准确性报告，这两者均根据运行账本生成。
其结果是一项同事可以在交叉询问中进行辩护的调查：每一句话都可以追溯到特定的工具执行，已确认的事实与推论分开，并且 agent 发现自己犯的错误也被记录在案。
## 它与基线的不同之处
基线 Protocol SIFT 是一个 Claude Code 配置：技能文件加上行为规则，交给模型一个 shell (`Bash(*)`) 并要求它小心行事。它的防护栏是基于 prompt 的，并且它将原始工具输出输入到模型上下文中，这是有记录的导致其产生幻觉的根源。
VERDICT 改变了架构，而不仅仅是 prompt：
| 关注点 | 基线 Protocol SIFT | VERDICT |
|---------|------------------------|---------|
| 证据安全 | Prompt 指出“绝不修改”；但 shell 仍然可以做任何事情 | 没有 shell，不存在任何写入工具；文件以 `O_RDONLY` 方式打开；强制将写入操作限制在证据根目录之外 |
| 幻觉控制 | “不要产生幻觉”指令 | 确定性验证引擎根据归档输出重新检查每一项声明 |
| 自我纠正 | “失败时重试”指令 | 结构性：一个 UNSUPPORTED 或 CONTRADICTED 的判定会强制撤回或打破僵局，并连同触发器一起记录 |
| 上下文过载 | 原始工具转储直接进入模型 | 输出被解析为紧凑的摘要；原始数据归档到磁盘并通过 id 引用 |
| 审计追踪 | 停止时追加的摘要行 | 每次执行对应一条结构化的来源记录；每个发现都会打印其 exec id |
## 设置（两种途径）
### 途径 A：Docker（推荐评委使用，一条命令）
要求：Docker 和 Claude Code 凭证（一个 `ANTHROPIC_API_KEY`，或挂载的 `~/.claude`）。无需其他任何内容。
```
git clone https://github.com/tejcodes-rex/verdict.git
cd verdict
docker build -t verdict:latest .
```
该镜像包含固定版本的 SIFT 工具链子集（The Sleuth Kit、Volatility 3、用于较旧或 32 位内存镜像的 Volatility 2.6、tshark、YARA、RegRipper、ExifTool）以及 agent runtime，因此无需启动 SIFT VM 即可在任何机器上重现运行。
### 途径 B：在 SANS SIFT Workstation 上原生运行
在 SIFT Workstation 上，工具已经安装好了。安装 server 和 agent 配置：
```
git clone https://github.com/tejcodes-rex/verdict.git
cd verdict
pip3 install -e .
# 将 Claude Code 指向 VERDICT MCP server 和 doctrine：
cp agent/CLAUDE.md ~/.claude/CLAUDE.md
cp agent/settings.json ~/.claude/settings.json
```
MCP server 会在 runtime 解析每个工具（SIFT 路径 `/opt/volatility3*/vol.py` 下的 Volatility 3，SIFT 路径 `/usr/local/bin/vol.py` 下的 Volatility 2，其余在 PATH 中），并带有 `VERDICT_` 环境变量覆盖。使用一条命令确认您的环境：
```
python3 -m verdict.doctor # prints exactly which tool resolved, and where
```
这是针对真实的 SIFT 工具布局验证过的：在故意将 `vol` 排除在 PATH 之外（如在 OVA 中）的情况下，VERDICT 将 Volatility 3 解析为 `python3 /opt/volatility3/vol.py`，从该路径执行它，并在 SIFT 工具链上运行了实时调查。请参阅 [`docs/architecture.md`](docs/architecture.md) 和准确性报告。
## 运行调查（面向评委）
带有已发布 ground truth 的样本证据记录在 [`docs/datasets.md`](docs/datasets.md) 中。Nitroba 网络案件很小（53 MB）并且可自我验证。要重现头条运行：
```
# 1. 获取样本 evidence（脚本从官方来源下载并验证 hashes）
bash scripts/fetch_sample_evidence.sh
# 2. 在 Docker 中运行完整的 autonomous investigation。
# Evidence 以 read-only 方式挂载；所有输出均存放在 ./work 中。
ANTHROPIC_API_KEY=sk-... \
EVIDENCE=$(pwd)/evidence/cases/nitroba \
WORK=$(pwd)/work \
docker compose run --rm --entrypoint bash verdict \
scripts/run_investigation.sh nitroba /evidence /work
```
（镜像入口点是 MCP server 本身；`--entrypoint bash` 会运行调查驱动程序。如果您不想使用 compose，等效的 `docker run` 位于 [`docs/submission_guide.md`](docs/submission_guide.md) 中。)
Agent 身份验证：该 agent 是 Claude Code，因此它需要您的 Claude 凭证。导出 `ANTHROPIC_API_KEY`（如上所示），或者，如果您使用 Claude 订阅，则通过在运行命令中添加 `-v $HOME/.claude:/root/.claude` 来挂载您现有的登录信息。该镜像绝不包含凭证；您需要在运行时提供它们。这是唯一的外部依赖，而且也是本次赛事评委已经拥有的依赖。
完成后，请查看最新的 `./work/run-*/` 目录：
- `report.md` 是调查叙述。
- `accuracy_report.md` 是根据 ground truth 评定的自我评估。
- `provenance.jsonl` 是工具执行审计追踪。
- `agent_stream.jsonl` 是完整的 agent 执行日志。
要针对您自己的证据运行 agent，请将其放入一个目录中并作为 `EVIDENCE` 传入。Agent 会根据其找到的任何数据类型进行自适应调整。
## 设计如何映射到评判标准
- **自主执行质量。** Agent 基于明确的假设账本进行推理，并根据其学到的内容重新排序。自我纠正是结构性的：由真实工具输出计算出的验证判定会强制执行。触发因素是真实的（输出中缺少某个值、两个来源不一致），因此它们无法被人为安排。参见 [`docs/architecture.md`](docs/architecture.md)。
- **IR 准确性。** 如果其断言的值不存在于两个独立的来源中，任何声明都不会进入已确认列表。已确认的事实和推论有明确的标记。准确性报告是根据账本生成的，列出了 agent 捕获到的幻觉，并根据已发布的 ground truth 进行评分。
- **广度和深度。** 深入处理磁盘（The Sleuth Kit）、内存（Volatility 3、Volatility 2 和无符号字符串分析）、网络、Windows 注册表和程序执行证据（RegRipper、Shimcache、Amcache），以及 IOC 搜寻（YARA），并提供基于事实的 MITRE ATT&CK 映射。在真正的 SIFT Workstation 上运行的 Ali Hadi 案件 ([`logs/examples/alihadi_sift/`](logs/examples/alihadi_sift/))，将来自一台主机的 3 GB 磁盘镜像和 1 GB 内存捕获关联起来：它重建了完整的 kill chain（DVWA 命令注入、sqlmap SQL 注入活动、三个 webshell（包括 Meterpreter payload）、磁盘上 SAM 中的两个攻击者创建的账户以及 RDP 持久性），并且只有在内存捕获独立证实了相同的注入命令时，才将 RDP 持久性发现提升为 CONFIRMED。持久性的跨来源验证被视为一类高价值发现。
- **约束实现。** 防护栏是架构性的：server 不暴露任何破坏性原语，证据以只读方式打开 (`O_RDONLY | O_NOFOLLOW`)，内存工具拒绝任何 Volatility dump 插件或输出标志，因此工具参数不能成为写入原语，配置层作为纵深防御拒绝通用 shell 和写入工具。绕过测试记录在准确性报告中。
- **审计追踪质量。** 每次执行对应一条来源记录；每个发现都会打印其 exec id；三声明追踪是机械化的。来源日志是一个防篡改的哈希链，每次运行都在 `manifest.json` 中使用经过验证的链头进行密封。
- **可用性和文档。** 一条 Docker 命令即可运行，并在真正的 SANS SIFT Workstation 上进行了验证：官方 OVA 已启动，完整的自主 agent 在其上端到端地运行（`logs/sift_verification/`，以及位于 `logs/examples/nitroba_sift/` 下的 SIFT 运行）；`python3 -m verdict.doctor` 可报告任何上的工具解析情况。提供 ground truth 样本、已提交的运行、实时调查视图 (`scripts/agent_live.py`)，以及与示例提交的诚实正面对比 (`benchmark/VALHUNTIR_COMPARISON.md`)。
每个经过验证的发现也会映射到 **MITRE ATT&CK** 技术（以确定性方式，仅基于已确认的发现，因此它不会产生幻觉上下文），从而为分析师提供 kill chain 的全貌，而没有知识库查找带来的虚假上下文风险。
## 仓库布局
```
verdict/
verdict/ the Python package (MCP server, engine, tools, reports)
server.py the MCP server: typed read-only tools + reasoning tools
evidence.py read-only evidence vault and integrity guarantees
provenance.py per-execution audit records (JSONL)
corroborate.py deterministic claim verifier
ledger.py hypotheses, findings, self-correction events
tools/ sleuthkit, volatility3, tshark, plaso wrappers
report/ narrative and accuracy-report generators
agent/ the agentic engine config: doctrine + read-only permissions
scripts/ run an investigation, fetch sample evidence, score a run
groundtruth/ answer keys for scored cases
docs/ architecture, datasets, accuracy report, demo script
logs/examples/ a committed full run (agent stream + tool provenance)
tests/ smoke tests that exercise the stack on real evidence
```
## 许可证
MIT。请参阅 [`LICENSE`](LICENSE)。本项目基于开源的 Protocol SIFT 和 SANS SIFT Workstation 构建；新颖的贡献（只读的 MCP server、验证引擎、假设账本以及来源和报告层）是为本次活动原创的工作，并已在全文中作为此类工作记录在案。
标签：DLL 劫持, MCP, 大语言模型, 安全运营, 库, 应急响应, 扫描框架, 数字取证, 自动化分析, 自动化脚本, 请求拦截, 跨站脚本, 逆向工具