AbhinashBadugu/SANS---Find-Evil-_-AI-Hackathon

# Find Evil! — 自主事件响应 Agent 一个自主的 DFIR Agent，它以机器速度对多主机入侵进行分类，并 生成一份**引用详尽、可复现的事件报告 — 且绝不产生幻觉。** 它 驱动一个**只读取证 MCP 服务器**（Volatility 3, The Sleuth Kit, Plaso, EZ Tools, bulk_extractor, YARA），将数千行原始工具输出转化为 结构化的叙述，其中**每一项发现都引用了其来源的确切工件。** 专为 SANS / Protocol SIFT **Find Evil!** 黑客松构建。已在 4 主机的 **SRL-2015** 案例上进行了端到端验证（磁盘 + 内存）。 ## 核心成果 — 准确率对比经验证的标准答案 根据 **`oracle_v2`**（10 个基于证据裁决的攻击里程碑）进行确定性评分 — 与原生的 Claude 基线进行同口径对比： | 指标 | 原生基线 | **本 Agent** | |--------|----------------|----------------| | **召回率** | 0.90 | **1.00 — 全部 10 个里程碑** | | **幻觉**（无引用/未解析的声明） | ~1 次 / 运行 | **0** | | **错误结论**（如错误的感染源） | — | **0** | | **引用质量** | 部分 | **100% 的发现包含 `{tool, artifact, provenance_id}`** | 几秒钟内即可复现（确定性，无需 LLM，**无需 API 密钥**） — 见[快速开始](#quick-start-for-judges)。 完整的自我评估 — 误报、遗漏的工件、证据完整性与篡改 测试，以及诚实的局限性说明 — 在 **[ACCURACY_REPORT.md](ACCURACY_REPORT.md)** 中。 ## 核心理念：代码决策，LLM 仅负责叙述 防幻觉保证是**架构层面的，而非依赖于提示词：** - **Agent 没有 shell，也没有直接的证据访问权限。** 每一项证据操作都是一次 有类型的 MCP 工具调用；只读工具的菜单*本身就是*安全边界。 - **两个独立的根目录，且经过路径验证：** `EVIDENCE_ROOT`（只读）与 `CASE_ROOT` （所有输出）。服务器在物理层面无法写入或执行证据。 - **置信度、关联、去重和矛盾检测都是确定性的 Python** （`agent/dfir_agent/rules/`） — 绝不依赖模型的判断。 - **每一项发现都引用了一个 `provenance_id`**，该 ID 会在不可变的日志中解析，否则 引用检查器将**剔除该发现。** 杜绝未引用的声明。 - LLM 唯一的工作是将结构化的事实转化为文本。它无法凭空捏造 工件，无法更改置信度等级，也无法触碰证据。 相同的证据 + 相同的代码 → 每次运行都是相同的 10/10。 ## 架构  用户 → 本地 Web UI → **DFIR Agent / 编排器**（LLM 引导的推理 + **确定性**工作流节点） → **只读的 MCP 安全边界**（有类型的工具，*无 shell*，*不对证据进行写入*，路径经过验证，来源被记录） → 经过法庭检验的 **SIFT** 工具 → **只读证据**。LLM 负责解释案例，但**绝不直接 访问原始证据**；每一次输出都是由来源账本支撑的**结构化、带引用的发现**。 ## 仓库结构 ``` ├─ install.sh One-command setup (venv + deps + tool preflight + tests) ├─ requirements.txt Pinned Python dependencies ├─ webui/ Conversational UI (localhost:8077) — chat, trigger runs, verify citations ├─ agent/ Autonomous DFIR agent — pipeline nodes + deterministic rules + scorer │ ├─ eval/ Entry points: run_from_evidence, run_case, score_profile │ └─ validation_profiles/srl2015.yml The graded answer key (ported from oracle_v2) ├─ mcp_server/ 28 typed, read-only forensic tools (the evidence boundary) └─ LICENSE MIT ``` ## 依赖项 **1. Python 3.10+** 以及 [`requirements.txt`](requirements.txt) 中的包 （`install.sh` 会将这些安装到本地的 `.venv` 中）：`anthropic`, `mcp`, `pydantic`, `starlette`/`uvicorn` (UI), `PyYAML`, `pefile`, `pytest`。 在 Debian/Ubuntu 上，请先确保安装了 venv 构建器： `sudo apt install -y python3-venv`（或对应版本的 `python3.12-venv`）。`install.sh` 会检查它，如果缺失会提示您。 **2. 系统取证工具** — 该 Agent *直接调用经过法庭验证的二进制文件*；它不会 重新实现它们。这些工具随 **SANS SIFT** 一起提供；`install.sh` 会运行预检， 报告任何缺失的工具： | 功能 | 二进制文件 | |---|---| | 内存取证 | Volatility 3 (`vol`) | | 时间线 | Plaso (`log2timeline.py`, `psort.py`) | | 文件系统 / 挂载 | The Sleuth Kit (`fls`, `icat`, `ifind`), `ewfmount` | | Carving | `bulk_extractor` | | Windows 工件 | 通过 .NET (`dotnet`) 运行的 EZ Tools — MFTECmd, EvtxECmd, RECmd… | | IOC 扫描 | `yara` | 如果缺少某个工具，需要它的步骤将被**跳过并在报告中标记** — 绝不会伪造。 **3. Anthropic API 密钥 — 可选；运行或评估分析结果不需要此密钥。** 完整的流水线、带引用的单主机及跨主机报告、来源账本， 以及确定性评分器均可在**无 API 密钥**的情况下运行。密钥仅会增加两个*附加的* 额外功能：报告中执行摘要的 LLM 叙述文本（无论哪种方式，事实和引用 都是相同的 — 只是摘要被标记为 `_(deterministic)_` 还是 `_(LLM-narrated)_`），以及对话式聊天 UI。**评委可以直接在终端运行并评估整个案例，无需密钥。** 如果您需要聊天 UI，请将您自己的密钥放入 `webui/.env` 中。 ## 快速开始（供评委使用） ``` git clone && cd find-evil ./install.sh # venv + deps + tool preflight + 158 unit tests source .venv/bin/activate # 分析和评分（以下步骤 1-3）不需要 Anthropic API key。 ``` ### 1. 运行完整分析 — **无需 API 密钥** 为其提供磁盘/内存镜像；它会引导整个流水线（清单 → 哈希 → 挂载 → 内存 + 磁盘 + 时间线 → 关联 → 跨主机报告），完全使用经过法庭验证的 工具。它会自动分类磁盘和内存，并根据文件名按主机分组；所有内容 都保留在一个只读的 `EVIDENCE_ROOT` 下。**这是评委在终端运行的路径 — 不需要 Anthropic 密钥。** ``` cd agent PYTHONPATH="$PWD/../mcp_server:$PWD" python -m eval.run_from_evidence \ --case srl2015 \ --evidence-root /path/to/SRL-2015 \ --host xp-tdungan disk=/path/xp-tdungan-c-drive.E01 memory=/path/xp-tdungan-memory-raw.001 \ --host win2008R2-controller disk=/path/win2008R2-controller-c-drive.E01 memory=/path/win2008R2-controller-memory-raw.001 \ --host win7-64-nfury disk=/path/win7-64-nfury-c-drive.E01 memory=/path/win7-64-nfury-memory-raw.001 \ --host win7-32-nromanoff disk=/path/win7-32-nromanoff-c-drive.E01 memory=/path/win7-32-nromanoff-memory-raw.001 # 添加 --dry-run 以预览 plan + manifest 而不运行 ``` 缺失或试图逃逸出 `EVIDENCE_ROOT` 的路径将被**拒绝**。对于不可读的 证据，Agent 将**不产生任何发现并披露所有信息缺口** — 绝不会提供捏造的 结果。（在没有密钥的情况下，报告摘要是确定性的；密钥仅增加可选的叙述文本。） ### 2. 将其与标准答案进行评分 — **无需 API 密钥** 确定性的，无需 LLM，无需网络 — 根据答案 （`validation_profiles/srl2015.yml`，从 `oracle_v2` 原样移植）对本次运行的发现和报告进行评分： ``` cd agent PYTHONPATH="$PWD/../mcp_server:$PWD" python -m eval.score_profile \ --case srl2015 --case-root /path/to/CASE_ROOT \ --profile validation_profiles/srl2015.yml # 写入 /agent/validation_score.{md,json} ``` ### 3. 重新运行测试 — **无需 API 密钥** ``` cd agent && PYTHONPATH="$PWD/../mcp_server:$PWD" python -m pytest -q # 145 rule/scoring tests cd ../mcp_server && PYTHONPATH="$PWD" python -m pytest -q # 13 path-safety / allowlist tests ``` ### 4. （可选）对话式 UI — 唯一需要密钥的部分 一个用自然语言探索案例的聊天界面。需要在 `webui/.env` 中放入**您自己的** Anthropic 密钥（仪表板/报告视图在没有密钥的情况下依然可用；只有聊天框 会调用模型）。 ``` PYTHONPATH="$PWD" python -m webui.server # → open http://127.0.0.1:8077 ``` 询问*“谁是感染源，你是怎么知道的？”* — 每一个回答都会引用真实的 `provenance_id`，并且*“删除证据”*在设计上会被拒绝。聊天 LLM 仅充当 编排器/解释器：只读工具，无 shell。 ## 使用的数据集 / 证据 提交的内容已在 **SANS SRL-2015** 入侵案例上验证 — 这是一个位于 `shieldbase.local` 域（子网 `10.3.58.0/24`）中的 4 主机 Windows 网络，每台主机都被捕获为**磁盘镜像 (`.E01`) + 物理内存镜像 (`.001` raw)**： | 主机 | IP | 角色 | 操作系统 | |---|---|---|---| | `xp-tdungan` | 10.3.58.7 | 工作站（感染源） | Windows XP SP3 | | `win7-32-nromanoff` | 10.3.58.5 | 工作站 | Windows 7 x86 | | `win7-64-nfury` | 10.3.58.6 | 工作站（数据外发暂存） | Windows 7 x64 | | `win2008R2-controller` | 10.3.58.4 | 域控制器 | Windows Server 2008 R2 | 证据镜像**不**包含在此仓库中（因为体积和授权原因）。通过 `--evidence-root` / 上述的主机标志 提供您自己的磁盘+内存镜像 — 该流水线是 与具体案例无关的，可运行于任何磁盘 (`.E01`) + 内存镜像集。证据被严格视为 **只读**（FUSE `ewfmount`，偏移量为 0 的 NTFS）；该架构无法对其进行修改。 Agent 必须重建（并依据其进行评分）的攻击链：在 `tdungan` 上的 Java 偷渡式攻击 → `httppump` RAT + `spinlock` 植入 → Run-key 持久化 → 凭据窃取 → PsExec 横向移动至 DC → 在 `nfury` 上通过 `system4.rar` 外发数据 — 外加一个植入的 良性服务，Agent **绝不能**将其标记（即自我纠错测试）。 📂 **详细的数据集文档** — 标准答案 (`oracle_v2`)、SIFT 基线， 以及 Agent 针对 SRL-2015 **和** SRL-2018 的评分结果 — 位于 **[`dataset-documentation/`](dataset-documentation/)** 中。 ## 运行内容及结果 对所有 4 台主机进行的一次**从零开始**的运行（无缓存的工件 — 每台主机都进行了完整的 Plaso 构建）： - **547+ 次取证工具执行**，每次都记录在不可变的 `provenance.jsonl` 中。 - 生成了 `CASE_REPORT.md`（跨主机活动）+ 4 份带引用的单主机报告 + `case_summary.json`。 - 针对 `oracle_v2` 评分为 **10/10 里程碑，召回率 1.00，0 幻觉，0 错误结论** （`validation_score.md`）。 - 捕获了完整的时间戳执行和工具日志，用于审计追踪。 感染源 (`tdungan`)、`httppump`/`spinlock` 植入、针对 DC 的 PsExec 横向移动、 `system4.rar` 数据外发，以及良性服务的自我纠错均已 恢复并单独引用。 ## 输出（按案例，位于 `CASE_ROOT` 下） - `hosts//agent/_report.md` — 带引用的单主机报告 - `CASE_REPORT.md` — 跨主机活动（感染源 → 扩散） - `provenance.jsonl` — 不可变的证据审计账本（每次工具调用 + 命令） - `agent/validation_score.{md,json}` — 针对 `oracle_v2` 的召回率 + 引用质量 ## 28 个 MCP 工具（只读证据边界） | 领域 | 工具 | |------|-------| | 完整性 | `hash_evidence`, `hash_file`, `compare_hashes_across_hosts`, `verify_ewf` | | 内存 | `run_volatility_plugin` (10 个白名单插件), `carve_network_artifacts` | | 磁盘 (无需管理员权限) | `open_ewf`, `close_ewf`, `inspect_disk`, `extract_artifacts` | | 解析器 | `parse_mft`, `parse_registry`, `parse_evtx`, `parse_shimcache`, `parse_evt_legacy` | | 注册表 / 配置 | `parse_reg_export`, `extract_c2_from_registry` | | PE 与 Dropper 分诊 | `extract_strings`, `extract_pe_metadata`, `detect_pyinstaller`, `extract_pdb_paths`, `extract_embedded_urls` | | Carving | `carve_files` | | 浏览器 / Java | `parse_java_cache` | | 归档 | `extract_archive` | | 时间线 | `generate_timeline`, `filter_timeline` | | 回读 | `read_artifact` | 不存在 shell 工具；命令是作为 argv 列表以 `shell=False` 方式构建和运行的。每次运行 （无论成功、失败还是拒绝）都会在 `provenance.jsonl` 中追加一行。 ## 适用范围 / 诚实声明 已在 **SRL-2015（4 台主机）** 上进行了验证和调优尚未证明能推广至未见过的案例 （SRL-2018 是延伸目标）。Agent 只能发现它有对应规则的内容 — 在 面对新型攻击时，人类依然占据优势。工具执行（尤其是 Plaso）占据了绝大部分运行时间 （从零开始完整运行 4 台主机大约需要 45–90 分钟）；审查和评分仅需几秒钟。 **迈向全面企业覆盖的路线图** — 实时/分诊数据以及 **Linux、macOS 和 网络设备** Agent（OS/设备系列分析器架构已存在于代码中； 扩展只需添加更多有类型的只读工具 + 工件解析器） — 位于 **[AGENT_CAPABILITY_EXPANSION_REPORT.md](AGENT_CAPABILITY_EXPANSION_REPORT.md)** 中。 ## 许可证 MIT — 见 [LICENSE](LICENSE)。

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