akshaydotweb/HunterTrace
GitHub: akshaydotweb/HunterTrace
基于贝叶斯多信号融合的钓鱼邮件攻击者归因引擎，能在VPN/代理遮挡下追踪真实IP并生成执法级取证报告。
Stars: 2 | Forks: 0
# HUNTERTRACE
[](https://badge.fury.io/py/huntertrace)
[](https://pypi.org/project/huntertrace/)
[](LICENSE)
## 概述
HUNTERTRACE 是一个开源的网络钓鱼归因引擎，能够以 **73% 的准确率** 识别 **网络钓鱼攻击者的地理位置** —— 即使他们在 VPN、代理或 Tor 背后操作。如果启用基础设施图谱分析，准确率可达 **82%**。
传统的电子邮件取证仅依赖 IP 地理定位（约 31% 的准确率）。HUNTERTRACE 通过贝叶斯推理融合了 **8 种以上的正交信号**：
| 信号 | 来源 | 抗 VPN |
|--------|--------|:---:|
| Webmail IP 泄露 | X-Originating-IP, X-Sender-IP 头 | 是 |
| 时区偏移 | Date 头 / Received 链 | 是 |
| 语言指纹 | Content-Type 字符集, Subject 编码 | 是 |
| 基础设施复用 | 跨活动图谱中心性 | 是 |
| 跳跃链伪造 | Received 头一致性 | 部分 |
| VPN 出口节点映射 | ASN + 托管提供商分类 | 不适用 |
| SPF/DKIM/DMARC | 认证结果 | 部分 |
| Webmail 提供商 | 头指纹识别 (Gmail/Yahoo/Outlook) | 是 |
## 架构
```
┌─────────────────────────────────────────────────────────────┐
│ HUNTERTRACE PIPELINE │
├─────────────────────────────────────────────────────────────┤
│ │
│ Stage 1: Header Extraction (RFC 2822 parsing) │
│ ↓ │
│ Webmail IP Leak Detection (X-Originating-IP extraction) │
│ ↓ │
│ Stage 2: IP Classification (VPN/Tor/Proxy/Residential) │
│ ↓ │
│ Stage 3A: Enrichment (WHOIS, ASN, hosting provider) │
│ ↓ │
│ VPN Backtrack Analysis (12 bypass techniques) │
│ ↓ │
│ Real IP Extraction (strips proxy layers) │
│ ↓ │
│ Stage 3B: Threat Intelligence │
│ Stage 3C: Correlation Analysis │
│ ↓ │
│ Stage 4: Geolocation (city-level, IPv4 + IPv6) │
│ ↓ │
│ Stage 5: Attribution Analysis (evidence packaging) │
│ ↓ │
│ Bayesian Multi-Signal Fusion (ACI confidence scoring) │
│ ↓ │
│ Sender Classification (hop forgery + timezone analysis) │
│ ↓ │
│ Output: JSON report + text summary + attack graph HTML │
│ │
└─────────────────────────────────────────────────────────────┘
```
## 快速开始
### 安装
```
pip install huntertrace
```
### Python API
```
from huntertrace import HunterTrace
# 运行完整的 7 阶段 pipeline
pipeline = HunterTrace(verbose=True)
result = pipeline.run("phishing.eml")
# 生成文本报告
report = result.generate_report()
print(report.generate_text_report())
# 访问 Bayesian attribution
bayes = result.bayesian_attribution
if bayes:
print(f"Region: {bayes.primary_region}")
print(f"Confidence: {bayes.aci_adjusted_prob:.1%}")
print(f"Tier: {bayes.tier} — {bayes.tier_label}")
```
### 命令行
```
# 单个邮件分析
huntertrace analyze phishing.eml --verbose
# 批量处理
huntertrace batch emails/ -o results/
# Campaign 关联（跨邮件攻击者关联）
huntertrace campaign emails/ -o campaign_report/
```
## 性能
在已知真实来源的网络钓鱼邮件语料库上进行评估：
| 方法 | 区域准确率 | 备注 |
|--------|:-:|---|
| 仅 IP 地理定位 | 31% | 基线 |
| 仅时区 | 52% | 抗 VPN 但粒度较粗 |
| **HUNTERTRACE (贝叶斯)** | **73%** | 多信号融合 |
| **HUNTERTRACE (+ 图谱)** | **82%** | 包含基础设施复用检测 |
## 核心技术
### Webmail 提供商 IP 泄露检测
Gmail、Yahoo 和 Outlook 会将发送者的真实 IP 注入到 `X-Originating-IP` 和 `X-Sender-IP` 等头中。HUNTERTRACE 在源自 Webmail 的网络钓鱼邮件中检测这些泄露，**提取率为 67%**。
### 基于时区的 VPN 绕过
`Date:` 头的时区偏移揭示了发送者的本地时间，无论其是否使用 VPN。结合 `Received:` 链的时间分析，这提供了一种抗 VPN 的地理信号。
### 基础设施图谱中心性
在分析多封邮件（批量/活动模式）时，HUNTERTRACE 构建基础设施复用图并应用中心性指标来识别共享的攻击者基础设施 —— 从而提供 **+9% 的准确率提升**。
### 贝叶斯多信号融合
所有信号均通过似然比和贝叶斯更新进行结合。对抗性置信度指数 (ACI) 会针对规避尝试进行调整，从而生成校准后的置信度等级 (0–4)。
### VPN 回溯分析
12 种用于识别 VPN/代理层背后真实来源的技术，包括 ASN 分类、出口节点指纹识别和 Webmail 头关联。
## 项目结构
```
huntertrace/
├── core/ # Main pipeline + orchestrator
├── extraction/ # IP extraction (basic, advanced, VPN backtrack, webmail)
├── enrichment/ # Geolocation, WHOIS, hosting provider, IP classification
├── attribution/ # Bayesian engine + evidence analysis
├── analysis/ # Campaign correlator, sender classifier, actor profiler
├── graph/ # Attack graph builder, centrality engine
├── forensics/ # Header forensic scanner
├── cli.py # Command-line interface
└── assets/ # HTML templates, logos
```
## 环境要求
- Python 3.8+
- networkx >= 2.6
- numpy >= 1.20
- requests >= 2.25
### 可选依赖项
```
# Graph 社区发现（用于 Campaign 分析）
pip install huntertrace[graph]
# WHOIS enrichment
pip install huntertrace[whois]
# 全部功能
pip install huntertrace[all]
```
## 文档
- [安装指南](docs/INSTALLATION.md)
- [使用指南](docs/USAGE.md)
- [更新日志](CHANGELOG.md)
## 引用
如果您在研究中使用 HUNTERTRACE：
```
@software{huntertrace2026,
author = {Akshay V},
title = {HUNTERTRACE: Advanced Phishing Actor Attribution Using Multi-Signal Bayesian Inference},
year = {2026},
url = {https://github.com/akshaydotweb/huntertrace}
}
```
## 许可证
MIT 许可证 — 详见 [LICENSE](LICENSE)
## 免责声明
本工具仅适用于**合法的安全研究、事件响应和执法**用途。在分析邮件之前，请务必获得适当的授权。作者不对滥用行为负责。
## 联系方式
- GitHub: [@akshaydotweb](https://github.com/akshaydotweb)
- 电子邮箱: akshayvmudaliar@gmail.com
标签：IP 地址批量处理, IP 地理定位, Python, SPF/DKIM/DMARC 验证, Tor 检测, VPN 穿透, 代理检测, 反钓鱼, 基础设施图谱, 威胁情报, 安全分析工具, 开发者工具, 开源情报 (OSINT), 执法报告生成, 攻击者归因, 数字取证, 无后门, 网络安全, 网络犯罪调查, 自动化脚本, 贝叶斯推断, 逆向工具, 邮件取证, 邮件头分析, 配置审计, 钓鱼攻击溯源, 隐私保护