nebulae/trudi

# TRUDI **数字调查威胁响应单元 (Threat Response Unit for Digital Investigation)** 构建于 SANS SIFT Workstation 之上的自主 DFIR agent。TRUDI 可执行完整的应急响应调查——磁盘分类、内存取证、Windows 工件解析、IOC 丰富化、YARA 狩猎——并生成一份带有完整审计追踪的结构化分析师报告，整个过程无需在每一步提示确认。 一个独立的模型逐步指导调查阶段，而对抗性审查器会在每个结论进入报告之前对其进行质疑。TRUDI 仅报告那些通过审查的内容。 为 [Find Evil! 黑客马拉松](https://findevil.devpost.com/) 打造 — SANS Institute / Devpost，2026 年 4 月至 6 月。 ## 目录 **本 README：** [工作原理](#how-it-works) · [前置条件](#prerequisites) · [安装说明](#setup) · [API 密钥](#api-keys) · [开启案件](#starting-a-case) · [实时监控（实验性）](#live-monitoring--autonomous-response-experimental) · [产出内容](#what-gets-produced) · [Trace 仪表板](#trace-dashboard) · [提交组件](#find-evil-submission-components) · [工具命名空间](#tool-namespaces) · [YARA 规则](#bundled-yara-rules) · [证据约束](#evidence-constraints) · [测试套件](#running-the-test-suite) · [仓库布局](#repository-layout) · [许可证](#license) **文档：** | 文档 | 包含内容 | |-----|--------------| | [试用体验](docs/try-it-out.md) | 分步指南：浏览已完成的运行（无需密钥）或驱动端到端的新调查 | | [架构](docs/architecture.md) | 组件、MVP 边界、防护层级、安全边界（[Mermaid 源码](docs/architecture.mmd) · [图表 PNG](docs/media/architecture.png)） | | [项目描述](docs/project-description.md) | Devpost 故事 — 设计原理、推理循环、门控、好奇心预算 | | [数据集文档](docs/datasets.md) | 每个案件的来源、证据源、发现和答案参考 | | [准确性报告](docs/accuracy-report.md) | 误报、遗漏的工件、捕获的幻觉、置信度校准、证据损毁 | | [实时监控演示](demo/live-monitoring/README.md) | *（实验性）* Velociraptor + 受害者 Docker 栈以及自动保护循环详解 | | [实时端点测试](docs/live-endpoint-testing.md) | *（实验性）* 针对运行中主机的只读 `live.*` SSH 分类 | | [媒体](docs/media/README.md) | 仪表板截图 + 演示视频说明 | ## 工作原理 TRUDI 是一个 **三模型系统** — 一个分析师和两个独立配置的推理模型，分别负责指导和挑战它： **Claude（主要分析师）** — 编排调查、选择工具、通过 TRUDI MCP server 运行工具、解读输出并撰写报告。 **DAIR 阶段控制器** (`dair.*`) — 以递归状态机的方式运行调查（分类 → 收集 → 分析 → 扫描 → 报告）。在每批工具执行完毕后，`dair_assess` 会重新审查证据现状，决定下一个阶段，并发出受约束的 `priority_tools` 工作指令。**DAIR 负责规划；Claude 负责执行。** 其后端通过 `DAIR_BACKEND` 独立配置。 **对抗性审查器** (`reason.*`) — 从两个方向对调查提出挑战： 1. **上游** — 在每次进入分类阶段时，它会生成一个优先级计划和相互竞争的假设（至少包括一个非先导性的行为者/机制），约束首先运行哪些具有区分度的工具。 2. **下游** — 在任何结论进入报告之前，它会评估发现、对置信度进行评分、检查引用，并运行报告前门控——标记不受支持的主张、逻辑漏洞和替代解释。 这两个推理平面都是可替换的：`REASON_BACKEND` 和 `DAIR_BACKEND` 均可接受 Claude API（默认）、任何 OpenAI 兼容的端点，或本地的 Foundation-Sec-8B-Reasoning 服务器，并且可以指向不同的模型。这些模型交换结构化的 `DIRECTIVES` 块，用于约束下一阶段的工具选择。分歧通过有上限的自我纠正循环（最多 3 次迭代）解决；未解决的项目将被报告为 `UNCERTAIN`，而不会被丢弃。 ### 执行流程 ``` case opened │ ├─ misc.start_execution_log ← trace log initialized ├─ [parallel] pre-plan triage ← ez.recmd_hive ×3 + vol.symbol_check + hash.verify_evidence_hash ├─ reason.hypothesize (case question) ← competing hypotheses, incl. ≥1 non-leading ├─ reason.plan ← prioritized Triage plan │ └─ DAIR loop ── repeats until next_phase = Report ───────────────┐ ├─ dair.dair_assess ← phase decision + priority_tools work order ├─ [tool batch — disk, memory, artifacts, network, …] │ (+ optional curiosity probes) │ └─ reason.hypothesize ← per suspicious artifact │ └─ dair.dair_assess (results) ──────────────────────────────┘ │ (before any CONFIRMED/LIKELY finding) ├─ reason.evaluate_finding / confidence_score / cite_check ├─ misc.record_finding ← gated, linked to source call_id │ (Report phase) ├─ reason.synthesize ← cross-finding consistency check ├─ reason.pre_report_check ← blocks until findings + attribution resolved ├─ misc.export_execution_log ← trace written to reports/ └─ misc.write_final_report ← gated final report write ``` 在整个调查过程中，每次工具调用、DAIR 调用、推理调用和已确认的发现都会写入实时的 JSON trace 日志中。Markdown 导出文件是人类可读的。 ## 前置条件 1. **SANS SIFT Workstation** — Ubuntu 22.04 x86-64，附带取证工具（Volatility 3, EZ Tools, Sleuth Kit, Plaso, YARA, bulk_extractor 等） - 下载：https://www.sans.org/tools/sift-workstation/ 2. **Protocol SIFT** — 安装 Claude Code 和取证技能手册 - 安装：https://github.com/teamdfir/protocol-sift 3. **Python 3.10+** 和 **dotnet** — 两者均包含在 SIFT Workstation 中 4. **推理后端** — **必填** TRUDI 使用两个独立配置的推理模型 — 对抗性审查器 (`REASON_BACKEND`) 和 DAIR 阶段控制器 (`DAIR_BACKEND`)。这是 TRUDI 工作原理的核心，而不是附加功能：没有它们，agent 将在无监督下运行，发现永远不会受到挑战或进行置信度评分，并且阶段控制将退回到静态路径。请在运行前配置好两者。它们采用相同的选项，可以指向相同或不同的模型： | 后端 | 配置 | |---------|--------| | `claude`（默认） | `ANTHROPIC_API_KEY=sk-ant-...` — 无需服务器 | | `openai-compat` | `REASON_URL` / `DAIR_URL` + `REASON_API_KEY` / `DAIR_API_KEY` | | Foundation-Sec（本地） | `…_BACKEND=openai-compat` + `…_URL=http://localhost:8000` | | Foundation-Sec（HF） | `…_BACKEND=openai-compat` + `…_URL=` + `…_API_KEY=hf_...` | 提交版本在 `claude` 上使用 Opus 运行两者（参见 [工作原理](#how-it-works)） — 最简单的设置就是添加一个 `ANTHROPIC_API_KEY` 即可。TRUDI 在未配置后端时也可以启动，但这**不是评估它的受支持方式**：推理和 DAIR 调用将被跳过，你看到的是一个被掏空的 agent，而不是 TRUDI。 ### 系统取证包 `install.sh` 会自动安装这些包（并在需要时启用 `universe` apt 组件）。在完整的 SIFT Workstation 上，大多数包已经存在；如果在较精简的系统上，或者安装程序记录了关于某个包的 `!` 警告，请手动安装它们： ``` sudo add-apt-repository -y universe # pst-utils / pff-tools / tcpxtract live here sudo apt-get update sudo apt-get install -y pff-tools pst-utils binwalk tcpxtract sleuthkit ewf-tools ``` | apt 软件包 | 二进制文件 | 需要它的 TRUDI 工具 | |-------------|----------|--------------------------| | `pff-tools` | `pffexport`, `pffinfo` | `misc.pff_export` (PST/OST 电子邮件提取) | | `pst-utils` | `readpst`, `lspst` | `misc.readpst_extract` (PST→mbox) — **不是** `libpst-utils`；该包不存在 | | `sleuthkit` | `fls`, `icat`, `istat`, `mmls`, `blkls`, `mactime`, `tsk_recover` | `tsk.*` | | `ewf-tools` | `ewfmount`, `ewfinfo`, `ewfverify` | `ewf.*`, `img.*` E01 挂载 | | `tcpxtract` | `tcpxtract` | `net.tcpxtract_streams` | | `binwalk` | `binwalk` | 固件 / 嵌入式文件雕刻 | | **chainsaw** (GitHub 发布版 `v2.10.2` → `/usr/local/bin`，非 apt) | `chainsaw` | `misc.chainsaw_hunt` (基于 EVTX 的 Sigma) — 可选；TRUDI 没有它也能运行 | 安装后验证：`for b in pffexport readpst fls ewfmount tcpxtract; do command -v "$b" || echo "MISSING: $b"; done` ## 安装说明 ``` git clone https://github.com/nebulae/trudi ~/trudi cd ~/trudi ./install.sh ``` `install.sh` 会执行以下操作： - 检查 `python3`、`dotnet` 和 `claude` CLI - 在 `~/.venv` 创建 Python venv 并安装所有依赖项 - 复制 `.env.example` → `.env`（编辑此文件以添加 API 密钥） - **备份**任何已存在的 `~/.claude/CLAUDE.md`（附带 UTC 时间戳），然后安装 TRUDI 编排器 - 注册 Claude Code hooks、斜杠命令和技能（hooks 直接从仓库运行 — 没有容易产生偏差的已部署副本） - 使用 `claude mcp add --scope global` 全局注册 TRUDI MCP server - 运行完整的测试套件（1,100+ 测试）作为冒烟检查 如果 `~/.claude/CLAUDE.md` 已经存在（例如来自 Protocol SIFT 的安装），备份将被写入 `~/.claude/CLAUDE.md..bak` — 原始文件绝不会在没有备份的情况下被覆盖。 ### API 密钥 编辑 `~/trudi/.env`。TRUDI 在没有任何密钥的情况下也能运行，但**缺少密钥会降低运行质量而不是直接中断** — 而且这种降级绝不是表面的： | 密钥 | 驱动 | 如果缺失 | |-----|--------|-----------| | `ANTHROPIC_API_KEY` | `reason.*` 审查器和 `dair.*` 控制器（当 `…_BACKEND=claude` 时） | **推理和 DAIR 调用将被跳过。** 发现永远不会受到质疑、进行置信度评分或引用检查；阶段控制将退回到静态路径。TRUDI 运行所特有的审计追踪和分析严谨性将荡然无存。 | | `VIRUSTOTAL_API_KEY` | `enrich.vt_lookup_*` | 哈希/IP/域名信誉查询返回 "unconfigured"；其他一切照常进行。 | | `ABUSEIPDB_API_KEY` | `enrich.abuseipdb_check` | IP 滥用评分被跳过；其他一切照常进行。 | ``` # IOC enrichment VIRUSTOTAL_API_KEY=your_key_here ABUSEIPDB_API_KEY=your_key_here # Reasoning backends — reviewer + DAIR director（两者均默认使用 claude） REASON_BACKEND=claude DAIR_BACKEND=claude ANTHROPIC_API_KEY=sk-ant-... # Claude API — used by both when backend=claude # Submission default：reasoning 和 DAIR 均使用 Opus REASON_MODEL=claude-opus-4-8 DAIR_MODEL=claude-opus-4-8 # 或者将任一 backend 指向 OpenAI-compatible / 本地 endpoint： # REASON_BACKEND=openai-compat # REASON_URL=https://api.openai.com/v1 # 或者 http://localhost:8000 用于本地 vLLM # REASON_API_KEY=sk-... # DAIR_BACKEND=openai-compat # DAIR_URL=http://localhost:8001 # 可能与 REASON_URL 不同 ``` **Foundation-Sec (openai-compat 后端，本地 vLLM)：** ``` pip install vllm vllm serve "fdtn-ai/Foundation-Sec-8B-Reasoning" \ --reasoning-parser minimax_m2 \ --quantization bitsandbytes --load-format bitsandbytes # for <24 GB VRAM # 然后设置：REASON_BACKEND=openai-compat, REASON_URL=http://localhost:8000 ``` ## 开启案件 ### 1. 创建案件目录 ``` cp -r ~/trudi/case-template ~/cases/ ``` ### 2. 编辑案件 CLAUDE.md 在 `~/cases//CLAUDE.md` 中填写证据路径、主机名和范围。这是唯一的手动步骤 — 其他一切都是自主的。 ``` ~/cases// ├── CLAUDE.md ← edit this ├── .claude/ │ └── settings.json ← MCP tool allowlist (pre-populated) ├── evidence/ ← place disk images and memory captures here ├── analysis/ ← intermediate artifacts (auto-created) ├── exports/ ← tool output: CSV, JSON, bodyfiles (auto-created) └── reports/ ← final report + trace log (auto-created) ``` ### 3. 放置证据 ``` cp /path/to/image.E01 ~/cases//evidence/ cp /path/to/memory.img ~/cases//evidence/ ``` ### 4. 在案件目录中打开 Claude Code ``` cd ~/cases/ claude ``` ### 5. 开始调查 ``` Investigate this case. Start with the pre-enumeration triage, then follow the plan. ``` TRUDI 将从那里开始自主运行。它不会在步骤之间请求确认。最终输出是位于 `reports/` 中的结构化报告，以及 JSON 和 Markdown 格式的完整执行追踪。 ## 实时监控与自主响应（实验性） 除了静态镜像调查之外，TRUDI 还可以通过 Velociraptor 监控实时端点并做出自主响应。这是 TRUDI 唯一对系统进行写入的模式，并且仅在证据边界之外通过单独的门控路径进行。 - `monitor.*` — 基线捕获、watcher 生命周期、警报抽取、每个调查的追踪 - `velo.*` — 只读的 Velociraptor API（客户端、工件收集、VQL） - `live.*` — 通过 SSH 进行只读的实时分类（进程、网络、持久化、服务、登录） - `respond.*` — **门控**的遏制措施（进程挂起/终止、网络阻断），通过结构化、类型验证的 SSH 路径执行 **自动保护**（默认开启）会自动执行*可逆且低风险*级别的遏制措施，并显示每个操作的回滚命令；任何破坏性操作（不可逆，或风险 ≥ 中等）都会暂停循环，直到操作员输入 `approve ACT-N`。自动执行与审批的边界是根据每个方案的 `risk`/`reversible` 元数据由服务器进行分类的 — agent 无法对其进行重新分类。 **端端体验：** [demo/live-monitoring/README.md](demo/live-monitoring/README.md) — 一个自包含的 Velociraptor + 受害者 Docker 栈，具备一键启动、预演的 Atomic Red Team 攻击，以及 TRUDI 循环（基线 → watcher → 警报抽取 → 自动保护，包括 `approve ACT-N` 流程）的完整演练。它由内置的 `/trudi-*` 斜杠命令（`/trudi-start-watcher`、`/trudi-watch-alerts`、`/trudi-check-alerts`、`/trudi-stop-watcher`、`/trudi-clear-case`）驱动，`install.sh` 会将这些命令安装到 `~/.claude/commands/`。如需单独了解只读 SSH 分类路径，请参阅 [docs/live-endpoint-testing.md](docs/live-endpoint-testing.md)。 ## 产出内容 | 文件 | 内容 | |------|----------| | `reports/_investigation_report.md` | 结构化的分析师报告 — 执行摘要、攻击时间线、带有置信度的发现、环境注意事项 | | `reports/_trace.md` | 人类可读的审计追踪 — 每次工具调用、推理调用和已确认的发现，附带 UTC 时间戳 | | `reports/_trace.json` | 机器可读的追踪 — 相同的数据，结构化以便于摄取 | | `analysis/_trace.json` | 实时追踪（在调查期间增量写入） | | `exports/` | 原始工具输出 — MFT CSV、EVTX 导出、预读取、注册表、amcache、shimcache、USN journal、netscan 等 | ## Trace 仪表板 每次调查都会写入实时的 JSON trace；内置仪表板会在其运行时于浏览器中渲染。启动一次，它就会为 `~/cases` 下的所有案件提供服务： ``` ./dashboard.sh # serves ~/cases on http://127.0.0.1:8765 ./dashboard.sh --port 9090 ./dashboard.sh --cases-root /data/cases ``` `install.sh` 还会向 `/usr/local/bin` 安装一个 `trudi-dashboard` 启动器。在案件开启时，TRUDI 会打印活动追踪的实时仪表板 URL，以便你实时观察调查的展开。 | 视图 | 展示 | |------|-------| | **Trace 查看器** | 每次工具调用、DAIR 调用、推理调用和发现的时间顺序流 — UTC 时间戳、参数和门控结果 | | **调查链** | 发现谱系链 — 每个发现都通过 `input_call_ids` 回溯到生成它的确切工具执行记录 | | **调查图谱** | 作为因果 DAG 的追踪 — 假设、工具运行和发现作为节点；谱系作为边 | **Trace 查看器** — 每次工具 / DAIR / 推理调用和发现，附带参数和门控结果：  **调查链** — 每个发现都通过 `input_call_ids` 回溯到生成它的确切工具执行记录：