codeforcode111/findevil

# FinDevil **证据契约自治 IR Agent —— 在结构上无法说谎的 agent** ## 什么是 FinDevil？ FinDevil 是一款**自治事件响应 agent**，能够在没有人工干预的情况下对受损的 Windows 端点进行推理。它将 Claude Code（规划和推理引擎）连接到在网络隔离的 Docker 容器中运行的 SIFT Workstation 取证工具，并通过 Model Context Protocol (MCP) 将它们桥接起来。 其核心差异化优势不在于速度或覆盖率，而在于**通过证据契约实现架构级的幻觉预防**。agent 所做的每一个声明都必须附有对原始证据（EVTX 记录、注册表键、内存页、文件系统条目）的引用。MCP 服务器的 Contract Compiler 会拒绝任何无法追溯到经过哈希验证的来源的发现。该 agent 在结构上就无法做出它未观察到的断言。 ## 架构 ``` graph TD CC["Claude Code\n(Planning + Reasoning)"] MCP["Investigation Runtime MCP Server\n(Python / FastMCP)"] EV["Evidence Vault\n(read-only · hash integrity)"] TG["Tool Gateway\n(Docker SIFT exec + security)"] COMP["Contract Compiler\n(reject uncited claims)"] SCE["Self-Correction Engine\n(auto-downgrade)"] AL["Audit Ledger\n(hash-chained JSONL)"] SIFT["SIFT Docker Container\n(network_mode: none)"] CC <-->|MCP Protocol| MCP MCP --- EV MCP --- TG MCP --- COMP MCP --- SCE MCP --- AL TG <-->|docker exec| SIFT ``` ### 数据流 1. Claude Code 接收案情简报并调用 MCP 工具以形成调查计划。 2. **Tool Gateway** 将每次工具调用转换为针对 SIFT 容器的 `docker exec` 命令（Hayabusa、Volatility、Sleuth Kit、Plaso、Zimmerman tools、YARA）。 3. 原始输出被摄取到 **Evidence Vault** 中，该模块会计算 SHA-256 哈希值并将证据以只读方式存储。 4. Claude Code 起草一项发现。**Contract Compiler** 会检查每个断言是否包含 vault 引用；未引用的声明在离开 MCP 边界之前会被拒绝。 5. **Self-Correction Engine** 将新证据与之前的发现进行比较，并在必须降低置信度时发出更正。 6. 每一个动作 —— 工具调用、证据摄取、发现、更正 —— 都会作为哈希链式的 JSONL 条目追加到 **Audit Ledger** 中。 ## 核心功能 ### 1. Self-Correction Engine（3 种更正类型） 该 agent 不仅仅是追加发现；它还会重新审视它们。系统会自动执行三种更正类别： | 类型 | 触发条件 | 效果 | |---|---|---| | `DOWNGRADE` | 出现矛盾的证据 | 降低置信度；标记先前的条目 | | `RETRACT` | 发现在重新评估契约后无法成立 | 从实时报告中移除；保留 ledger 条目 | | `AMEND` | 证据的范围扩大 | 更新发现；记录差异 | ### 2. 证据契约（结构性反幻觉） 每个 `Finding` 对象都是一个 Pydantic 模型，该模型要求包含一个或多个 `EvidenceRef` 对象，通过哈希值和字节偏移量将其链接到 vault 证据。Contract Compiler 在写入时强制执行此操作 —— 不是作为提示指令，而是作为 Python 类型约束。提示注入攻击无法绕过它。 ### 3. Windows 端点深度 FinDevil 针对各类 Windows 证据内置了全套 SIFT 工具链的封装： | 证据类型 | 工具 | |---|---| | EVTX 事件日志 | Hayabusa（Sigma 规则）、原生 EVTX 解析器 | | 注册表配置单元 | Zimmerman RECmd、Registry Explorer | | 内存映像 | Volatility 3（pslist、netscan、malfind、cmdline） | | 文件系统 / 时间线 | Sleuth Kit、Plaso / log2timeline | | 横向移动 / YARA | 自定义 YARA 规则集、hayabusa 横向移动 profile | ### 4. 架构级安全约束 安全性并非通过系统提示指令来强制执行，而是通过 runtime 强制执行： - SIFT 容器以 `network_mode: none` 模式运行 —— 没有数据外泄路径。 - 证据以只读方式挂载；agent 可以读取证据但无法修改它们。 - Tool Gateway 维护着一份允许执行的二进制文件注册表；无法执行任意 shell 命令。 - Evidence Vault 仅支持追加；如果在摄取后篡改了任何证据，哈希验证将会失败。 ### 5. 哈希链防篡改审计追踪 Audit Ledger 将每个事件追加为一条 JSONL 记录，其中每个条目都包含 `prev_hash` —— 即上一个条目的 SHA-256 哈希值。从创世块开始重放该链条，可以验证没有任何条目被悄无声息地插入、删除或修改。`findevil trace` CLI 命令可以验证并美观地打印出特定案例的完整链条。 ### 6. 面向操作员和审查员的 CLI 工具 ``` findevil investigate # run autonomous investigation findevil trace # replay and validate audit chain findevil bench # batch-scan EVTX files, emit detections findevil doctor # check Docker/SIFT/MCP health findevil report # render HTML/Markdown report with citations ``` ## 快速开始 ### 前置条件 - Docker（Engine 24+） - 支持 MCP 的 Claude Code - Python 3.12+ ### 1. 启动 SIFT 容器 ``` git clone https://github.com/findevil/findevil cd findevil docker compose up -d ``` SIFT 容器根据 `Dockerfile.sift` 构建，并将 `./cases/real_evidence` 以只读方式挂载到容器内的 `/evidence` 路径。不授予任何网络访问权限。 ### 2. 安装 Python 包 ``` pip install -e . ``` ### 3. 配置 Claude Code MCP 将 FinDevil MCP 服务器添加到您的 Claude Code 配置中： ``` { "mcpServers": { "findevil": { "command": "python", "args": ["-m", "findevil.server"], "env": { "FINDEVIL_CASE_DIR": "/absolute/path/to/cases" } } } } ``` ### 4. 运行调查 ``` # 将 Windows artifacts（EVTX、memory image、registry hives）放置在 cases/real_evidence/ 中 findevil investigate cases/real_evidence --case-id demo-001 ``` 或者直接询问 Claude Code： ## 试一试（面向审查员） 该代码库附带了一个位于 `cases/` 目录下的独立测试语料库和一个基准测试框架。要复现已发布的测试结果，请执行： ``` # 1. 验证环境是否正常 findevil doctor # 2. 运行完整的测试套件 pytest tests/ -v # 3. 批量扫描包含的 EVTX 语料库并统计检测结果 findevil bench cases/evtx_samples/ --output bench_results.jsonl # 4. 运行完整的演示调查 findevil investigate cases/real_evidence/ --case-id judge-run-01 # 5. 验证 audit chain（证明未被篡改） findevil trace judge-run-01 # 6. 渲染带有证据引用的最终报告 findevil report judge-run-01 --format markdown ``` 第 3 步的预期输出为：`37,732 detections across 877 EVTX files`（跨 877 个 EVTX 文件检测到 37,732 次）。 要观察反幻觉系统的实际运行情况，请尝试使用伪造的证据哈希调用 MCP 工具 `submit_finding` —— Contract Compiler 会在该发现被记录之前，以 `ContractViolation` 错误拒绝它。 ## 测试结果 | 指标 | 数值 | |---|---| | 测试套件 | 跨 9 个模块的 55 个测试 | | 进行基准测试的 EVTX 文件 | 877 | | 总检测数 | 37,732 | | 捕获的契约违规 | 100% 拦截了注入的伪造内容 | | 审计链完整性 | 在所有测试用例上均已验证 | 测试模块包括：`test_vault`、`test_compiler`、`test_correction`、`test_ledger`、`test_executor`、`test_registry`、`test_models`、`test_cli`、`test_e2e`。 ## 技术栈 | 层级 | 技术 | |---|---| | 推理引擎 | Claude Code（通过 Anthropic API 使用 claude-sonnet-4-x） | | Agent 与工具桥接层 | Model Context Protocol (MCP) | | MCP 服务器框架 | FastMCP (Python) | | 数据模型 / 验证 | Pydantic v2 | | 取证平台 | SIFT Workstation (Docker) | | EVTX / Sigma 检测 | Hayabusa | | 注册表分析 | Zimmerman tools (RECmd) | | 内存取证 | Volatility 3 | | 时间线 / 文件系统 | Plaso / log2timeline、Sleuth Kit | | 恶意软件扫描 | YARA | | 容器隔离 | Docker（`network_mode: none`，只读挂载） | | CLI | Click | | 报告模板 | Jinja2 | ## 项目结构 ``` findevil/ ├── src/findevil/ │ ├── server.py # FastMCP server — MCP entry point │ ├── cli.py # Click CLI (investigate / trace / bench / doctor / report) │ ├── vault/ # Evidence Vault — read-only, SHA-256 integrity │ ├── contracts/ # Contract Compiler + Finding/EvidenceRef models │ ├── correction/ # Self-Correction Engine (DOWNGRADE / RETRACT / AMEND) │ ├── audit/ # Hash-chained Audit Ledger (JSONL) │ └── tools/ # Tool wrappers: hayabusa, volatility, sleuthkit, plaso, │ # zimmerman, yara_scanner, executor, registry ├── tests/ # 55-test suite ├── cases/ # Evidence and EVTX sample corpus ├── docker-compose.yml # SIFT container definition └── Dockerfile.sift # SIFT Workstation image ``` ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。 ## 致谢 - **SANS Institute** —— FIND EVIL! 黑客马拉松及 SIFT Workstation 平台 - **DFIR.training / Eric Zimmerman** —— Zimmerman 取证工具 - **Yamato Security** —— Hayabusa EVTX 分析引擎 - **EVTX-ATTACK-SAMPLES** —— 用于基准测试的公开 EVTX 语料库 - **Volatility Foundation** —— Volatility 3 内存取证框架 - **Anthropic** —— Claude Code 及 Model Context Protocol

标签：AI智能体, AlienVault OTX, DLL 劫持, MCP, 大语言模型, 库, 应急响应, 数字取证, 自动化脚本, 请求拦截, 逆向工具