arunsakthi2802-star/-Intelligence-Phishing-Detection-System
GitHub: arunsakthi2802-star/-Intelligence-Phishing-Detection-System
一个基于机器学习的全栈钓鱼检测平台，通过对 URL、网页内容和电子邮件进行多向量安全分析来识别和评分恶意威胁。
Stars: 0 | Forks: 0
# 🛡️ 智能钓鱼检测系统
一个从头构建的企业级、AI 驱动的网络安全威胁情报平台。该系统从 URL、动态网页抓取内容和原始电子邮件资产中提取并分析安全向量，利用机器学习来识别、评分和诊断恶意的钓鱼向量。
## 🏗️ 架构与系统图表
### 1. 统一架构流程
```
graph TD
Client[Next.js 15 Client App] <-->|JSON / JWT Auth| FastAPI[FastAPI Backend Server]
FastAPI <-->|Async Motor| DB[MongoDB Database]
FastAPI -->|Extracts Features| URL[URL Analyzer]
FastAPI -->|Extracts HTML/CSS/JS| Scrap[Website Scraper]
FastAPI -->|Parses Headers & Links| Email[Email Analyzer]
URL & Scrap & Email -->|Vector Matrix| ML[ML Prediction Inference Engine]
ML <-->|Load / Retrain| SavedModel[phishing_detector.joblib]
```
### 2. 实体关系图 (ERD)
```
erDiagram
User {
string email PK
string password
boolean is_active
boolean is_admin
datetime created_at
}
OTP {
string email FK
string code
datetime expires_at
boolean is_verified
}
ScanReport {
string id PK
string target
string scan_type
string status
integer score
float confidence
json details
string created_by FK
datetime created_at
}
BlockedDomain {
string domain PK
string reason
datetime created_at
}
ThreatIntel {
string indicator PK
string type
string severity
string source
datetime created_at
}
AuditLog {
string id PK
string user_id FK
string action
string ip_address
datetime created_at
}
User ||--o{ ScanReport : creates
User ||--o{ AuditLog : triggers
User ||--o{ OTP : requests
```
### 3. 验证扫描流程图
```
flowchart TD
Start[User Submits Target URL/Email] --> Type{Scan Type?}
Type -->|URL| A[Run Lexical Checks] --> B[Resolve DNS & SSL Cert] --> C[Query WHOIS age]
Type -->|Website| A --> B --> C --> D[Scrape HTML Forms, iFrames & brand indicators]
Type -->|Email| E[Parse Headers, DKIM, SPF] --> F[Extract Attachments & Urgency Keywords] --> G[Inspect Embedded Links via URL Engine]
C --> H[Assemble Feature Vector]
D --> H
G --> H
H --> I[Execute ML Classifier Prediction]
I --> J[Check Admin Blocked List]
J --> K[Generate Risk Score & Confidence]
K --> Save[Save ScanReport to MongoDB]
Save --> End[Return Diagnostics to Client]
```
## 🌟 核心功能与特性
### 🔍 1. 多向量安全检测引擎
- **URL 词法与网络分析器**：扫描 URL 的结构异常（长度、子域名、特殊字符比例、Punycode 编码、域名抢注向量），并执行实时 DNS 查询、SSL 证书有效性检查以及基于 Socket 的 WHOIS 域名年龄查询。
- **动态网站抓取器**：安全获取目标网页的 HTML，通过分析文档布局和脚本来发现密码收集表单、iframe 重定向结构、不安全的表单 endpoint（`action="http://..."`）以及品牌伪造页面。
- **深度电子邮件解析器**：检查原始电子邮件内容（`.eml` 格式或正文文本），解析 header 中的 SPF、DKIM 和 DMARC 安全标记，标记高紧急性关键词，并提取嵌入的超链接重新输入到 URL 扫描引擎中。
### 🤖 2. 机器学习威胁推断
- 结合多个分类器的预测结果：**Logistic Regression、Decision Trees、Random Forests、XGBoost 和 LightGBM**。
- 提供对 **CatBoost** 的动态支持（已安装且完全兼容）。
- 基于 F1-score 评估指标，自动选择并保存表现绝对最佳的模型。
- 完全具备自动化的后台重训 pipeline，可汇总性能统计数据并对 ROC 曲线坐标进行降采样，以实现最佳的渲染速度。
### 📊 3. 现代安全仪表盘与分析
- 响应式 Next.js 应用程序，采用高级网络情报暗色玻璃拟态设计构建。
- 交互式 SVG 风险仪表、指标报告、被拦截域名过滤器以及实时扫描日志。
### 🛡️ 4. 管理控制与审计事件记录
- **被拦截域名列表**：立即拦截特定的高风险域名通过安全扫描。
- **审计日志**：保留分析师操作（登录、切换管理员状态、拉黑域名、触发 ML 训练）的不可变追踪记录。
- **ML 重训中心**：允许管理员在后台触发重训任务，以生成全新的分类器模型。
## 📁 仓库目录映射
```
PROJECT ROOT/
├── docker-compose.yml # Multi-container Orchestrator (FastAPI, Next.js, Mongo, Redis)
├── README.md # Comprehensive Project Documentation
│
├── backend/ # FastAPI Backend Application Directory
│ ├── Dockerfile # Container instructions (Python 3.11 base)
│ ├── requirements.txt # Python dependencies (includes scikit-learn, xgboost, lightgbm, etc.)
│ ├── test_backend.py # Integration testing suite
│ └── app/ # Main Application Code
│ ├── main.py # FastAPI Application configurations & Routers
│ ├── database.py # MongoDB connection with asynchronous fallback database
│ ├── schemas.py # Pydantic schemas for data validation
│ │
│ ├── core/
│ │ └── security.py # JWT Tokens & Cryptographic utilities (Bcrypt)
│ │
│ ├── ml/
│ │ ├── train.py # Pipelines to train and serialize the ML classifiers
│ │ ├── model_metrics.json # Cached metrics and ROC data (JSON-safe formatted)
│ │ └── phishing_detector.joblib # Saved best model binaries
│ │
│ ├── routes/
│ │ ├── auth.py # User authentication, OTP verification, and JWT signup routes
│ │ ├── scan.py # Scans URLs, websites, and emails; saves results
│ │ ├── dashboard.py # Fetches platform analytics statistics
│ │ └── admin.py # User management, blocklists, audit logs, and metrics routes
│ │
│ └── services/
│ ├── url_analyzer.py # URL lexical and network scanner logic
│ ├── website_analyzer.py # HTML scraping and form scanner logic
│ ├── email_analyzer.py # EML parsing and authentication header checks
│ └── ml_service.py # Heuristics + ML Model inference router
│
└── frontend/ # Next.js Frontend Application Directory
├── Dockerfile # Production Next.js container instructions
├── package.json # Project dependencies and script endpoints
├── next.config.ts # Next.js configurations
├── tailwind.config.ts # Styling tokens
└── src/
└── app/
├── layout.tsx # Main application page layout
├── globals.css # Custom animations & glassmorphic grid stylings
└── page.tsx # Phishing Scanner Dashboard (Scanner, Analytics, Admin)
```
## ⚡ 设置与执行指南
### 选项 1：本地设置（推荐用于开发）
#### 1. 设置并运行后端
1. 打开终端并导航至 `backend` 文件夹：
cd backend
2. 安装 Python 包：
pip install -r requirements.txt
3. 运行初始训练脚本以生成 ML 分类器二进制文件：
python app/ml/train.py
4. 启动 FastAPI 开发服务器：
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
*注意：如果 MongoDB 未在您的主机上运行，后端将自动初始化**内存数据库回退**，允许您无需配置 MongoDB 即可立即测试登录、注册、扫描和管理功能！*
#### 2. 设置并运行前端
1. 打开一个新的终端并导航至 `frontend` 文件夹：
cd frontend
2. 安装 Node 包：
npm install --legacy-peer-deps
3. 启动 Next.js 开发服务器：
npm run dev
4. 打开浏览器并导航至 `http://localhost:3000`。
### 选项 2：完全 Docker 编排
要在 Docker 中独立运行整个技术栈（FastAPI、Next.js、MongoDB、Redis）：
1. 在根目录中构建并启动所有服务：
docker-compose up --build
2. 启动完成后：
- 访问 Next.js 前端：`http://localhost:3000`
- 访问 FastAPI Swagger 文档：`http://localhost:8000/docs`
## 📖 管理员与操作手册
### 🧑💻 默认账户与凭证
- **默认管理员账户**：当在干净的数据库上首次启动后端时，系统会注册一个默认管理员：
- **电子邮件地址**：`admin@phishdetect.ai`
- **密码**：`admin123`
- **分析师注册**：如果您注册了一名新分析师，请检查正在运行后端的终端/控制台；您将在日志中看到打印出的生成的 6 位 OTP 代码，以完成注册。
### 🧪 API Endpoint 参考
| 方法 | Endpoint | 描述 | 认证 |
| :--- | :--- | :--- | :--- |
| **POST** | `/api/auth/register` | 注册新的安全分析师 | 无 |
| **POST** | `/api/auth/login` | 登录并获取 JWT 访问令牌 | 无 |
| **POST** | `/api/auth/verify-otp` | 验证注册或密码重置 OTP | 无 |
| **POST** | `/api/scan/url` | 提交目标 URL 进行词法/网络扫描 | User JWT |
| **POST** | `/api/scan/website` | 抓取并检查网站布局的安全性 | User JWT |
| **POST** | `/api/scan/email` | 上传 `.eml` 文件或原始文本以检查 header/链接 | User JWT |
| **GET** | `/api/dashboard/stats` | 获取实时仪表盘分析计数器 | User JWT |
| **GET** | `/api/admin/users` | 列出所有已注册的分析师资料 | Admin JWT |
| **GET** | `/api/admin/model-metrics` | 获取 ML 性能指标和 ROC 曲线 | Admin JWT |
| **POST** | `/api/admin/model-retrain` | 触发 ML 模型的后台训练任务 | Admin JWT |
## 🛠️ 维护与故障排除
### 1. 本地编辑器中出现 "Cannot find module 'catboost'"
该项目构建为在运行时动态检查 `catboost` 导入，因此即使缺少该包也能运行。但是，您编辑器的静态类型检查 linter 可能会标记此导入。
- **解决方法**：在您的 Python 环境中安装 `catboost`：
pip install catboost
### 2. "ValueError: 超出范围的浮点数值不符合 JSON 规范: inf"
当模型达到 100% 的准确率时，scikit-learn 的 `roc_curve` 会返回 `Infinity` 作为第一个阈值。Python 的标准 `json` 模块会将其保存在 `model_metrics.json` 中，但 Starlette 的 `JSONResponse` 会拒绝它并抛出 `500 Server Error`。
- **解决方法**：系统现在在 `admin.py` 和 `train.py` 中包含了自动清理处理器，可以递归清理加载的指标文件，并将无限值替换为符合 JSON 标准的 `null` 值。
标签：Apex, AV绕过, FastAPI, MongoDB, 威胁情报, 开发者工具, 搜索引擎查询, 搜索语句（dork）, 机器学习, 网络安全, 请求拦截, 逆向工具, 配置审计, 钓鱼检测, 隐私保护