ItsDarker/ThreatDetector
GitHub: ItsDarker/ThreatDetector
一款面向 SOC 的 AI 驱动钓鱼 URL 检测与自动化响应仪表板，结合机器学习分类与威胁情报，实现从检测到处置的闭环安全运营流程。
Stars: 0 | Forks: 0
# ThreatDetector 🛡️
**基于 AI 的 URL 威胁检测与自动化响应系统**
一个先进的 SOC（安全运营中心）仪表板，利用机器学习检测钓鱼和恶意 URL，执行威胁情报检查，并自动生成安全响应。
## 🌟 功能特性
### 🔍 **智能威胁检测**
- **机器学习分类器**：准确率超过 90% 的 Random Forest 模型
- **置信度评分**：实时预测置信度（0-100%）
- **9 项特征分析**：URL 长度、特殊字符、协议、域名特征
- **快速处理**：每个 URL 检测时间约 10-50ms
### 🌐 **威胁情报**
- **VirusTotal 集成**：实时恶意软件检测查询
- **外部 API 检查**：全面的威胁信誉评分
- **速率限制感知**：妥善处理 API 配额管理
### 🚨 **自动化 SOAR 响应**
- **多步骤自动化**：智能响应链
- **严重性分类**：CRITICAL、MEDIUM、LOW 威胁等级
- **动作生成**：阻止、告警、工单、调查等工作流
### 📧 **邮件告警**
- **自动通知**：通过邮件发送钓鱼检测告警
- **智能配置**：基于环境变量的凭据管理（无硬编码）
- **专业格式**：包含完整上下文的丰富邮件模板
### 📊 **丰富的仪表板**
- **实时统计**：总扫描次数、钓鱼数量、合法 URL 数量
- **交互式图表**：检测概览和 7 天活动历史
- **持久化日志**：包含完整详细信息的最近 50 次扫描
- **数据导出**：将威胁日志下载为 CSV
- **自动刷新**：每 10-30 秒实时更新
### 💾 **持久化存储**
- **SQLite 数据库**：永久记录所有扫描日志
- **查询端点**：/stats、/logs、/activity 用于 API 访问
- **无数据丢失**：服务重启后数据依然保留
### 🔐 **生产就绪**
- **安全最佳实践**：输入验证、XSS 防护、SQL 注入防护
- **错误处理**：带有结构化日志的优雅故障处理
- **API 端点**：6 个用于集成的 RESTful 端点
- **健康检查**：服务器状态监控端点
## 📋 快速开始
### 前置条件
- Python 3.10 或更高版本
- pip 包管理器
### 安装说明
```
# 克隆 repository
git clone https://github.com/yourusername/threatdetector.git
cd threatdetector
# 安装 dependencies
pip install -r requirements.txt
# （可选）配置 email alerts
cp .env.example .env
# 使用您的 Gmail app-specific password 编辑 .env
```
### 运行应用
```
# 启动 server
python app.py
# 访问 dashboard
# 打开浏览器访问：http://localhost:5000
```
服务将在 `http://0.0.0.0:5000` 上启动，并可通过 `http://localhost:5000` 访问
## 🖥️ Web 界面
赛博朋克主题仪表板提供以下功能：
```
┌─ THREATDETECTOR ────────────────────────────────────┐
│ SYSTEM ONLINE│
├──────────────────────────────────────────────────────┤
│ // URL THREAT SCANNER │
│ [https://suspicious-url.com ] [▶ SCAN] │
│ │
│ Detection Result: Phishing Confidence: 87.3% │
│ Threat Intel: Malicious Action: BLOCK... │
├──────────────────────────────────────────────────────┤
│ Total Scans: 42 Legitimate: 27 Phishing: 15 │
├──────────────────────────────────────────────────────┤
│ [Detection Overview Chart] [7-Day Activity Chart] │
├──────────────────────────────────────────────────────┤
│ Threat Logs (Last 50 Scans) │
│ URL | Result | Time │
│ suspicious.com | Phishing | 14:32:15 │
│ google.com | Legitimate | 14:31:45 │
└──────────────────────────────────────────────────────┘
```
## 🔌 API 端点
### 仪表板
```
GET /
```
返回 Web 仪表板 HTML。
### 扫描 URL
```
POST /scan
Content-Type: application/json
{
"url": "https://example.com/suspicious-path"
}
```
**响应：**
```
{
"url": "https://example.com/suspicious-path",
"result": "Phishing",
"confidence": 87.3,
"intel": "Malicious according to VirusTotal",
"action": "[BLOCK] URL: ... | [ALERT] SOC team notified | [TICKET] ... | [INVESTIGATE]...",
"severity": "CRITICAL",
"time": "2026-05-12 19:31:32"
}
```
### 获取威胁日志
```
GET /logs
```
返回最近 50 条威胁日志条目的数组：
```
[
{
"url": "http://phishing-site.com",
"result": "Phishing",
"action": "[BLOCK] URL: ... | ...",
"time": "2026-05-12 19:31:32"
}
]
```
### 获取统计信息
```
GET /stats
```
返回整体威胁统计信息：
```
{
"total": 42,
"phishing": 15,
"legitimate": 27
}
```
### 获取活动数据
```
GET /activity
```
返回过去 7 天的扫描活动数据：
```
[
{"date": "2026-05-12", "count": 12},
{"date": "2026-05-11", "count": 8}
]
```
### 健康检查
```
GET /health
```
返回服务器状态：
```
{
"status": "healthy",
"timestamp": "2026-05-12T19:31:32.123456"
}
```
## ⚙️ 配置
### 环境变量
基于 `.env.example` 创建一个 `.env` 文件：
```
# Email 配置（用于 phishing alerts）
EMAIL_SENDER=your_email@gmail.com
EMAIL_PASSWORD=your_app_specific_password
# Threat Intelligence API
VIRUSTOTAL_API_KEY=your_virustotal_key
# Flask
FLASK_ENV=production
FLASK_DEBUG=False
# Database
DATABASE_PATH=threat_logs.db
# Server
HOST=0.0.0.0
PORT=5000
```
**注意**：请使用 [Gmail 应用密码](https://support.google.com/accounts/answer/185833) 而不是您的主密码。
## 🏗️ 架构
```
┌─────────────────────────────────────────────────┐
│ Web Dashboard (HTML/CSS/JS) │
│ Real-time Charts & Threat Logs │
└────────────────────┬────────────────────────────┘
│
┌────────────────────┴────────────────────────────┐
│ Flask REST API (7 Endpoints) │
├─────────────────────────────────────────────────┤
│ ML Detection │ Threat Intel │ SOAR Engine │
├────────────────┼────────────────┼──────────────┤
│ • RandomForest │ • VirusTotal │ • Block URL │
│ • 9 Features │ • URL Lookup │ • Alert Team │
│ • Confidence │ • Reputation │ • Create TKT │
└────────────────┼────────────────┼──────────────┘
│
┌────────┴────────┐
│ │
┌────▼─────┐ ┌──────▼──────┐
│ SQLite │ │Email Alert │
│ Database │ │via SMTP │
└──────────┘ └─────────────┘
```
## 📊 系统统计
| 组件 | 技术 | 详情 |
|-----------|-----------|---------|
| **后端** | Flask 2.3.3 | 轻量级，生产就绪 |
| **ML 模型** | scikit-learn | Random Forest 分类器 (200 棵树) |
| **数据库** | SQLite3 | 持久化威胁日志记录 |
| **前端** | HTML/CSS/JS | 赛博朋克主题，响应式设计 |
| **图表** | Chart.js | 实时数据可视化 |
| **外部 API** | VirusTotal v3 | 威胁情报查询 |
## 🔒 安全特性
✅ **输入验证** - 处理前的 URL 格式验证
✅ **SQL 注入防护** - 参数化数据库查询
✅ **XSS 防护** - 前端正确的 HTML 转义
✅ **密钥管理** - 通过环境变量管理凭据
✅ **API 超时** - 外部请求 10 秒超时限制
✅ **错误处理** - 错误消息中不包含敏感信息
✅ **禁用调试** - 生产安全的默认配置
✅ **结构化日志** - 全面的审计跟踪
## 📈 性能
- **ML 检测**：每个 URL 约 10-50ms
- **VirusTotal 查询**：1-5 秒（带超时）
- **数据库查询**：<100ms
- **仪表板刷新**：每 10-30 秒自动更新
- **并发用户**：已通过 10 个以上并发请求测试
## 📦 依赖项
```
Flask==2.3.3 # Web framework
pandas==2.1.4 # Data processing
scikit-learn==1.3.2 # Machine learning
joblib==1.3.2 # Model serialization
requests==2.31.0 # HTTP client
numpy==1.24.3 # Numerical computing
python-dotenv==1.0.0 # Environment config
gunicorn==21.2.0 # Production server
```
## 🚀 部署
### 本地开发
```
python app.py
```
### 使用 Gunicorn 进行生产部署
```
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```
### Docker 部署
```
FROM python:3.10-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5000", "app:app"]
```
### Nginx 反向代理
```
server {
listen 80;
server_name threatdetector.example.com;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
## 📝 日志
所有操作均记录至：
- **文件**：`logs/threatdetector.log`
- **控制台**：stdout/stderr
日志格式：
```
2026-05-12 19:31:32,006 - __main__ - INFO - Scanning URL: http://example.com
2026-05-12 19:31:33,123 - __main__ - INFO - Scan complete - Result: Phishing, Confidence: 87.3%
```
## 🔬 测试
### 测试 ML 检测
```
python -c "from ml_model import detect_phishing; print(detect_phishing('http://paypal-secure.com'))"
```
### 测试数据库
```
python -c "from database import get_stats; print(get_stats())"
```
### 测试 API
```
curl -X POST http://localhost:5000/scan \
-H "Content-Type: application/json" \
-d '{"url": "http://suspicious.com"}'
```
## 📚 文档
- **代码注释**：所有模块中的内联文档
- **API 文档**：此 README 中的请求/响应示例
- **日志**：查看 `logs/threatdetector.log` 了解操作详情
- **配置**：参阅 `.env.example` 了解所有选项
## 🤝 贡献
欢迎贡献！可改进的方向包括：
- [ ] 扩展威胁情报来源（URLhaus、PhishTank）
- [ ] 增加 ML 训练数据集（10,000+ 个 URL）
- [ ] 添加 WebSocket 以实现实时更新
- [ ] 实现用户身份验证
- [ ] 添加更多图表类型和指标
- [ ] 迁移到 PostgreSQL 以适应生产环境
- [ ] 创建 Docker/Kubernetes 部署文件
## 📄 许可证
本项目基于 MIT 许可证授权。详情请参阅 LICENSE 文件。
## 🙏 致谢
- **scikit-learn** - 机器学习库
- **Flask** - Web 框架
- **VirusTotal** - 威胁情报数据
- **Chart.js** - 数据可视化
## 📞 支持
如有问题、疑问或建议：
1. 检查日志：`tail -f logs/threatdetector.log`
2. 查看 API 响应中的错误消息
3. 确认环境变量设置正确
4. 使用 curl 单独测试各端点
## 🔮 路线图
**v1.1**（下一版本）
- [ ] WebSocket 实时更新
- [ ] 用户身份验证与角色管理
- [ ] 高级过滤与搜索
- [ ] 自定义威胁评分规则
**v1.2**（未来版本）
- [ ] PostgreSQL 支持
- [ ] Redis 缓存层
- [ ] 微服务架构
- [ ] Kubernetes 部署
- [ ] 移动端应用
**v2.0**（长期计划）
- [ ] 深度学习模型
- [ ] 高级 SOAR 集成
- [ ] 事件管理系统
- [ ] 合规性报告
- [ ] 多租户支持
## 📊 项目统计
- **代码行数**：1,000+
- **API 端点**：6
- **数据库表**：1
- **仪表板图表**：2
- **功能特性**：20+
- **测试覆盖**：ML + DB + API 已验证
**用 ❤️ 为威胁猎手和安全分析师而构建**
*最后更新：2026-05-12*
标签：AI安全, Apex, API集成, Ask搜索, Chat Copilot, Flask, Go语言工具, Python, scikit-learn, SOAR, SOC仪表盘, URL分析, VirusTotal, Web安全, 可观测性, 后端开发, 威胁情报, 安全运营中心, 开发者工具, 恶意URL检测, 无后门, 机器学习, 网络安全, 网络映射, 网络测绘, 自动响应, 蓝队分析, 请求拦截, 逆向工具, 邮件告警, 钓鱼检测, 随机森林, 隐私保护