SumitSonkusale/phishing-detector-python
GitHub: SumitSonkusale/phishing-detector-python
一款基于启发式规则的 Python 钓鱼邮件检测 CLI 工具，通过分析邮件标头、正文和 URL 为安全运营团队提供快速分诊判定。
Stars: 0 | Forks: 0
# phishing-detector-python
一个命令行钓鱼检测工具，通过分析电子邮件的标头、正文和嵌入的 URL 来识别钓鱼指标。专为对分诊速度有要求的 SOC 和蓝队工作流而构建。
## 功能
- **标头分析** — 检查 `From`/`Reply-To` 域名不匹配、缺失的 SPF/DKIM/DMARC 身份验证标头以及可疑的标头模式
- **正文分析** — 检测紧急催促性语言、凭据收集短语、可疑的发件人线索和混淆文本
- **URL 分析** — 标记基于 IP 的 URL、同形异义词/拼写抢注模式、过多的子域名、可疑的 TLD 以及编码字符
- **综合评分** — 将每个分析器的风险分数汇总为整体判定（`clean` / `suspicious` / `phishing`）
- **JSON 输出** — 适合 SIEM 摄取或进一步流水线处理的结构化结果
- **CLI 接口** — 接受原始的 `.eml` 文件、通过管道传输的 stdin 或手动输入
## 项目结构
```
phishing-detector-python/
├── phishing_detector/
│ ├── __init__.py # Package version + public API
│ ├── models.py # Dataclasses: AnalysisResult, EmailData
│ ├── header_analyzer.py # Email header heuristics
│ ├── body_analyzer.py # Email body heuristics
│ ├── url_analyzer.py # URL heuristics
│ └── engine.py # Orchestrator: runs all analysers, returns verdict
├── tests/
│ ├── __init__.py
│ ├── test_url_analyzer.py
│ ├── test_header_analyzer.py
│ └── test_engine.py # Integration tests (15 test cases)
├── main.py # CLI entry point
├── requirements.txt
├── .gitignore
└── LICENSE
```
## 安装说明
```
git clone https://github.com/SumitSonkusale/phishing-detector-python.git
cd phishing-detector-python
pip install -r requirements.txt
```
无外部运行时依赖 —— 仅使用 Python 标准库。`pytest` 和 `pytest-cov` 仅用于测试。
## 用法
### 分析 `.eml` 文件
```
python main.py email path/to/email.eml
```
### 直接分析 URL
```
python main.py url "http://secure-login.paypa1.com/verify"
```
### JSON 输出（用于流水线集成）
```
python main.py email path/to/email.eml --json
```
输出示例：
```
{
"verdict": "phishing",
"overall_score": 0.87,
"header_score": 0.75,
"body_score": 0.80,
"url_score": 0.95,
"indicators": [
"From/Reply-To domain mismatch",
"Urgency language detected",
"IP-based URL",
"Suspicious TLD"
]
}
```
## 工作原理
该工具使用由中央引擎协调的三个独立的启发式分析器：
| 分析器 | 检查内容 |
|---|---|
| `HeaderAnalyzer` | 域名对齐、身份验证标头 (SPF/DKIM/DMARC)、标头异常 |
| `BodyAnalyzer` | 紧迫/恐慌性短语、凭据提示、发件人冒充线索 |
| `UrlAnalyzer` | IP URL、punycode/同形异义域名、拼写抢注、编码字符、可疑的 TLD |
每个分析器都会返回一个标准化分数 (0.0–1.0) 和一系列触发的指标。引擎将这些内容聚合为加权总分，并将其映射到判定阈值。
## 运行测试
```
pytest tests/ --tb=short -q --cov=phishing_detector --cov-report=term-missing
```
测试套件涵盖了每个分析器模块的单元测试以及通过引擎进行的集成测试（共有 15 个测试用例）。
## CI
GitHub Actions 会在每次推送到 `main` 分支和发起 pull request 时运行完整的测试套件。请参阅 [`.github/workflows/test.yml`](.github/workflows/test.yml)。
## 许可证
[MIT](LICENSE)
标签：Python, 威胁情报, 安全规则引擎, 安全运营, 开发者工具, 扫描框架, 文档结构分析, 无后门, 构建工具, 逆向工具, 邮件分析, 钓鱼检测