WooYoungSang/warvis-findEvil
GitHub: WooYoungSang/warvis-findEvil
一款基于 Go 编排器和 Gemma 4 大模型的自动化数字取证 IR Agent，通过五阶段有限状态机实现端到端的事件响应调查流程。
Stars: 0 | Forks: 0
# W.A.R.V.I.S — 查找 Evil
[](./LICENSE)
**W.A.R.V.I.S** (Woops, A Rather Very Intelligent System) 是一个单一的 Go 二进制文件，它使用确定性的 5 状态 FSM (Finite State Machine) 和预算保留恢复功能来协调自动化的数字取证。专为物理隔离的事件响应环境而构建，在这些环境中，可靠性和可重复性比覆盖广度更重要。
**提交**: SANS FIND EVIL Hackathon | **截止日期**: 2026-06-15 | **作者**: WoopsFactory
## 为什么选择 warvis (vs Valhuntir)
我们承认 **Valhuntir** 是一个全面的 DFIR 参考平台（90+ 工具，22K-record RAG，Sigma rules，多后端编排）。我们并不声称能匹配其广度。相反，warvis 专注于三个狭窄的差异化优势：
1. **单一的 Go 控制二进制文件** — Hunt FSM、恢复预算和工具白名单均在 Go 中强制执行；Python 仍作为本地的 MCP 工具运行时。
2. **带有编译时工具白名单的 5 状态 Hunt FSM** — 架构上保证 agent 无法脱离其取证角色，在构建时（而非运行时）强制执行。
3. **预算保留恢复 + kill-switch 约束机制** — 每次搜寻在 CI 中都是可重现和可验证的；中断的搜寻可以恢复，而无需重新消耗 LLM-turn 配额。
对于处于物理隔离或受监管环境中的取证团队来说，这种狭窄的方法是一个可部署的答案。对于以广度为主的开放环境，Valhuntir 是参考标准。有关完整诚实的定位矩阵，请参阅 [docs/find-evil/valhuntir-comparison.md](./docs/find-evil/valhuntir-comparison.md)。
## 概述
W.A.R.V.I.S 将 Python MCP server（9 种取证工具）与 Go orchestrator 桥接器结合，提供**端到端的自动化事件响应**。该系统：
- **INITIALIZE**：打开取证案件并接收证据
- **TRACE**：构建时间线并查询结构化日志
- **SCAN**：扫描入侵指标 和内存工件
- **EXPOSE**：交叉检查发现并验证假设
- **LOCK**：终结审计追踪并生成取证报告
Gemma 4 LLM (via Ollama) 自主解释工具输出并选择下一个调查步骤。
## 前置条件
### 必需
- **Go** 1.21+ (用于 warvis 桥接器)
- **Python** 3.10+ (用于 MCP server)
- **Ollama** (运行在 `localhost:29134`)
- 模型：`gemma4:26b-a4b-it-q4_K_M`
- 设置：`ollama pull gemma4:26b-a4b-it-q4_K_M && ollama serve`
### 已验证平台
- Linux (Ubuntu 22.04+, Debian 12+)
- macOS (M1/M2, Intel；Ollama 可能需要更高的内存)
- Windows (带有 Linux 内核的 WSL2)
## 安装说明
### 1. 克隆仓库
```
git clone https://github.com/WooYoungSang/warvis-findEvil.git
cd warvis-findEvil
```
### 2. 设置 Python MCP Server
```
# 创建虚拟环境
python3.10 -m venv .venv
source .venv/bin/activate
# 安装依赖
pip install -e .[dev]
# 验证 MCP server 可导入
python -c "from find_evil_mcp import MCP"
```
### 3. 构建 Go 桥接器
```
cd warvis
go mod download
go build -o bin/warvis ./cmd/warvis
cd ..
```
### 4. 验证安装
```
# 测试 Go 二进制文件
./warvis/bin/warvis --version
# 测试 Python 环境
python -m pytest --co -q
```
## 快速开始
### 准备证据
将取证证据（磁盘镜像、内存转储、日志归档）放置在 `/evidence/` 下。MCP `case.open` 契约有意仅接受来自 SIFT 主机视角的绝对 `/evidence/...` 路径。
```
mkdir -p /evidence 2>/dev/null || echo "Use the SIFT-provided /evidence mount or ask an operator to create it."
# 添加你的证据文件（例如：/evidence/test.img, /evidence/memory.bin）
# 如果你的证据存放于此仓库中，请在运行 warvis 前将其符号链接或复制到 /evidence 中。
```
### 运行 Hunt
```
./warvis/bin/warvis hunt /evidence/test.img
```
**输出**：带有审计追踪的案件目录 `/cases//`：
```
/cases//
audit.jsonl # FSM state transitions + tool calls
report.json # Forensic findings (EXPOSE phase)
timeline.jsonl # Event timeline (TRACE phase)
```
### 检查结果
```
# 查看 FSM 进度
jq .event_type /cases//audit.jsonl | sort | uniq -c
# 提取发现
jq '.findings' /cases//report.json | head -20
```
### 恢复中断的 Hunt
如果搜寻被中断（网络、Ollama 超时），请使用以下命令恢复：
```
./warvis/bin/warvis hunt /evidence/test.img --case-id --resume
```
## 命令参考
### warvis hunt
开始对证据文件进行取证调查。
```
warvis hunt [--case-id ] [--resume]
```
**选项**：
- `--case-id`：使用现有的案件 ID（恢复模式）
- `--resume`：从上次检查点继续
**示例**：
```
warvis hunt /evidence/disk.img
# 输出：已使用 case_id=abc123def456 开启案件
```
### warvis status
检查活动或已完成搜寻的 FSM 状态。
```
warvis status
```
**输出**：
```
Case: abc123def456
State: SCAN (3/5)
Last Tool: iocs.scan
Progress: 60%
Timestamp: 2026-05-07T10:23:45Z
```
### warvis report
生成最终的取证报告。
```
warvis report [--format json|html]
```
## 架构
### FSM 状态与自治度
| 状态 | LLM 自治度 | 工具 | 目的 |
|-------|---|---|---|
| INITIALIZE | 0% | `case.open` | 接收证据，计算哈希值 |
| TRACE | 70% | `timeline.build`, `log.query` | 构建事件时间线，识别异常 |
| SCAN | 90% | `iocs.scan`, `memory.*`, `net.*` | 搜寻指标，扫描内存中的工件 |
| EXPOSE | 60% | `verify.cross_check`, `report.append` | 关联发现并附加已验证的报告条目 |
| LOCK | 0% | _(无 — 终结状态)_ | 在报告条目写入后封存案件 |
### 组件栈
- **MCP Server** (Python)：9 种取证工具，暴露 `case`、`timeline`、`log`、`iocs`、`memory`、`network`、`verify`、`report` 命名空间
- **Go Bridge** (Hunt Orchestrator)：管理 FSM 状态，运行 Ollama tool-call 循环，维护审计追踪
- **Gemma 4 LLM** (Ollama)：解释工具输出，选择下一个调查行动
- **Audit Trail** (JSONL)：所有 FSM 转换、工具调用和 LLM 推理的不可变记录
## 限制
### 已知约束
1. **轻量级扫描器**：YARA/Plaso 风格的路径仍包含合成装置，尚不属于生产级检测内容。
2. **外部工件待定**：全新的 SIFT VM 从克隆到搜寻的证据以及未列出的演示视频被有意作为 TODO/STOP 项进行跟踪，直到被捕获。
3. **Volatility3 最后一跳问题**：现有的追踪证明了 FSM/MCP 调度形态，但尚未直接演示从 agent 循环中真正触发 vol3。
4. **Ollama 依赖**：需要本地 Ollama 实例；尚不支持云 LLM
5. **召回率**：在合成测试套件上约为 60%；准确率 >80% 有待在真实数据集上进行调优
### 不支持的特性
- ⛔ 分布式取证（多节点调查）
- ⛔ 实时网络流量分析（仅限 PCAP 文件）
- ⛔ 加密分区分析（LUKS, BitLocker）
- ⛔ 云端取证（S3, Azure Blob, GCS 集成）
## 测试
### Python 测试
```
python -m pytest tests/ -v
python -m pytest --cov=src/find_evil_mcp/
```
### Go 测试
```
cd warvis
go test ./...
```
### 集成测试
```
make -C harness/find-evil test-hunt
```
## 故障排除
### "Ollama 连接被拒绝"
确保 Ollama 正在运行：
```
ollama serve
# 在另一个终端中：
ollama pull gemma4:26b-a4b-it-q4_K_M
```
### "MCP server 导入失败"
验证 Python 环境：
```
source .venv/bin/activate
pip install -e .[dev]
python -c "from find_evil_mcp import MCP; print(MCP.__version__)"
```
### "Go 构建失败：找不到模块"
确保您位于 `warvis/` 目录中：
```
cd warvis
go mod tidy
go build -o bin/warvis ./cmd/warvis
```
## 参考文献
- **架构**：[docs/find-evil/warvis-go-architecture.md](./docs/find-evil/warvis-go-architecture.md)
- **MCP 规范**：https://modelcontextprotocol.io
- **Ollama**：https://ollama.ai
- **SANS FIND EVIL**：https://findevil.devpost.com/
**W.A.R.V.I.S — 将数字混乱转化为取证清晰度。**
标签：AI安全, AI风险缓解, Chat Copilot, DAST, DLL 劫持, FSM, Gemma, Google搜索, Go语言, IoC扫描, MCP, Python, SANS FIND EVIL, SecList, 内存取证, 大语言模型, 子域名变形, 开源, 恶意软件分析, 数字取证, 数据展示, 无后门, 无线安全, 日志审计, 有限状态机, 物理隔离, 离线环境, 程序破解, 红队, 网络安全审计, 自动化取证, 自动化脚本, 跨语言编排, 逆向工具, 黑客松