anupam2150/PhishGuard

# 🛡️ PhishGuard 一个基于 Python 和 Django 构建的**全栈钓鱼检测与威胁情报平台**。       🔗 **在线演示：** [https://phishguard-tool.onrender.com](https://phishguard-tool.onrender.com) ## 📌 功能 ### 🔗 URL/域名钓鱼扫描器 - 对比 **VirusTotal**（90+ 杀毒引擎）扫描 URL，响应缓存 1 小时 - 检查 **Google Safe Browsing** 威胁数据库（30 分钟缓存） - 检查 **PhishTank** — 实时 API 或免费离线每日数据库（无每次请求配额） - 执行 **WHOIS 查询**获取域名年龄和注册商信息 - **SSL/TLS 证书分析** — 颁发者、有效期、SAN、自签名检测、风险标记 - 计算风险等级：`LOW` / `MEDIUM` / `HIGH` / `CRITICAL` - **PDF 报告导出**（WeasyPrint）— 包含所有扫描数据的专业 A4 报告 - **截图捕获**（APIFlash + html2image 备用方案）用于 HIGH/CRITICAL 结果 - ⚡ 当结果从 Redis 缓存提供时显示缓存徽章 - 每个结果均可复制到剪贴板并生成可分享的永久链接 ### 📧 邮件头分析器 - 使用 Python 的 `email` 标准库解析原始邮件头 - 检测 **SPF**、**DKIM**、**DMARC** 通过/失败结果 - 统计转发跳数并检测可疑标记 ### 🔍 威胁情报查询 - 自动检测指标类型：**IP / 域名 / URL / 哈希** - 对所有指标类型查询 **VirusTotal API v3**（1 小时缓存） - 查询 **AbuseIPDB** 获取 IP 滥用置信度评分（2 小时缓存） - 查询 **URLhaus**（abuse.ch）— 免费，无需密钥（2 小时缓存） - 查询 **Shodan** 获取开放端口、CVE、服务横幅（24 小时缓存） ### 🕸️ 钓鱼活动关联器 - 接受 2–100 个 URL 并将它们分组为协调攻击活动 - 使用 **Union-Find 算法**结合加权信号 - **D3.js 力导向网络图**显示域名 → IP → 托管关系 - 导出结果为 JSON ### 📦 批量 URL 扫描器 - 上传包含最多 500 个 URL 的 `.txt` 或 `.csv` 文件 - 通过 **Celery** 工作进程后台处理（Upstash Redis 作为消息代理） - 每 3 秒轮询实时进度条 - 风险筛选标签页、CSV 报告下载 - 速率限制：每小时 5 次上传 ### 👁️ 监控列表与监控 - 将域名、IP 或 URL 添加到个人监控列表 - **APScheduler** 每 6 小时重新扫描（在 Web 进程内运行） - 风险等级变化时创建 `WatchlistAlert` - 通过 Django 的 `send_mail()` 发送邮件提醒 - 侧边栏徽章显示未确认的提醒数量 ### 📊 仪表盘 - 面向当前用户的实时统计 - 风险分布**环形图**（Chart.js） - **14 天扫描活动折线图** — 按风险等级分类，带颜色标识 - **前 10 威胁域名柱状图** — 最近 30 天 - **威胁地图**（Leaflet.js + CARTO Dark Matter 瓦片）— 定位 HIGH/CRITICAL IP 的地理坐标 - 带自动类型检测的快速扫描栏 - 跨所有扫描历史的全局搜索 ### 🔌 REST API - 位于 `/api/` 的完整 DRF API，支持 **JWT 认证**（SimpleJWT） - `POST /api/scan/` — 运行完整扫描管道 - `POST /api/intel/` — 运行威胁情报查询 - `POST /api/correlate/` — 运行关联管道 - `GET /api/stats/` — 用户扫描统计 - 所有资源的分页列表/详情端点 - 速率限制：100 次/天（已认证），10 次/天（匿名） ### 🔐 用户认证与隐私 - Django 认证 — 注册、登录、登出（基于 POST 的登出，带 CSRF 保护） - 安全的会话管理，登出后正确重定向 - `UserProfile` 包含加密的每用户 API 密钥（Fernet AES） - 使用自己密钥的用户获得独立的速率限制 - 个人 API 密钥（UUID）仅对管理员/员工可见 - 所有扫描结果、情报报告和邮件分析均**按用户私有** - 未认证用户只能在仪表盘上看到 HIGH/CRITICAL 威胁域名（无链接，无个人数据） - 未认证用户尝试使用任何功能时显示登录/注册弹窗 - 侧边栏计数在登录/登出时重置为 0 — 按用户范围 ### ✨ 优化体验 - 永久深色主题 - 自定义 404、500、429 错误页面 - PWA 清单 + 网站图标 - 所有 IOC 上的复制到剪贴板按钮 - 每个扫描结果上的可分享永久链接 ## 🖥️ 技术栈 | 层级 | 技术 | |---|---| | 后端 | Python 3.14+, Django 5.x | | 任务队列 | Celery 5.x + Upstash Redis | | 调度 | APScheduler + django-apscheduler | | 前端 | Bootstrap 5.3, Chart.js, D3.js v7, Leaflet.js | | 数据库 | SQLite（开发）/ PostgreSQL（生产，通过 dj-database-url）| | 缓存 | Upstash Redis（生产）/ LocMemCache（开发）| | API | Django REST Framework + SimpleJWT | | PDF | WeasyPrint | | 错误追踪 | Sentry SDK | | 部署 | Render（Web + Worker 服务）| ## 🚀 快速开始 ### 1. 克隆仓库 ``` git clone https://github.com/anupam2150/PhishGuard.git cd PhishGuard ``` ### 2. 安装依赖 ``` pip install -r requirements.txt ``` ### 3. 配置环境变量 ``` copy .env.example .env # Windows cp .env.example .env # macOS/Linux ``` 编辑 `.env` — 本地开发最低要求： ``` DJANGO_SECRET_KEY=your-secret-key-here DEBUG=True FIELD_ENCRYPTION_KEY= VT_API_KEY=your-virustotal-api-key ``` 生成密钥： ``` # Django 密钥 python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())" # Fernet 加密密钥 python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" ``` ### 4. 运行迁移 ``` python manage.py migrate ``` ### 5. 收集静态文件 ``` python manage.py collectstatic --noinput ``` ### 6. 启动开发服务器 ``` python manage.py runserver ``` ### 7.（可选）启动 Celery 工作进程用于批量扫描 ``` celery -A phishguard worker --loglevel=info --concurrency=2 ``` 访问 `http://127.0.0.1:8000` ## 🔑 API 密钥 | 服务 | 获取位置 | 免费额度 | 用途 | |---|---|---|---| | VirusTotal | [virustotal.com](https://www.virustotal.com/gui/join-us) | 4 次/分钟，500 次/天 | 扫描器、情报、批量 | | AbuseIPDB | [abuseipdb.com](https://www.abuseipdb.com/register) | 1,000 次/天 | 情报（IP）| | Google Safe Browsing | [console.cloud.google.com](https://console.cloud.google.com) | 免费 | 扫描器 | | NewsAPI | [newsapi.org/register](https://newsapi.org/register) | 100 次/天 | 新闻面板 | | PhishTank | [phishtank.com](https://www.phishtank.com/api_register.php) | 可选 | 扫描器（离线数据库无需密钥）| | Shodan | [shodan.io](https://account.shodan.io/register) | 有限免费 | 情报（IP）| | APIFlash | [apiflash.com](https://apiflash.com) | 500 次/月 | 截图 | | Upstash Redis | [console.upstash.com](https://console.upstash.com) | 免费额度 | 缓存 + Celery 消息代理 | | Sentry | [sentry.io](https://sentry.io) | 免费额度 | 错误追踪 | ## 🚢 部署到 Render ### Web 服务 - **构建命令：** `./build.sh` - **启动命令：** `gorn phishguard.wsgi:application --workers 2 --timeout 120` - `Procfile` 的 release 命令在每次部署时自动运行 `migrate` - `collectstatic` 在构建期间通过 `build.sh` 运行 ### Worker 服务（用于批量扫描器） - **构建命令：** `pip install -r requirements.txt` - **启动命令：** `celery -A phishguard worker --loglevel=info --concurrency=2 --max-tasks-per-child=50` - 环境变量与 Web 服务相同 ### 数据库 - 添加一个 **Render PostgreSQL** 实例 - 将**内部数据库 URL** 复制为两个服务中的 `DATABASE_URL` ### Redis - 在 [console.upstash.com](https://console.upstash.com) 创建一个免费的 **Upstash Redis** 数据库 - 将 `rediss://` TLS URL 复制为 `REDIS_URL` ### Render 上所需的环境变量 ``` DEBUG=False ALLOWED_HOSTS=your-app.onrender.com SITE_URL=https://your-app.onrender.com DATABASE_URL=postgresql://... REDIS_URL=rediss://... DJANGO_SECRET_KEY= FIELD_ENCRYPTION_KEY= VT_API_KEY= ABUSEIPDB_KEY= GSB_API_KEY= SHODAN_API_KEY= NEWS_API_KEY= ``` ## 📁 项目结构 ``` PhishGuard/ ├── phishguard/ # Django project config │ ├── settings.py # All settings (DB, cache, Celery, DRF, Sentry) │ ├── urls.py # Root URL config + handler404/500 │ ├── views.py # Custom 404, 500, 429 handlers │ ├── celery.py # Celery app │ └── context_processors.py ├── accounts/ # Auth + encrypted API key management ├── scanner/ # URL/domain phishing scanner ├── emailparser/ # Email header analyzer ├── intel/ # Threat intelligence lookup ├── correlation/ # Phishing campaign correlator ├── bulk_scanner/ # Bulk URL scanner (Celery tasks) ├── watchlist/ # Watchlist + APScheduler monitoring ├── dashboard/ # Overview, charts, threat map, search ├── api/ # DRF REST API ├── services/ # Shared external API clients (all cached) │ ├── virustotal.py # VirusTotal (1h cache) │ ├── abuseipdb.py # AbuseIPDB (2h cache) │ ├── safebrowsing.py # Google Safe Browsing (30m cache) │ ├── urlhaus.py # URLhaus / abuse.ch (2h cache) │ ├── phishtank.py # PhishTank live + offline DB │ ├── shodan_service.py # Shodan host intel (24h cache) │ ├── ssl_analyzer.py # SSL/TLS certificate analysis │ ├── screenshot.py # APIFlash + html2image screenshots │ ├── pdf_reporter.py # WeasyPrint PDF generation │ └── api_key_resolver.py # Per-user API key resolution ├── templates/ # Shared templates (base, 404, 500, 429) │ └── reports/ # PDF report template ├── static/ │ ├── css/custom.css # Dark theme │ ├── favicon.ico │ └── manifest.json # PWA manifest ├── build.sh # Render build script ├── .env.example ├── requirements.txt └── Procfile # Render deployment (web + worker + release) ``` ## 📸 页面 | 页面 | URL | |---|---| | 仪表盘 | `/` | | 威胁地图 | `/threat-map/` | | URL 扫描器 | `/scanner/` | | 邮件分析器 | `/email/` | | 威胁情报 | `/intel/` | | 活动关联器 | `/correlation/` | | 批量扫描器 | `/bulk/` | | 监控列表 | `/watchlist/` | | 监控提醒 | `/watchlist/alerts/` | | REST API 根 | `/api/` | | 个人资料 / API 密钥 | `/accounts/profile/` | | 管理面板 | `/admin/` | ## 🔌 REST API 快速参考 ``` # 获取 JWT 令牌 curl -X POST /api/token/ \ -H "Content-Type: application/json" \ -d '{"username": "you", "password": "pass"}' # 扫描 URL curl -X POST /api/scan/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"url": "https://suspicious.example.com"}' # 威胁情报查询 curl -X POST /api/intel/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"indicator": "1.2.3.4"}' # 关联 URL curl -X POST /api/correlate/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"urls": ["https://a.com", "https://b.com"], "label": "test"}' # 获取扫描历史（按风险筛选） curl "/api/scans/?risk=HIGH" \ -H "Authorization: Bearer " # 获取用户统计 curl /api/stats/ \ -H "Authorization: Bearer " ``` ## ⚠️ 免责声明 此工具仅用于**教育和防御性安全目的**。 未经适当授权，请勿使用它来扫描系统或 URL。 ## 📝 最近更新 ### v1.1.0（最新） - **修复：** 登出重定向问题 — 现在登出后正确重定向到仪表盘 - **安全：** 登出现在使用 POST 方法并带 CSRF 保护，而非 GET - **用户体验：** 登出时添加成功消息确认 - **改进：** 会话管理和认证流程 ## 📄 许可证 MIT 许可证 — 欢迎使用、修改和分发。