nirvana58/phishgaurd

# 🔍 PhishGuard — URL 威胁扫描器 一个基于 CLI 的 URL 威胁检测系统，由机器学习异常检测、实时威胁情报 API、WHOIS 域名情报和多格式报告生成功能驱动 — 所有操作均可通过单一的交互式终端菜单进行控制。 ``` ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄██████████████████████████▄▄ ▄▄██████████████████████████████████▄▄ ▄██████████████ ██████████████▄ ▄████████████ ╔════════════╗ ████████████▄ ██████████ ║ ● ● ● ║ ██████████ █████████ ║ ◉◉◉◉◉ ║ █████████ █████████ ║ ◉ ▓▓▓ ◉ ║ █████████ █████████ ║ ◉◉◉◉◉ ║ █████████ ██████████ ║ ● ● ● ║ ██████████ ▀████████████ ╚════════════╝ ████████████▀ ▀██████████████ ██████████████▀ ▀▀██████████████████████████████████▀▀ ▀▀██████████████████████████▀▀ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ [ TARGET : incoming URL ] [ STATUS : SCANNING... ] [ ENGINE : PHISHGUARD ] [ THREAT : ANALYZING… ] ██████╗ ██╗ ██╗██╗███████╗██╗ ██╗ ██████╗ ██╗ ██╗ █████╗ ██████╗ ██████╗ ██╔══██╗██║ ██║██║██╔════╝██║ ██║██╔════╝ ██║ ██║██╔══██╗██╔══██╗██╔══██╗ ██████╔╝███████║██║███████╗███████║██║ ███╗██║ ██║███████║██████╔╝██║ ██║ ██╔═══╝ ██╔══██║██║╚════██║██╔══██║██║ ██║██║ ██║██╔══██║██╔══██╗██║ ██║ ██║ ██║ ██║██║███████║██║ ██║╚██████╔╝╚██████╔╝██║ ██║██║ ██║██████╔╝ ╚═╝ ╚═╝ ╚═╝╚═╝╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ``` ## 目录 - [概述](#overview) - [功能](#features) - [架构](#architecture) - [技术栈](#tech-stack) - [项目结构](#project-structure) - [安装说明](#installation) - [快速开始](#quick-start) - [用法](#usage) - [交互式菜单](#interactive-menu) - [直接 CLI 命令](#direct-cli-commands) - [训练模型](#training-the-model) - [管理面板 (Web)](#admin-panel-web) - [机器学习](#machine-learning) - [威胁情报源](#threat-intelligence-sources) - [报告格式](#report-formats) - [配置](#configuration) - [API 参考](#api-reference) ## 概述 PhishGuard 使用多层方法检测恶意 URL： 1. **ML 异常检测** — 基于 URL 结构特征训练的 K-means + 自组织映射 (SOM)。标记与已知正常模式相比在统计上显得异常的 URL。无需标注的数据集。 2. **外部威胁情报** — 并发查询 VirusTotal（70+ 防病毒引擎）、Google Safe Browsing（实时钓鱼/恶意软件）和 URLhaus（活跃的恶意软件分发 URL）。 3. **WHOIS / RDAP** — 域名年龄、注册商、国家、域名服务器、新注册域名检测 — 通过 HTTPS 进行（不依赖 43 端口）。 4. **报告生成** — 完整的扫描报告保存为 Markdown、PDF、DOCX 和 TXT 格式，每个情报源都有专门的部分。可通过本地 Ollama 生成可选的 LLM 叙述。 ## 功能 - **交互式终端菜单** — 方向键导航，无需记忆命令 - **单 URL 扫描** 支持实时轮询和即时结果显示 - **批量扫描** 从 `.txt` 或 `.csv` 文件执行 — 一个批次 ID，一份汇总报告 - **异步扫描流水线** — VT + Safe Browsing + URLhaus + WHOIS 全部并发触发 - **ML 异常评分** — K-means + SOM 独立运行；分歧将作为置信度信号呈现 - **基于 RDAP 的 WHOIS** — 使用 HTTPS（443 端口），无 43 端口防火墙问题 - **URLhaus 集成** — 在防病毒引擎之前捕获活跃的恶意软件分发 URL - **多格式报告** — `.md` `.txt` `.pdf` `.docx` + 丰富的终端输出 - **LLM 报告增强** — 本地 Ollama 生成威胁叙述（可选） - **Web 管理面板** — 仪表板、扫描历史、模型管理器、标签管理器、快速扫描 - **离线模型训练** — 从积累的扫描记录或任何 CSV 数据集中进行训练 - **模型热重载** — 无需重启服务器即可交换 ML 产物 - **任务取消** — 可在运行中途取消单个扫描或整个批次 - **WAL 模式 SQLite** — 支持并发读写；管理面板永远不会阻塞 CLI ## 架构 ``` Interactive Menu (cli/menu.py) │ │ HTTP (sync httpx) ▼ FastAPI Server (server/main.py + api.py) │ │ asyncio.Queue ▼ Scan Worker (server/queue_worker.py) │ │ asyncio.gather ──────────────────────────────────────┐ ▼ │ Feature Extraction ML Scoring External APIs │ (core/features.py) (core/models.py) │ 17 URL features K-means + SOM VirusTotal Safe Browsing │ synchronous synchronous URLhaus WHOIS/RDAP │ └───────────async─────────┘ │ ▼ Verdict Engine (server/scanner.py) Priority: Safe Browsing → URLhaus online → VT ≥3 → ML → WHOIS → SAFE │ ▼ Report Generator (report/generator.py) Terminal │ Markdown │ TXT │ PDF │ DOCX │ ▼ SQLite (WAL mode, QueuePool) scan_jobs │ batch_jobs │ feature_vectors │ feedback ``` ## 技术栈 | 层级 | 技术 | |---|---| | **服务器** | FastAPI, Uvicorn | | **数据库** | 通过 SQLModel 使用 SQLite (WAL 模式, QueuePool) | | **HTTP 客户端** | httpx (扫描器中为异步，CLI 中为同步) | | **ML — 聚类** | scikit-learn (K-means + StandardScaler) | | **ML — 拓扑** | MiniSom (自组织映射) | | **报告** | reportlab (PDF), python-docx (DOCX), rich (终端) | | **LLM** | Ollama (本地，可选) | | **CLI 菜单** | questionary + rich | | **WHOIS** | 基于 HTTPS 的 RDAP (rdap.org, rdap.iana.org, Verisign) | | **环境配置** | python-dotenv | ## 项目结构 ``` phishguard/ ├── server/ │ ├── main.py # App entry point, thread pool, lifespan │ ├── api.py # All API routes │ ├── scanner.py # Scan orchestrator (features → ML → APIs → verdict) │ ├── queue_worker.py # asyncio.Queue worker with cancellation │ ├── db.py # SQLModel schema, WAL mode, CRUD helpers │ ├── migrations.py # Idempotent schema migrations │ └── static/ │ └── admin.html # Web admin panel (single file) │ ├── core/ │ ├── features.py # URL → 17-feature vector (shared) │ ├── models.py # Loads artifacts, K-means + SOM scoring │ ├── whois_lookup.py # RDAP-first WHOIS, in-process cache │ └── urlhaus.py # URLhaus API client (URL + host lookup) │ ├── training/ │ ├── train.py # Offline training: DB / CSV streaming / feature CSV │ └── artifacts/ # scaler_*.pkl kmeans_*.pkl som_*.pkl latest.json │ ├── report/ │ └── generator.py # 5 renderers: terminal, md, txt, pdf, docx │ ├── cli/ │ ├── client.py # Direct CLI: scan, batch, cancel, admin, check-ollama │ └── menu.py # Interactive option-based terminal menu │ ├── reports/ # Generated report files saved here ├── data.db # SQLite database ├── .env # API keys (not committed) ├── .env.example # Key template └── requirements.txt ``` ## 安装说明 **要求：** Python 3.11+ ``` # 克隆仓库 git clone https://github.com/yourusername/phishguard.git cd phishguard # 安装依赖 pip install -r requirements.txt # 复制 env 模板并填入你的 API keys cp .env.example .env ``` **`.env` 文件：** ``` VIRUSTOTAL_API_KEY=your_virustotal_key_here GOOGLE_SAFE_BROWSING_API_KEY=your_google_key_here ``` ## 快速开始 ``` # 终端 1 — 启动服务器 uvicorn server.main:app --port 8000 # 终端 2 — 打开交互式菜单 python -m cli.menu ``` 菜单会自动连接到服务器，并显示实时的服务器状态指示灯。 ## 用法 ### 交互式菜单 ``` python -m cli.menu # 使用自定义服务器 URL python -m cli.menu --server http://192.168.1.100:8000 ``` ``` Main Menu: ❯ 🔍 Scan URL 📋 Check Scan Status ✕ Cancel Scan / Batch 📦 Batch Scan 🕑 Scan History 📄 Generate Report 🧠 Train Model ⚙️ Admin 🔧 Settings ❌ Exit ``` 使用方向键导航，按 Enter 键选择。每个选项仅会提示其所需的信息。 ### 直接 CLI 命令 对于脚本和自动化任务，请直接使用 `cli/client.py`： ``` # 扫描单个 URL python -m cli.client scan https://suspicious-site.tk # 使用 LLM 报告增强进行扫描 python -m cli.client scan https://example.com --llm # 仅扫描并保存特定格式 python -m cli.client scan https://example.com --formats md,pdf # 即发即忘（不等待结果） python -m cli.client scan https://example.com --async # 检查先前扫描的状态 python -m cli.client status # 为任何过往扫描重新生成报告 python -m cli.client report --formats pdf,docx # 取消正在运行的扫描 python -m cli.client cancel ``` **批量扫描：** ``` # 从纯文本文件（每行一个 URL） python -m cli.client batch urls.txt # 从 CSV 文件扫描 python -m cli.client batch urls.csv --column url # 带自定义分隔符的 CSV python -m cli.client batch data.csv --column website --delimiter ";" # 扫描前预览 CSV 列 python -m cli.client batch data.csv --preview # 批量为每个 URL 生成 LLM 摘要 python -m cli.client batch urls.csv --column url --llm # 取消整个批处理 python -m cli.client cancel-batch ``` **管理员命令：** ``` # 服务器统计信息 python -m cli.client admin stats # 重新训练后热重载 ML 模型 python -m cli.client admin reload # 为训练反馈标注扫描结果 python -m cli.client admin label malicious python -m cli.client admin label benign # 诊断 Ollama 连接 python -m cli.client check-ollama python -m cli.client check-ollama --test ``` ### 训练模型 PhishGuard 采用**离线训练** — 服务器仅加载预训练的产物。只要有足够的新数据就可以随时进行训练，然后无需重启即可热重载。 **基于积累的扫描数据进行训练（默认）：** ``` python -m training.train ``` **基于 URL 的 CSV 文件进行训练（无需扫描 — 自动提取特征）：** ``` # 使用 PhishTank 导出、URLhaus 下载或你自己的数据集 python -m training.train --csv phishtank.csv --url-column url # 同时将提取的特征向量保存到 DB 以便将来重用 python -m training.train --csv phishtank.csv --url-column url --save-to-db ``` **基于预计算的特征列进行训练：** ``` python -m training.train --csv features.csv --all-features python -m training.train --csv data.csv --feature-columns url_length,entropy,digit_ratio ``` **训练后进行热重载（无需重启服务器）：** ``` # 通过 CLI python -m cli.client admin reload # 通过管理面板 # 管理 → Model Manager → 重载 Model Artifacts ``` 对于大型数据集，训练过程会显示实时进度条。包含数百万行的文件将通过逐行处理的方式进行，无需将整个文件加载到内存中。 ### 管理面板 (Web) 在服务器运行时打开 [http://localhost:8000/admin](http://localhost:8000/admin)。 | 板块 | 功能说明 | |---|---| | **仪表板** | 判定结果的甜甜圈图、扫描计数、任务状态、最近的扫描 | | **扫描历史** | 可搜索/可过滤的所有扫描表格，可深入查看完整结果 | | **模型管理器** | 活跃模型版本、训练说明、一键热重载 | | **标签管理器** | 将扫描标记为恶意/良性，以构建训练反馈 | | **快速扫描** | 直接从浏览器提交 URL，结果内嵌显示 | ## 机器学习 ### 为什么使用无监督学习？ 恶意 URL 是一个不断变化的目标。基于昨天钓鱼域名训练的监督分类器无法捕捉到今天新注册的域名。PhishGuard 采用**异常检测** — 学习正常 URL 的样子并标记偏差 — 这样它就能在不需持续更新标注数据集的情况下捕捉新型威胁。 ### 特征向量（17 个特征） | 特征 | 测量内容 | |---|---| | `url_length` | URL 总字符数 | | `domain_length` | 主机/域名部分的长度 | | `path_length` | URL 路径的长度 | | `query_length` | 查询参数的长度 | | `num_subdomains` | 子域名深度 | | `num_dots` | 点的总数 | | `num_hyphens` | 连字符数量 | | `num_digits` | 数字数量 | | `digit_ratio` | 数字 / 总长度 | | `special_char_ratio` | 非字母数字字符 / 总长度 | | `shannon_entropy` | URL 字符串的随机性 (0–5+) | | `has_at_symbol` | 是否存在 `@` (隐藏真实目的地) | | `has_ip_host` | 使用 IP 地址而不是域名 | | `is_https` | 是否使用 HTTPS | | `suspicious_tld` | TLD 是否在已知不良列表中 (.tk .xyz .gq 等) | | `num_query_params` | `?key=value` 键值对的数量 | | `typosquat_distance` | 与最接近的热门域名的编辑距离 | ### K-means 聚类 根据 URL 的特征向量将其划分为 8 个簇 (K=8)。在扫描时，URL 会被分配到其最近的簇，并测量到该簇中心的距离。距离任何簇中心都很远的 URL 都是异常的。分数 > 1.0 = 明显异常。 ### 自组织映射 (SOM) 一个 10×10 的神经网格，用于学习 URL 特征空间的拓扑结构。相似的 URL 会落在附近的神经元上；不寻常的 URL 会落在稀疏、未填充的区域。**量化误差**（URL 向量到其最佳匹配单元的距离）即为异常信号。它可以捕捉到落在 K-means 簇*之间*、仅靠 K-means 会遗漏的 URL。 ### 综合评分 ``` combined_score = 0.5 × kmeans_score + 0.5 × som_score ``` 当两个模型都独立地将某个 URL 标记为异常时，结果将带有 `models_agree: true` 并且具有更高的置信度。当它们得出不同结论时，报告会明确将其标记为混合信号。 ## 威胁情报源 ### 判定优先级顺序 ``` 1. Google Safe Browsing → MALICIOUS (real-time, high authority) 2. URLhaus actively online → MALICIOUS 3. VirusTotal ≥ 3 engines → MALICIOUS 4. VT 1–2 engines + ML agree → SUSPICIOUS 5. ML combined score alone → SUSPICIOUS 6. WHOIS newly registered domain → SUSPICIOUS 7. No signals → SAFE ``` ### VirusTotal 使用 70 多个防病毒引擎检查 URL。需要免费的 API 密钥。最擅长捕捉具有既定特征码的已知恶意软件。 ### Google Safe Browsing 由 Google 维护的实时钓鱼、恶意软件和不需要的软件检测。需要免费的 API 密钥。 ### URLhaus (abuse.ch) 实时追踪积极分发恶意软件的 URL — 通常在防病毒引擎更新其特征码之前。**免费，无需 API 密钥。** 检查特定的 URL 和主机域名。URLhaus 中的“活跃在线”命中记录会立即触发 MALICIOUS 判定。 ### WHOIS / RDAP 通过基于 HTTPS 的 RDAP 获取域名注册情报（无需 43 端口）。返回域名年龄、注册商、国家、域名服务器数量，并标记新注册的域名（< 30 天） — 这是一个强烈的钓鱼指标。结果按域名缓存 1 小时。 ## 报告格式 每份报告都包含以下独立部分： 1. **概述** — URL、判定结果、置信度、扫描 ID、时间戳 2. **信号摘要** — 以项目符号列表形式列出所有判定原因 3. **ML 异常检测** — K-means 分数/聚类、SOM 分数/BMU、综合评分、一致性标志 4. **外部威胁情报** — VirusTotal 计数、Safe Browsing 威胁类型 5. **URLhaus** — URL 列表状态、威胁类型、恶意软件标签、主机 URL 计数、Spamhaus/SURBL 黑名单状态 6. **WHOIS 域名情报** — 注册商、国家、域名年龄（颜色编码）、到期时间、域名服务器、风险标志 7. **URL 特征分解** — 包含内嵌风险标记的全部 17 个特征 8. **AI 分析** *(可选)* — 通过本地 Ollama 生成的 LLM 威胁叙述 ### 格式选项 | 格式 | 说明 | |---|---| | **终端** | 丰富的色彩编码输出，包含表格、面板和内嵌标志 | | `.md` | 包含表格的完整 Markdown — 可在 GitHub、Obsidian 等平台上渲染 | | `.txt` | 纯文本，60 字符宽 — 随处可读，适合用于日志记录 | | `.pdf` | ReportLab — 专业的布局，带有样式化的表格和彩色判定标题 | | `.docx` | python-docx — 可编辑的 Word 文档，带有表格网格样式 | **批量报告** 会生成一份涵盖批次中所有 URL 的合并文件，包含每个 URL 的摘要表格和单独的详细信息部分。 ## 配置 ### 环境变量 | 变量 | 默认值 | 描述 | |---|---|---| | `VIRUSTOTAL_API_KEY` | — | VirusTotal API 密钥（可选） | | `GOOGLE_SAFE_BROWSING_API_KEY` | — | Google Safe Browsing 密钥（可选） | | `OLLAMA_MODEL` | 自动检测 | 用于 LLM 报告的 Ollama 模型 | | `OLLAMA_HOST` | `http://localhost:11434` | Ollama 服务器 URL | | `BATCH_MAX_URLS` | 无限制 | 每次批量提交的最大 URL 数量 | ### LLM 设置（可选） PhishGuard 可以使用通过 [Ollama](https://ollama.com) 本地运行的 LLM 生成的 AI 威胁叙述来增强报告。 ``` # 安装 Ollama（针对你的平台请参见 ollama.com） # 拉取模型 ollama pull llama3 # 启动 Ollama ollama serve # 诊断连接 python -m cli.client check-ollama --test # 在扫描中使用 LLM python -m cli.client scan https://example.com --llm ``` ### 运行服务器 ``` # 开发环境（代码更改时自动重载） uvicorn server.main:app --port 8000 --reload # 生产环境 uvicorn server.main:app --port 8000 --workers 1 ``` ## API 参考 | 方法 | 路由 | 描述 | |---|---|---| | `POST` | `/scan` | 提交 URL → `scan_id` | | `GET` | `/scan/{id}` | 轮询状态 + 结果 | | `POST` | `/scan/{id}/cancel` | 取消排队中/运行中的扫描 | | `GET` | `/scan/{id}/report?fmt=pdf` | 下载报告文件 | | `POST` | `/batch | 提交 URL 列表 → `batch_id` | | `GET` | `/batch/{id}?page=1&page_size=200` | 轮询批次进度（分页） | | `POST` | `/batch/{id}/cancel` | 取消批次中的所有扫描 | | `GET` | `/batch/{id}/report?fmt=md` | 下载批次报告 | | `POST` | `/admin/reload-model` | 热交换 ML 产物 | | `POST` | `/admin/label/{id}` | 将扫描标记为恶意/良性 | | `GET` | `/admin/stats` | 判定计数 + 模型版本 | | `GET` | `/admin/scans?limit=100` | 扫描历史 | | `GET` | `/admin` | Web 管理面板 | | `GET` | `/health` | 轻量级健康检查 | 在服务器运行时，可在 [http://localhost:8000/docs](http://localhost:8000/docs) 获取交互式 API 文档。 ## 依赖要求 ``` Python >= 3.11 fastapi==0.138.2 uvicorn==0.49.0 sqlmodel==0.0.39 httpx==0.28.1 python-dotenv==1.2.2 scikit-learn==1.8.0 MiniSom==2.3.6 rich==15.0.0 python-docx==1.2.0 reportlab==4.4.10 python-whois==0.9.6 questionary ollama==0.6.2 (optional — only needed for --llm) ``` 安装所有内容： ``` pip install -r requirements.txt ``` 由 Lakshmeesha Suvarna 构建

标签：AI风险缓解, Apex, AV绕过, FastAPI, URL威胁检测, 威胁情报, 开发者工具, 异步任务, 机器学习, 运行时操纵, 逆向工具