nlink-jp/mail-analyzer
GitHub: nlink-jp/mail-analyzer
一款结合规则引擎与 Gemini LLM 的可疑邮件分析工具，支持解析多种格式邮件并输出包含安全风险评估的结构化 JSON。
Stars: 0 | Forks: 0
# mail-analyzer
可疑邮件分析器，结合了基于规则的指标和 Gemini LLM。
解析 `.eml` 和 `.msg` 文件并输出结构化的 JSON，包含 SHA-256 哈希值、
认证结果、发件人完整性检查、URL/附件风险评估，
以及由 LLM 驱动的内容分析。
## 功能
- **双重分析引擎**：确定性基于规则的指标 + Gemini LLM 内容分析
- **支持 EML 和 MSG**：完整的字符集处理（ISO-2022-JP、Shift_JIS、EUC-JP 等）
- **SHA-256 哈希**：文件哈希和每个附件的哈希，用于 IoC 关联
- **认证分析**：SPF、DKIM、DMARC 结果解析
- **发件人完整性**：From/Return-Path 不匹配、显示名欺骗、Reply-To 偏差
- **URL 分析**：提取、去激活（Defanging）、免费托管 / 短链接 / 可疑 TLD 检测
- **附件分析**：危险扩展名、启用宏的 Office、双重扩展名
- **路由分析**：X-Mailer 分类、可疑的 Received 头检测
- **离线模式**：无 LLM 的基于规则分析（无 API 调用）
- **Prompt injection 防御**：带有 nonce 标签的 XML 边界，并在 prompt 顶部提供防御指令
## 安装说明
```
git clone https://github.com/nlink-jp/mail-analyzer.git
cd mail-analyzer
make build # → dist/mail-analyzer
```
## 运行说明
```
# 使用 Gemini LLM (需要配置包含 Vertex AI 的 GCP project)
export MAIL_ANALYZER_PROJECT=your-project-id
mail-analyzer email.eml
# 离线模式 (仅基于规则，无 API 调用)
mail-analyzer --offline email.eml
# MSG 格式
mail-analyzer message.msg
# 支持 Pipe
mail-analyzer email.eml | jq '.judgment'
mail-analyzer email.eml | jq '.indicators.urls[] | select(.suspicious)'
```
## 配置
配置按以下优先级加载：
1. **环境变量**（`MAIL_ANALYZER_*` 或 `GOOGLE_CLOUD_*`）
2. **TOML 配置文件**（`~/.config/mail-analyzer/config.toml`）
3. **默认值**
```
# 设置 config file (可选)
mkdir -p ~/.config/mail-analyzer
cp config.example.toml ~/.config/mail-analyzer/config.toml
# 编辑 project ID
```
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `MAIL_ANALYZER_PROJECT` | (必填) | 用于 Vertex AI 的 GCP project ID |
| `MAIL_ANALYZER_LOCATION` | `us-central1` | Vertex AI location |
| `MAIL_ANALYZER_MODEL` | `gemini-2.5-flash` | Gemini model 名称 |
| `MAIL_ANALYZER_LANG` | (自动) | 强制输出语言 |
| `--config ` | | 覆盖配置文件路径 |
## 输出 Schema
```
{
"source_file": "alert.eml",
"hash": "sha256...",
"message_id": "<...>",
"subject": "...",
"from": "...",
"to": ["..."],
"date": "...",
"indicators": {
"authentication": { "spf": "fail", "dkim": "pass", "dmarc": "fail" },
"sender": { "from_return_path_mismatch": true, ... },
"urls": [{ "url": "hxxps://evil[.]com/path", "suspicious": true, "reason": "..." }],
"attachments": [{ "filename": "...", "hash": "sha256...", "suspicious": false }],
"routing": { "hop_count": 7, "x_mailer": "...", "x_mailer_suspicious": false }
},
"judgment": {
"is_suspicious": true,
"category": "phishing",
"confidence": 0.95,
"summary": "...",
"reasons": ["...", "..."],
"tags": ["...", "..."]
}
}
```
## 构建
```
make build # Build for current platform → dist/
make build-all # Cross-compile all platforms
make test # Run tests
make clean # Remove dist/
```
## 文档
- [架构](docs/architecture.md) — 设计决策、分析方法、原理
- [README.md](README.md) (英语)
- [README.ja.md](README.ja.md) (日语)
- [CHANGELOG.md](CHANGELOG.md)
标签：AI辅助分析, EVTX分析, Go, Python安全, Ruby工具, 威胁情报, 开发者工具, 日志审计, 邮件分析, 钓鱼检测