Oskiir23/veredictum
GitHub: Oskiir23/veredictum
一款将恶意邮件静态取证分析与 LLM 推理相结合、自动生成 Word 格式鉴定意见书草稿的 DFIR 自主代理。
Stars: 0 | Forks: 0
# Veredictum
**自主 DFIR Agent：恶意邮件分流 → 鉴定意见书草稿生成。**
你只需传入一封邮件（`.eml`）。Veredictum 会使用取证工具对其进行静态分析，LLM agent 会对事实进行推理，并生成一份 **Word 格式的鉴定意见书草稿** —— 它会标记出**无法**确认的内容以便人类鉴定专家进行验证，而不是凭空捏造结论。
## 目录
1. [特性](#características)
2. [架构](#arquitectura)
3. [要求](#requisitos)
4. [安装](#instalación)
5. [API 密钥（免费）](#claves-de-api-gratis)
6. [使用 — 直接模式](#uso--modo-directo)
7. [使用 — VM 隔离模式（真实恶意软件）](#uso--modo-aislado-en-vm-malware-real)
8. [安全模型](#modelo-de-seguridad)
9. [项目结构](#estructura-del-proyecto)
10. [限制与法律声明](#limitaciones-y-aviso-legal)
11. [路线图](#roadmap)
12. [作者与许可证](#autor-y-licencia)
## 特性
- **邮件解析**：邮件头、SPF/DKIM/DMARC 身份验证、正文、附件。
- **IOC 提取**：URL、IP、域名、邮箱和哈希值（以 *defang* 格式呈现）。
- **静态附件分析**：哈希值（MD5/SHA-1/SHA-256）、通过 *magic bytes* 识别真实文件类型（检测伪装成 `.zip` 的 `.exe`），以及使用 `olevba` 分析 VBA 宏。
- **VirusTotal**：通过哈希值查询（从不上传文件）。
- **Word 鉴定意见书**采用鉴定模板：包含 TLP 封面、宣誓声明、法规、方法论、IOC、编号结论、证据监管链。
- **不确定性标记**：将无法得出结论的内容移至“待验证的限制与要点”部分。绝不捏造结论。
- **隔离模式**：对活体样本的操控在无网络的 VM 中进行；仅向宿主机传输文本。二进制文件永远不会触及你的设备。
## 架构
**事实**（哈希值、身份验证、IOC）由取证工具提供；**推理**（结论、判定、不确定性）由 LLM 提供。这样事实就不会被凭空捏造。
**直接模式**（良性/已知样本）—— 全部在一台机器上执行：
```
.eml → [agente LLM + herramientas] → dictamen .docx
```
**隔离模式**（真实恶意软件）—— 将危险部分隔离开来：
```
VM aislada (SIN red) │ host (con internet)
─────────────────── │ ──────────────────
extraer.py │
.eml → parse + hash + olevba │
→ evidencia.json ──────────────┼──► dictaminar.py
(binario → /tmp, NO sale) carpeta │ LLM + VirusTotal
compartida │ → dictamen .docx
```
LLM 引擎隔离在 `veredictum/llm.py` 中（目前使用 Gemini）；如果要使用本地模型（例如 Ollama），只需重新实现该文件即可。
## 要求
- **Python 3.10+**
- **Node.js 18+**（鉴定意见书 `.docx` 通过 `docx-js` 生成）
- 一个 **Gemini** API 密钥（免费）—— 见下文
- *（可选）* **VirusTotal** 密钥（免费）
- *（可选，针对真实恶意软件）* **VirtualBox** + Linux 虚拟机（Kali/Parrot）
## 安装
```
# 1. Clonar
git clone https://github.com//veredictum.git
cd veredictum
# 2. Python 虚拟环境
python -m venv .venv
# Windows:
.\.venv\Scripts\Activate.ps1
# Linux/Mac:
source .venv/bin/activate
# 3. Python 依赖
pip install -r requirements.txt
# 4. Node 依赖（.docx 的 renderer）
npm install
# 5. 配置密钥（见下一节）
copy .env.example .env # Windows (Linux/Mac: cp .env.example .env)
# 编辑 .env 并粘贴你的密钥
```
## API 密钥（免费）
密钥**不包含**在代码库中。每位用户需将自己的密钥放入 `.env` 文件中（该文件已包含在 `.gitignore` 中，从不上传）。
### Gemini（必需，免费）
1. 访问 **https://aistudio.google.com/app/apikey**（使用 Google 账号）。
2. 点击 **创建 API 密钥**（如果要求提供项目，请新建一个）。
3. 复制密钥。
### VirusTotal（可选，免费）
1. 在 **https://www.virustotal.com** 注册账号。
2. 访问 **https://www.virustotal.com/gui/my-apikey** 并复制你的 API key。
3. 如果没有此密钥，哈希分析将被标记为“未查询”（有待人工验证）—— 系统依然能正常运行，但缺乏多引擎扫描的判定结果。
### 存放位置
编辑 `.env` 文件（从 `.env.example` 复制）：
```
GEMINI_API_KEY=tu_clave_de_gemini
VT_API_KEY=tu_clave_de_virustotal # opcional
VEREDICTUM_MODEL=gemini-2.5-flash # modelo del free tier
```
## 使用 — 直接模式
适用于**无害或已知**的样本，无需 VM。只需一步即可完成分析并生成意见书：
```
python run.py veredictum/samples/demo.eml
```
生成的鉴定意见书会保存在 `salida/dictamen_.docx` 中。
## 使用 — VM 隔离模式（真实恶意软件）
对于包含**潜在恶意附件**的邮件，操作需在**无互联网连接**的虚拟机中进行。二进制文件永远不会触及宿主机；仅通过 JSON 文本传递事实。
### 1. 准备 VM
在 VirtualBox 中创建（或克隆）一台 Linux VM。建议从已安装好的 Kali/Paroot 镜像开始操作。**务必始终使用一次性的克隆副本进行操作**，不要在你主要的 VM 上操作。
### 2. 加固 VM（需禁用的项目）
在 VM **关机**状态下，打开 **设置（Configuración）** 并应用：
**a) 禁用网络**（最重要的一点 —— 否则恶意软件将能连接外网）：
- `设置（Configuración） → 网络（Red） → 网卡 1（Adaptador 1）`
- **取消勾选“启用网卡（Habilitar adaptador de red）”**。
- 如果适配器 2–4 处于活动状态，请重复此操作。
**b) 禁用剪贴板和拖放功能**（防止污染的途径）：
- `设置（Configuración） → 常规（General） → 高级（Avanzado）`（或专家模式下的 *Features* 选项卡）
- **共享剪贴板（Portapapeles compartido） → 禁用（Inhabilitado）**
- **拖放（Arrastrar y soltar） → 禁用（Inhabilitado）**
### 3. 创建共享文件夹（传输通道）
此文件夹是 VM↔宿主机之间**唯一**的桥梁。仅共享提取器所在的文件夹 —— **绝不要**共享包含你 `.env` 的项目主文件夹。
1. 在宿主机上，生成传输文件夹（复制不包含 `.env` 的提取器，并创建 `entrada/` 和 `salida/`）：
python preparar_transfer.py
2. 进入 `设置（Configuración） → 共享文件夹（Carpetas compartidas） →（+ 图标）`
3. 填写以下内容：
- **文件夹路径（Ruta de la carpeta）**：宿主机上 `transfer_vm/` 的路径。
- **文件夹名称（Nombre de la carpeta）**：`transfer_vm`。
- **自动挂载（Automontar）**：✅ 勾选。
- **只读（Sólo lectura）**：❌ 不勾选（VM 必须能够写入 `evidencia.json`）。
4. 点击确认。在 Kali 中，它将被挂载到 `/media/sf_transfer_vm`。
### 4. 拍摄快照（snapshot）以保存干净状态
在植入恶意软件之前，请先建立一个还原点：
- 在 VM 窗口中：`设备/计算机（Máquina） → 拍摄快照（Tomar instantánea）`（将其命名为 `limpio`）。
### 5. 分析流程
```
[Host] Copia el correo a analizar en transfer_vm/entrada/caso.eml
[VM] Arranca la VM (login por defecto en imágenes Kali: kali / kali)
[VM] En una terminal:
cd /media/sf_transfer_vm
bash correr_en_vm.sh entrada/caso.eml
-> genera salida/evidencia.json (solo texto)
-> el binario queda en /tmp/veredictum DENTRO de la VM
[Host] python dictaminar.py transfer_vm/salida/evidencia.json CASO-ID
-> salida/dictamen_CASO-ID.docx
```
### 6. 清理（重要）
完成后，**恢复快照**（`设备/计算机（Máquina） → 快照（Instantáneas） → 恢复（Restaurar） 'limpio'`）。这将删除恶意二进制文件，并使 VM 恢复干净状态以备下次使用。
## 安全模型
- **绝不执行**任何附件。仅进行静态分析。
- 附件在写入隔离文件夹时，会添加 **`.quarantine`** 后缀（不可执行，无法通过双击运行）。
- 在隔离模式下，隔离区**位于 VM 内部**（`/tmp/veredictum`）；向宿主机仅传输 `evidencia.json`（文本）。
- 发送给 VirusTotal 的**仅限哈希值**，绝无文件本身。
- SHA-256 会在**触及磁盘之前在内存中完成计算**：即便杀毒软件删除了样本，意见书中依然会保留哈希值。
- 包含你密钥的 `.env` 位于 `.gitignore` 中，不会上传至代码库。
## 项目结构
```
veredictum/
config.py Claves, modelo, rutas (dotenv opcional)
context.py Store de hechos compartido entre herramientas
llm.py Capa LLM aislada (Gemini; cambiable a local)
agent.py Persona del perito + orquestación (directo y split)
extractor.py Extracción offline (para la VM)
tools/
email_tools.py parse_email, extract_iocs
attachment_tools.py analyze_attachment (olevba), vt_lookup
report_tools.py write_report (invoca el renderer Node)
render/
gen_dictamen.js Renderer del .docx (docx-js) con la plantilla pericial
samples/demo.eml Correo de demostración (inofensivo)
run.py CLI modo directo
extraer.py CLI extracción (en la VM)
dictaminar.py CLI dictamen desde hechos (en el host)
transfer_vm/ Carpeta a compartir con la VM (extractor + entrada/salida)
tests/ Pruebas de humo
```
## 限制与法律声明
- 生成结果仅为**草稿**，需经过司法鉴定验证。它并非已签字的正式鉴定意见书，也不构成法律建议。
- 宏分析（`olevba`）需要 `oletools` 支持；在没有该工具的 VM 中将跳过此步骤（PE 文件不需要宏）。
- 支持 `.msg`（Outlook）和 YARA 规则：已列入路线图。
- 仅对你已获授权的电子证据使用本工具。
## 路线图
- [ ] 支持 `.msg`（Outlook）格式邮件。
- [ ] 对附件应用 **YARA** 规则。
- [ ] **动态分析**（在隔离沙箱中引爆）。
- [ ] **本地 LLM**（Ollama）选项，实现 100% 离线流程。
## 作者与许可证
**Óscar Carretero Hilillo** —— ASIR 高级技师 · 网络安全硕士。
**MIT** 许可证（详见 `LICENSE`）。
标签：LLM智能体, MITM代理, 云安全监控, 库, 应急响应, 恶意邮件分析, 数字取证, 自动化报告生成, 自动化脚本, 逆向工具, 静态分析