WilBtc/find-evil-sleuth

## ✅ 黑客松提交合规性 每一项必交内容都映射到了确切的位置，以便评委一眼核验完整性。 | # | 必交项 | 位置 | |---|---------------|----------| | 1 | 公开代码仓库 | **本仓库** — https://github.com/WilBtc/find-evil-sleuth | | 2 | 开源许可证 (Apache-2.0) | [`LICENSE`](LICENSE) | | 3 | 包含设置说明的 README | 本文件 → [快速开始](#-quick-start) | | 4 | 在线部署 URL 或分步说明 | [快速开始](#-quick-start) + [持久化检查器 (SaaS)](#-persistent-inspector-saas) | | 5 | 功能与特性的文字描述 | [它是什么](#what-it-is) + [`submission/devpost-form.md`](submission/devpost-form.md) | | 6 | 演示视频 (≤5 分钟，含语音解说，展示自我纠错能力) | [`submission/demo.mp4`](submission/demo.mp4) · 托管 URL 见 [`submission/devpost-form.md`](submission/devpost-form.md) | | 7 | 架构图 | [`docs/architecture.svg`](docs/architecture.svg) (渲染于 [架构](#architecture)) | | 8 | 证据数据集文档 | [`docs/EVIDENCE.md`](docs/EVIDENCE.md) | | 9 | 准确率报告 | [`docs/ACCURACY.md`](docs/ACCURACY.md) | | 10 | Agent 执行日志 | [`submission/execution-log.ndjson`](submission/execution-log.ndjson) · 实时日志见 [`logs/`](logs/) | ## 它是什么 **find-evil-sleuth** 能够自主运行完整的数字取证与事件响应调查 —— 从原始磁盘、内存和网络证据，到结构化且附带完整引用的报告 —— 全程无需任何人工介入。 三个专家级子 Agent（磁盘、内存、网络）驱动了完整的 SANS SIFT 工具链。每个子 Agent 都会在 Postgres 17 底座中生成 `findings` 记录，每一条记录都包含 **BLAKE3 哈希的 artifact 链**、一条 **Merkle 链式审计追踪**，以及一个 **Apache AGE 攻击图**节点。验证器子 Agent 会针对原始证据重新执行*每一个*声明；IR 叙述器子 Agent 则会将已确认的发现转化为报告，其中每一句话都带有 `[F-NNN]` 引用，以追溯至其来源。 ### 与众不同之处 大多数智能体 DFIR 工具依赖提示词工程将模型限制在界限内。而 find-evil-sleuth 让违规操作在**结构上变得不可能**： - 🔒 **护栏是架构，而非指令。** 一个 Bash `PreToolUse` 钩子会对任何非 `./bin/sb`（broker）或 `./bin/es`（evidence-store）的命令执行退出码为 1 的终止操作 —— 这是在 shell 接触到命令*之前*强制执行的。Agent 根本无法直接运行 `strings`、`grep` 或 `tshark`。 - 🦀 **Rust broker 负责协调每一次工具调用。** 它使用 `pg_jsonschema` 验证参数，在带有自定义 **seccomp** 配置文件和**只读**证据挂载的 **rootless podman 容器**中运行每个取证二进制文件，并将 stdout/stderr 直接流式传输到 Postgres 中。 - 🧠 **通过重新执行来限制幻觉。** 验证器会使用完全相同的参数重新运行每个发现对应的原始工具调用，并比对输出。任何无法复现的内容都会被标记为 `refuted` 并从报告中剔除。 - 🗄️ **Postgres 是 Agent 的大脑。** 每次工具调用都是一条记录。每个 artifact 都通过内容寻址。`./bin/es cite F-001` 会在 100 毫秒内返回完整的溯源链 —— 工具调用、参数、退出码、stderr、BLAKE3 哈希、artifact 内容。评委可以在演示期间运行实时的 `SELECT` 查询。 ## 🏆 评审标准 → 设计 | # | 标准 | 我们的应对方案 | |---|-----------|-------------------| | 1 | **自主执行质量** | ADW 外部循环 + Best-of-N 叙述器 (Opus 评判)；基于单个发现的事件驱动式重新验证 (数据库触发器 + `LISTEN/NOTIFY`，无时钟，无人工输入)；自我纠错限制为每个发现最多重试 3 次 | | 2 | **IR 准确性** | 验证器通过 broker 重新运行每个声明；`validation_status ∈ {confirmed, refuted, inconclusive, drift}`；pgvector 余弦去重合并重复的 IOC。详见 [`docs/ACCURACY.md`](docs/ACCURACY.md) | | 3 | **广度 × 深度** | 针对完整 SIFT 工具链的三个深度专家：Sleuth Kit + Plaso (磁盘)，Volatility 3 (内存)，tshark + Zeek + Suricata 配合 ET-Open 规则 (网络) | | 4 | **约束实现** | 架构级护栏：Bash 钩子 + Rust broker + rootless podman + 自定义 seccomp + 只读挂载 + `pg_jsonschema` —— 结构性的，而非系统提示词 | | 5 | **审计追踪** | BLAKE3 内容寻址 artifact，Merkle 链式 `tool_calls` hypertable，`findings.tool_call_id` 外键；`es cite F-NNN` 在 <100 ms 内返回完整追踪记录；pgaudit 记录每一次 `SELECT` | | 6 | **可用性与文档** | 单命令快速启动；持久化浏览器检查器；架构 SVG；每个报告段落中包含 `[F-NNN]` 引用 | ## 🚀 快速开始 ``` # 1. 克隆并启动 Postgres substrate git clone https://github.com/WilBtc/find-evil-sleuth cd find-evil-sleuth docker compose -f docker/compose.yaml up -d # 2. 获取 SANS evidence case（从 digitalcorpora.org 下载） ./scripts/fetch-evidence.sh ./cases/lone-wolf/ # 3. 运行完整调查（triage → specialists → validator → narrator） ./scripts/investigate.sh ./cases/lone-wolf/ # 4. 引用任何发现 — 完整 provenance chain 在 <100 ms 内 ./bin/es cite F-001 ``` `investigate.sh` 驱动完整的 ADW pipeline：分类阶段对证据进行分流，三个专家 Agent 并行运行，验证器重新执行每一个声明，最后由叙述器将 `report.md` 输出到案例目录中。在 8 核 / 32 GB 机器上的典型挂钟时间：处理完整的磁盘+内存+网络案例需 **20–40 分钟**；证据下载是唯一耗时的步骤。 一个快速的端到端冒烟测试（底座已运行）可在几秒钟内完成： ``` ./scripts/smoke-test.sh --skip-compose # clone-to-`cite` sanity check ``` ## 🖥️ 持久化检查器 (SaaS) `bin/sleuth-saas` 是一个编译好的 Rust Web 应用 —— 一个用于浏览任何已完成调查的持久化浏览器 UI。无需 Python，无需 notebook，也不需要终端。 ``` ./scripts/saas.sh up # starts Postgres if needed, launches inspector on :8932 ``` 打开 **http://127.0.0.1:8932/**，即可在不到一秒的时间内浏览任何案例。 | 页面 | URL | 显示内容 | |--------|-----|--------------| | 案例列表 | `/` | 所有案例，包含证据数量和最新活动徽章 | | 发现表格 | `/case//findings` | 每一项发现 —— 置信度、validation_status、MITRE 标签、深入详情 | | 发现详情 | `/finding/` | 工具调用、精确参数、stdout 哈希、artifact 内容、Merkle 根 | | 审计链 | `/case//audit` | Merkle 链式 `tool_calls`，带有实时验证徽章（绿色 = 无篡改） | | 攻击图 | `/case//graph` | 使用 vis-network 渲染的 Apache AGE 节点 —— 一眼洞察横向移动 | 截图：[`docs/saas-screenshots/`](docs/saas-screenshots/) · 使用 `./scripts/saas.sh down` 停止。 ## 🧰 SIFT 集成 本次黑客松是围绕 **SANS SIFT Workstation** 构建的，find-evil-sleuth 在两个层面上集成了 SIFT 工具链： - **单工具沙箱镜像** —— 每个取证二进制文件（Sleuth Kit, Volatility 3, Plaso, tshark, Zeek, Suricata, YARA, bulk_extractor）都运行在各自独立的、最小化的 rootless podman 镜像中，并注册在 broker 的 `tool_specs` 表中。这是生产环境的路径：严格的沙箱隔离、快速启动、每次工具调用对应一个容器。 - **完整的 SIFT 发行版** —— `find-evil-sleuth/sift-full` 是完整且**最新**的 SANS SIFT Workstation（**2026-04-22**，Ubuntu 24.04，约 20 GB），通过 libguestfs (`virt-tar-out`) 从官方 SANS OVA 中提取并导入为容器。它被注册为 `mmls-sift-full` broker 工具，并可通过 [`scripts/fetch-sift.sh`](scripts/fetch-sift.sh) 复现。已验证：Sleuth Kit 4.11.1, Volatility 3, Plaso/log2timeline 20260119。维护中的 `digitalsleuth/sift-remnux` 打包包作为 `sift-full:remnux-2024.10.19` 的后备标签保留。 每一个 SIFT 工具**只能**通过 broker 访问 —— 经过验证、置于沙箱并记录在案。没有任何 Agent 会直接调用取证二进制文件。 ## 🏗️ 架构  红色虚线边界标志着**架构级护栏**：`PreToolUse` 钩子会拦截所有不匹配 `./bin/sb` 或 `./bin/es` 的命令。Broker 负责验证、沙箱化与记录。Evidence-store 负责哈希计算、链接与暴露。没有任何 Agent 会直接触碰主机 shell。 ``` ADW driver (adws/investigate.py) │ ├── PreToolUse hook ──► blocks anything not ./bin/sb or ./bin/es │ ├── ./bin/sb exec --tool --args │ │ validates args (pg_jsonschema) │ │ podman run --read-only --security-opt seccomp=sleuth.json │ └──► tool container (sleuthkit / vol3 / tshark / zeek / sift-full / …) │ └── ./bin/es cite|record-finding|search|graph └──► Postgres 17 pgvector · AGE · TimescaleDB · pg_cron · pgaudit · … ``` 底座是 **Postgres 17**，配备了 11 个扩展：pgvector（语义发现搜索）、Apache AGE（攻击图）、TimescaleDB（工具调用时间序列）、pg_cron（定时验证扫描）、pg_partman、pg_trgm、pgcrypto、pg_stat_statements、pgaudit（防篡改查询日志）、pg_jsonschema（参数验证）、pg_graphql。 ## 📐 设计文档 分阶段的设计原理位于 [`plans/`](plans/)： | 文件 | 内容 | |------|----------| | [`00-master-plan.md`](plans/00-master-plan.md) | 获胜条件、架构概述、分阶段构建计划 | | [`01-postgres-substrate.md`](plans/01-postgres-substrate.md) | 完整 schema、每个扩展的作用、pg_cron 任务、AGE 图、pgvector 策略 | | [`02-broker-design.md`](plans/02-broker-design.md) | 工具规范格式、白名单、podman 调用、seccomp 配置 | | [`03-evidence-store-design.md`](plans/03-evidence-store-design.md) | Merkle 链、BLAKE3 布局、`cite` 语义、搜索/图 endpoint | | [`04-subagents-and-skills.md`](plans/04-subagents-and-skills.md) | 每个 Agent 的工具、系统提示词、技能主体、成功/失败形态 | | [`05-adw-outloop.md`](plans/05-adw-outloop.md) | investigate.py 状态机、重试预算、并发上限、幂等性 | | [`06-self-correction-demos.md`](plans/06-self-correction-demos.md) | 自我纠错演示的精确复现步骤 | | [`07-submission-deliverables.md`](plans/07-submission-deliverables.md) | 提交清单、README 结构、准确率报告模板 | | [`08-risk-and-rollback.md`](plans/08-risk-and-rollback.md) | 包含回滚计划和熔断机制的完整风险登记表 | ## 📄 许可证 Apache-2.0 — 详见 [`LICENSE`](LICENSE)。 ## 📚 引用 **证据数据集：** 通过 [digitalcorpora.org](https://digitalcorpora.org/) 和 SANS 黑客松数据集仓库分发的 SANS DFIR 场景 —— 详见 [`docs/EVIDENCE.md`](

标签：Metaprompt, PostgreSQL, Rust, 可视化界面, 子域名变形, 数字取证, 网络流量审计, 自动化分析, 自动化脚本, 请求拦截, 跨站脚本, 逆向工具, 防篡改