AliZafar780/findevil-agent
GitHub: AliZafar780/findevil-agent
一个自主的数字取证与事件响应（DFIR）AI 智能体，通过编排 21 个 MCP 取证工具实现跨内存、文件系统和网络的自动化安全调查与分析。
Stars: 0 | Forks: 0
# FindEvil Agent
**自主 DFIR 分析智能体 — AI 驱动的数字取证与事件响应**
[](https://github.com/AliZafar780/findevil-agent)
[](LICENSE)
[](https://python.org)
[](https://github.com/AliZafar780/findevil-agent/actions)
[](#mcp-server)
[](#ai-integration)
[](Dockerfile)
[](.github/workflows/ci.yml)
[](SECURITY.md)
`#dfir` `#incident-response` `#forensics` `#mcp` `#memory-forensics` `#yara` `#automation`
## 目录
- [概述](#overview)
- [功能](#features)
- [架构](#architecture)
- [快速开始](#quick-start)
- [使用指南](#usage-guide)
- [MCP Server](#mcp-server)
- [AI 集成](#ai-integration)
- [安全性](#security)
- [测试](#testing)
- [配置](#configuration)
- [Docker](#docker)
- [项目结构](#project-structure)
- [扩展](#extending)
- [常见问题](#faq)
- [贡献](#contributing)
- [许可证](#license)
## 概述
**FindEvil Agent** 是一个自主的数字取证与事件响应（DFIR）智能体，负责协调跨越内存、文件系统、注册表、网络和数据雕刻分析领域的 **21 个 MCP 取证工具**。它集成了 **Groq AI** 以进行智能工具选择和叙述性报告生成，同时能够在**无需任何 API key 的确定性模式**下完全运行。
该智能体遵循结构化的调查工作流 —— 分流、文件系统分析、痕迹提取、内存分析、注册表解析、网络分析、时间线关联和报告生成 —— 所有这些都通过单个 CLI 命令进行编排。
### 核心能力
| 能力 | 状态 |
|---|---|
| **21 个 MCP 取证工具** | 磁盘、内存、注册表、网络、雕刻、哈希、YARA |
| **AI 集成** | Groq Llama 3.3 70B（可选 — 确定性回退机制始终有效） |
| **无需 API Key** | 所有功能均可在没有 Groq、Shodan 或任何外部 key 的情况下运行 |
| **173 个通过的测试** | 单元测试 + 集成测试 + 基于属性的测试 (Hypothesis) + 边缘情况 |
| **安全加固** | 路径遍历、空字节注入、TOCTOU、YARA 注入、命令注入 — 全部拦截 |
| **置信度评分** | 针对每个工具的数据质量：CONFIRMED / INFERRED / UNVERIFIED |
| **Token 预算上限** | 每次会话最多 100K token（约 $0.07），支持实时跟踪 |
| **优雅降级** | 每个工具都有回退机制 — 系统绝不会因缺少依赖而崩溃 |
| **Docker 支持** | 包含 sleuthkit、yara、tshark、foremost、bulk-extractor 的多阶段构建 |
| **CI/CD 流水线** | GitHub Actions：lint、类型检查、测试（4 个 Python 版本）、构建、Docker、安全审计 |
## 功能
### 工具类别
| 类别 | 工具 | 后端 |
|---|---|---|
| **文件系统** | `fs_partition_scan`, `fs_list_files`, `fs_file_metadata`, `fs_extract_file`, `fs_filesystem_info` | TSK (fls, icat, mmls, fsstat, istat) |
| **数据雕刻** | `carve_files` | foremost |
| **哈希** | `verify_hash` | hashdeep / openssl |
| **YARA** | `scan_yara` | yara（内置规则用于 C2 域名、加密货币矿机、PowerShell 滥用、webshell） |
| **内存** | `mem_list_processes`, `mem_analyze`, `mem_scan_network`, `mem_dump_cmdline` | Volatility 3 + 基于字符串的 IOC 回退 |
| **注册表** | `reg_analyze_hive`, `reg_list_keys`, `reg_get_value` | regipy |
| **网络** | `pcap_analyze`, `pcap_list_protocols`, `pcap_extract_streams` | tshark |
| **信息** | `list_evidence`, `get_case_info`, `export_timeline` | TSK + 内置 |
| **配置** | `get_tool_config` | config/tools.toml |
### AI 集成
- **Groq Llama 3.3 70B** 用于智能工具选择和叙述性报告生成
- **确定性回退** — 无需 API key；内置工具选择器包含 58 个条目的注册表和基于优先级的回退链
- **Token 预算跟踪** — 实时成本监控（每次会话最多 100K token）
- **证据类型检测** — 自动过滤不兼容的工具，防止浪费 LLM 调用
### 安全加固
- 阻止路径遍历（9 种变体，包括编码、unicode 和空字节攻击）
- 拒绝所有证据路径上的空字节
- 针对 YARA 规则和 subprocess 调用提供命令注入保护
- 通过 `asyncio.Lock` 缓解 TOCTOU 竞争条件
- 输出大小限制（每个工具最多 100K 字符）
- 将安全事件日志持久化记录到 `~/.local/share/findevil/security_events.jsonl`
- 通过 Pydantic models 强制执行类型安全
### 性能优化
- 延迟导入 — 模块仅在其工具首次被调用时加载
- 缓存工具解析 — `shutil.which()` 结果按会话进行缓存
- 缓冲审计写入 — 批量进行安全日志的磁盘 I/O 操作
- 模块级 MCP server fixture 将边缘情况测试套件的运行时间从 3 分多钟缩短至约 25 秒
## 架构
```
┌─────────────────────────────────────────────────────────────────────────┐
│ FindEvil Agent │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────────┐ ┌──────────────────┐ ┌─────────────────────┐ │
│ │ CLI (rich) │ │ MCP Server │ │ Groq AI / │ │
│ │ findevil │──▶│ 21 Tools API │──▶│ Deterministic │ │
│ └──────────────────┘ └────────┬─────────┘ │ Tool Selector + │ │
│ │ │ Report Generator │ │
│ ┌───────────────────────────────┴────────────┐ └──────────┬──────────┘ │
│ │ DFIR Workflow Engine │ │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────┐ │ │ │
│ │ │Triage │→│ FS │→│ Carve │→│Memory│─┘ │ │
│ │ └────────┘ └────────┘ └────────┘ └──────┘ │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ │ │
│ │ │Registry│→│Network │→│Hashing │→│ Timeline │ │ │
│ │ └────────┘ └────────┘ └────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────┴───────────────────────────────────┐ │
│ │ Tool Resolver + Config/Tools.TOML │ │
│ │ fls │ icat │ mmls │ foremost │ yara │ tshark │ hashdeep │ │
│ │ bulk_extractor │ volatility3 │ regipy │ reglookup │ │
│ └───────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```
### 调查工作流
1. **证据输入** — 磁盘镜像（raw, E01）、内存转储（raw, ELF）、PCAP、注册表 hive
2. **分流** — 通过哈希（SHA256/SHA1/MD5）验证完整性，检查文件系统元数据
3. **文件系统分析** — 列出文件，提取元数据，通过 TSK 恢复已删除的内容
4. **痕迹提取** — 雕刻已删除的文件，使用 YARA 规则扫描（C2、加密货币矿机、webshell、PS 滥用）
5. **内存分析** — 列出进程，扫描网络连接，通过 Volatility 3 或 IOC 回退转储命令行
6. **注册表分析** — 解析 hive 文件，通过 regipy 提取键和值
7. **网络分析** — 分析 PCAP，提取协议，通过 tshark 重建会话
8. **时间线关联** — 导出 MAC 时间线以进行时间上的关联
9. **报告生成** — Groq LLM 叙述或内置确定性报告生成器
## 快速开始
### 前置条件
- **Python 3.10+**
- **系统工具**（推荐用于完整功能）：
# Linux
sudo apt install sleuthkit foremost yara tshark
# macOS
brew install sleuthkit foremost yara tshark
- **Groq API Key**（可选）：[免费获取](https://console.groq.com)
### 安装说明
```
# 克隆 repository
git clone https://github.com/AliZafar780/findevil-agent.git
cd findevil-agent
# 创建并激活虚拟环境
python3 -m venv venv && source venv/bin/activate
# 安装 package
pip install -e .
```
### 验证安装
```
findevil check
```
### 运行您的首次调查
```
# 生成包含真实 IOC 的测试镜像
findevil create-test-image test.dd
# 运行完全自主调查（无需 API key）
findevil investigate test.dd --output ./results
# 使用 AI 驱动的分析（需要 GROQ_API_KEY）
findevil investigate test.dd --output ./results
```
## 使用指南
### CLI 参考
```
findevil [command] [options]
```
| 命令 | 描述 |
|---|---|
| `investigate
` | 运行完整的调查工作流 |
| `check` | 验证环境和工具可用性 |
| `tools` | 列出所有可用的 MCP 工具 |
| `tool [args]` | 直接执行单个 MCP 工具 |
| `create-test-image ` | 生成嵌入了 IOC 的测试磁盘镜像 |
| `serve` | 启动 MCP server 以进行 LLM 集成 |
### 调查选项
```
findevil investigate [options]
Options:
--output PATH Output directory for results
--task TEXT Natural language task description
--groq-model TEXT Groq model (default: llama-3.3-70b-versatile)
--no-ai Skip AI — use deterministic report generator
--phase PHASE Run specific phase only (triage, fs, carve, memory, registry, network, timeline)
--json Output as JSON
--debug Enable debug logging
--no-logo Skip ASCII logo
```
### 使用示例
```
# 使用 AI 进行全面调查
findevil investigate ./evidence.dd --output ./results
# Deterministic 模式（无需 API key）
findevil investigate ./evidence.dd --no-ai
# 仅运行特定阶段
findevil investigate ./evidence.dd --phase memory
# 列出所有可用工具
findevil tools
# 直接执行单个工具
findevil tool fs_list_files --image evidence.dd
findevil tool scan_yara --image evidence.dd --rules "rule Bad { strings: \$a = \"evil\" condition: \$a }"
# 调查证据文件目录
findevil investigate /evidence/case_dir/ --output ./results
# Debug 模式
findevil investigate ./evidence.dd --debug
```
## MCP Server
FindEvil 实现了 **Model Context Protocol** (MCP)，使所有 21 个工具可用于任何兼容 MCP 的 LLM 客户端。
### 配置
添加到您的 MCP 客户端配置中（例如 `claude_desktop_config.json`）：
```
{
"mcpServers": {
"findevil": {
"command": "findevil",
"args": ["serve"]
}
}
}
```
### 启动服务器
```
findevil serve
```
### 可用工具
所有 21 个工具均具有带有类型化输入 schema 的自文档化功能。该 server 公开：
- **文件系统**：分区扫描、文件列出、元数据提取、文件提取、文件系统信息
- **数据雕刻**：通过 foremost 恢复已删除的文件
- **哈希**：SHA256/SHA1/MD5 完整性验证
- **YARA**：基于模式扫描，内置 IOC 规则
- **内存**：进程列出、网络连接扫描、命令行转储
- **注册表**：hive 解析、键/值枚举
- **网络**：PCAP 分析、协议提取、流重建
- **时间线**：MAC 时间线生成和过滤
- **实用工具**：证据列出、案件信息、工具配置查询
## AI 集成
### Groq AI 模式
设置了 `GROQ_API_KEY` 后，智能体将使用 **Groq 的 Llama 3.3 70B** 模型来：
- 根据调查上下文选择最佳的下一个工具
- 生成总结发现的叙述性报告
- 根据证据类型优先安排调查路径
```
export GROQ_API_KEY="your_api_key_here"
findevil investigate ./evidence.dd --output ./results
```
### 确定性模式（默认）
在没有任何 API key 的情况下，所有功能均使用内置的确定性逻辑运行：
| 功能 | 有 API Key | 无 API Key |
|---|---|---|
| 工具执行 | 是 | 是 |
| 工具选择 | AI 优化 | 确定性回退链（58 个条目的注册表） |
| 报告生成 | Groq 叙述 | 内置叙述生成器 |
| Token 跟踪 | 是 | 是（上限为 $0） |
| 审计追踪 | 是 | 是 |
### 优雅降级
每个取证工具至少有一个回退路径：
| 缺少的工具 | 回退方案 |
|---|---|
| YARA | 内置签名扫描 |
| Volatility 3 | 基于字符串的 IOC 扫描 |
| TSK (sleuthkit) | 通过 Python 减少文件列出 |
| regipy | reglookup CLI（如果可用） |
| tshark | 通过 Python 进行基本的数据包分析 |
| foremost | 内置文件签名雕刻 |
## 安全性
### 纵深防御架构
| 层级 | 保护措施 |
|---|---|
| **路径验证** | 针对 `EVIDENCE_ROOT` 验证所有证据路径 |
| **输入清理** | 阻止空字节、控制字符和路径遍历（9 种变体） |
| **类型安全** | Pydantic models 在 runtime 强制执行参数类型 |
| **命令注入** | YARA 规则和 exec 命令在执行前进行验证 |
| **TOCTOU 预防** | `asyncio.Lock` 防止并发访问时的竞争条件 |
| **输出隔离** | 工具输出最多限制为 100K 字符 |
| **超时限制** | 工具执行上限为 600 秒 |
| **审计追踪** | 记录每次工具调用的参数、结果和时间；持久化到 JSONL |
### 已拦截的攻击向量
- 路径遍历（9 种编码变体）
- 空字节注入
- Symlink 替换攻击 (TOCTOU)
- 输出目录逃逸（10 个系统目录）
- 通过 YARA 规则和 exec 参数进行的命令注入
- 错误的参数类型和缺少必需参数
- 空的 YARA 规则和格式错误的输入
- 资源耗尽（200MB+ 输入）
- 通过精心构造的参数进行的日志注入
- 并发访问竞争条件
### 报告
有关我们的负责任披露政策，请参阅 [SECURITY.md](SECURITY.md)。
## 测试
### 运行测试套件
```
# 所有测试
pytest tests/ -v
# 特定测试套件
pytest tests/test_cli.py -v # CLI tests
pytest tests/test_forensic_tools.py -v # Tool model & resolver tests
pytest tests/test_groq_client.py -v # Parser, selector, client tests
pytest tests/test_server.py -v # MCP server integration tests
pytest tests/test_edge_cases.py -v # Edge case integration tests
pytest tests/test_workflow.py -v # Workflow tests
```
### 测试覆盖率 — 173 个测试
| 套件 | 类型 | 数量 | 覆盖范围 |
|---|---|---|---|
| CLI | 单元 | 4 | Logo 渲染、版本、帮助、导入 |
| 取证工具 | 单元 | 15 | Models（哈希、模式、文件系统、注册表、网络、时间线、内存）、工具解析器 |
| Groq Client | 单元 | 22 | Client 初始化、输出解析器、工具选择器、回退链 |
| 工作流 | 集成 | 2 | Agent 循环阶段、工具链式调用 |
| 边缘情况 | 集成 | 104 | 路径遍历、缺少证据、雕刻安全性、YARA、大文件、审计追踪、并发访问、错误质量、拒绝错误工具 |
| 基于属性 | Hypothesis | 15 | 工具解析器不变性、清理/截断属性、所有 Pydantic model 检查 |
| Server | 集成 | 11 | 工具执行、哈希验证、证据列出、路径验证、错误处理 |
### CI 流水线
GitHub Actions 跨 **4 个 Python 版本**（3.10、3.11、3.12、3.13）运行：
```
lint (ruff) → type-check (mypy) → test (pytest × 4 versions)
→ build (wheel) → Docker (multi-stage) → audit (pip-audit)
```
## 配置
### 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `GROQ_API_KEY` | — | Groq API key（可选 — 所有功能均可在此情况下运行） |
| `EVIDENCE_ROOT` | `/evidence` | 默认证据目录 |
| `RESULTS_ROOT` | `/results` | 默认结果目录 |
### 可选依赖项
```
# 安装核心取证工具（Volatility 3、Regipy）
pip install -e ".[core]"
# 用于开发的所有内容
pip install -e ".[dev,core]"
```
### 工具配置（`config/tools.toml`）
工具路径和参数定义在 `config/tools.toml` 中：
```
[tools.fls]
path = "fls"
args = ["-r", "-p", "{image_path}"]
description = "List file names in a disk image"
```
在 runtime 查询工具配置：
```
findevil tool get_tool_config --tool fls
```
## Docker
### 构建
```
docker build -t findevil-agent .
```
### 运行
```
docker run --rm \
-v /path/to/evidence:/evidence \
-v /path/to/results:/results \
findevil-agent investigate /evidence/case.dd
```
多阶段 Dockerfile 使用 `python:3.11-slim` 构建器和 `ubuntu:24.04` runtime，并预装了 sleuthkit、foremost、yara、tshark 和 bulk-extractor。
## 项目结构
```
findevil-agent/
├── src/
│ ├── cli.py # Rich CLI entry point
│ ├── server.py # MCP server (21 tools, async subprocess, audit, security logs)
│ ├── models.py # Pydantic data models
│ ├── _version.py # Version constant
│ ├── __main__.py # Package entry point
│ ├── agent/
│ │ ├── loop.py # DFIR workflow + evidence pre-validation
│ │ ├── groq_client.py # Groq LLM + deterministic fallback
│ │ ├── output_parser.py # Balanced-brace JSON extraction
│ │ └── tool_selector.py # 58-entry registry with fallback chains
│ └── tools/
│ ├── filesystem.py # TSK wrappers (fls, icat, mmls, fsstat, istat)
│ ├── carving.py # Foremost carving
│ ├── memory.py # Volatility 3 + IOC scanning
│ ├── registry.py # Regipy hive parsing
│ ├── network.py # TShark PCAP analysis
│ ├── hashing.py # hashdeep / openssl
│ ├── patterns.py # YARA rules (C2, crypto, webshells, PS abuse)
│ ├── timeline.py # MAC timeline export
│ ├── tool_resolver.py # Cross-platform shutil.which() resolution
│ └── __init__.py
├── config/
│ ├── tools.toml # Tool path & argument definitions
│ └── server.toml # Server configuration
├── tests/
│ ├── conftest.py # Shared fixtures (module-scoped MCP server)
│ ├── helpers.py # Shared test utilities
│ ├── test_cli.py # CLI unit tests
│ ├── test_forensic_tools.py # Tool model tests
│ ├── test_groq_client.py # Parser/selector/client tests
│ ├── test_server.py # MCP server integration tests
│ ├── test_edge_cases.py # Edge case integration tests
│ └── test_workflow.py # Workflow tests
├── scripts/
│ └── generate_test_evidence.sh # Test evidence image generator
├── .github/workflows/ci.yml # GitHub Actions CI/CD
├── Dockerfile # Multi-stage Docker build
├── pyproject.toml # PEP 621 project config
├── CHANGELOG.md # Version history
└── GAP_ANALYSIS.md # 33-gap audit and closure report
```
## 扩展：添加新的取证工具
### 步骤 1：编写工具逻辑
```
# src/tools/strings.py
import subprocess
from pydantic import BaseModel
class StringsResult(BaseModel):
success: bool
strings: list[str] = []
error: str = ""
def extract_strings(image_path: str, min_len: int = 6) -> StringsResult:
"""Extract readable strings from a binary image."""
try:
result = subprocess.run(
["strings", "-n", str(min_len), image_path],
capture_output=True, text=True, timeout=60,
)
lines = [s for s in result.stdout.split("\n") if s.strip()]
return StringsResult(success=True, strings=lines[:200])
except Exception as e:
return StringsResult(success=False, error=str(e))
```
### 步骤 2：在 MCP server 中注册
```
# 在 src/server.py 中
from src.tools.strings import extract_strings, StringsResult
# 添加 Tool 定义
Tool(
name="extract_strings",
description="Extract ASCII/Unicode strings from a binary file",
inputSchema={
"type": "object",
"properties": {
"image_path": {"type": "string"},
"min_length": {"type": "integer", "description": "Minimum string length", "default": 6},
},
"required": ["image_path"],
},
)
# 添加 handler
async def _handle_extract_strings(args: dict) -> list[TextContent]:
image_path = args["image_path"]
min_len = args.get("min_length", 6)
err = _validate_evidence_path(image_path)
if err:
return [TextContent(type="text", text=json.dumps({"success": False, "error": err}))]
result = extract_strings(image_path, min_len)
return [TextContent(type="text", text=result.model_dump_json(indent=2))]
```
### 步骤 3：在工具选择器中注册
```
# 在 src/agent/tool_selector.py 中
PHASE_TOOLS["strings_analysis"] = [
{"tool": "extract_strings", "priority": 1, "reasoning": "Extract embedded strings"},
]
```
就是这样。该工具将出现在 `findevil tools` 中，可通过 MCP 调用，并可用于 AI 驱动的工作流。
## 常见问题
### 支持哪些镜像格式？
Raw/dd 镜像（`.dd`、`.raw`、`.img`、`.bin`）、拆分的 raw 镜像、E01/EWF（Expert Witness）和 AFF4。内存转储：raw（`.raw`、`.mem`、`.bin`）和 ELF（LiME 输出）。PCAP/PCAPNG 用于网络捕获。
### 证据文件可以有多大？
已测试高达 50 GB 的 raw 镜像。系统使用流式读取进行数据雕刻，并仅扫描大型内存转储的前 100 MB 以查找 IOC 字符串。
### 我可以一次分析多个证据文件吗？
可以 — 将目录传递给 `findevil investigate`。系统会对每个文件进行分流并按顺序处理它们，将结果合并到一个时间线和报告中。
### AI 模式需要互联网访问吗？
需要 — Groq API 需要互联网连接。确定性模式完全可以离线工作，无需任何 API key。
### 如何选择 Volatility 插件？
系统会根据调用的工具尝试 `linux.pslist.PsList`、`linux.malfind.Malfind`、`linux.netstat.Netstat`、`linux.bash.Bash`。如果都不起作用，它会回退到基于字符串的 IOC 扫描。
### 如果没有安装取证工具会怎样？
每个工具都有一个优雅的回退机制：缺少 YARA → 内置签名扫描，缺少 Volatility → 字符串 IOC 扫描，缺少 TSK → 减少文件列出，缺少 regipy → reglookup CLI（如果可用）。系统绝不会因为缺少工具而崩溃。
### 为什么 `pip install -e .` 不安装 Volatility/Regipy？
它们位于可选的 `core` 组中。需要显式安装它们：`pip install -e ".[core]"`。
## 故障排除
| 问题 | 原因 | 解决方案 |
|---|---|---|
| `Tool not found` | 未安装取证工具 | `sudo apt install sleuthkit foremost yara tshark` (Linux) |
| `No partition table found` | 镜像是原始文件系统（没有 MBR/GPT） | 改用 `fs_filesystem_info`，或者传入 `--offset 0` |
| `Not a Registry hive file` | 证据类型对应的工具错误 | 首先使用 `fs_list_files` 确定证据类型 |
| `AI returned no tools` | 解析器无法从 LLM 提取 JSON | 自动回退到确定性模式 |
| `Image contains no files` | 偏移量错误或镜像损坏 | 首先运行 `fs_partition_scan`，然后使用检测到的偏移量 |
| `HAS_EVIDENCE=False` / 测试跳过 | 没有测试镜像 | 运行 `findevil create-test-image /evidence/cases/test.raw` |
### 仍然遇到问题？
```
# 检查你的环境
findevil check
# 开启 debug 日志运行
findevil investigate ./evidence.dd --debug
```
## 贡献
我们欢迎各种贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。
主要贡献领域：
- macOS 和 Windows Volatility 3 插件
- 额外的 YARA 规则集
- 新的取证工具集成
- 性能优化
## 许可证
在 **MIT License** 下分发。详情请参阅 [LICENSE](LICENSE)。
FindEvil Agent v2.1.5
自主 DFIR 分析 · 内存 · 磁盘 · 注册表 · 网络 · 数据雕刻 · YARA
由 Ali Zafar 构建
标签：AI智能体, MCP, 库, 应急响应, 数字取证, 自动化分析, 自动化脚本, 请求拦截, 跨站脚本, 逆向工具