hx010207/PishBIN-Gaurd
GitHub: hx010207/PishBIN-Gaurd
一个开源的统一网络威胁分析平台，结合本地启发式规则与外部威胁情报 API，实现钓鱼 URL 检测和 PE 二进制文件静态分析的一站式安全研判。
Stars: 0 | Forks: 0
```
██████╗ ██╗ ██╗██╗███████╗██╗ ██╗██████╗ ██╗███╗ ██╗ ██████╗ ██╗ ██╗ █████╗ ██████╗ ██████╗
██╔══██╗██║ ██║██║██╔════╝██║ ██║██╔══██╗██║████╗ ██║██╔════╝ ██║ ██║██╔══██╗██╔══██╗██╔══██╗
██████╔╝███████║██║███████╗███████║██████╔╝██║██╔██╗ ██║██║ ███╗██║ ██║███████║██████╔╝██║ ██║
██╔═══╝ ██╔══██║██║╚════██║██╔══██║██╔══██╗██║██║╚██╗██║██║ ██║██║ ██║██╔══██║██╔══██╗██║ ██║
██║ ██║ ██║██║███████║██║ ██║██████╔╝██║██║ ╚████║╚██████╔╝╚██████╔╝██║ ██║██║ ██║██████╔╝
╚═╝ ╚═╝ ╚═╝╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝
```
# PhishBIN Guard
**统一网络威胁分析平台**
[](https://fastapi.tiangolo.com/)
[](https://nextjs.org/)
[](https://www.postgresql.org/)
[](https://redis.io/)
[](https://www.docker.com/)
[](LICENSE)
*检测钓鱼 URL。深度剖析恶意二进制文件。一站式解决方案。*
## 📖 目录
- [概述](#-overview)
- [功能](#-features)
- [架构](#-architecture)
- [技术栈](#-tech-stack)
- [API 参考](#-api-reference)
- [评分算法](#-scoring-algorithm)
- [项目结构](#-project-structure)
- [快速开始](#-getting-started)
- [前置条件](#prerequisites)
- [开发环境 (Docker)](#development-docker)
- [生产环境 (Docker)](#production-docker)
- [手动设置](#manual-setup)
- [环境变量](#-environment-variables)
- [外部 API 集成](#-external-api-integrations)
- [开发规则](#-development-rules)
- [测试](#-testing)
- [监控](#-monitoring)
## 🧭 概述
PhishBIN Guard 是一个开源的、基于浏览器的网络安全分析平台，专为以下用户构建：
- **网络安全专业学生**，学习威胁分析
- **安全分析师**，需要快速的工件检查器
- **大学和学术机构**，教授攻防安全
- **黑客马拉松和演示**，展示威胁情报工作流
它将**钓鱼 URL 启发式分析**、**静态二进制分析**和**外部威胁情报 API** 结合到一个仪表盘中——无需执行文件，无云端上传风险，完全透明。
## ✨ 功能
### 🎣 钓鱼 URL 检测
| 检查项 | 描述 |
|---|---|
| **Punycode / IDN 同形字** | 检测用于 IDN 欺骗攻击的 `xn--` 前缀 |
| **主机名中的 IP 地址** | 标记直接使用 IP 的 URL（例如 `http://192.168.1.1/login`） |
| **过深的子域级别** | 对具有超过 2 层子域的 URL 进行惩罚 |
| **域名拼写错误检测** | 与流行品牌（Google、PayPal 等）进行 Levenshtein 距离检查 |
| **可疑关键词匹配** | 扫描 `login`、`verify`、`reset`、`billing`、`confirm` 等关键词 |
| **域名熵值分析** | 高香农熵表明是随机生成的域名 |
| **长域名惩罚** | 标记长度超过 40 个字符的域名 |
| **用户信息滥用** | 检测 URL 授权部分中的 `@` 符号注入（`user:pass@evil.com`） |
| **外部 API 共识** | 交叉比对 VirusTotal、Google Safe Browsing、AbuseIPDB |
### 🔬 二进制 / PE 文件分析
| 检查项 | 描述 |
|---|---|
| **香农熵** | 检测加壳或加密的二进制文件（熵值 > 7.2 会被标记） |
| **PE 导入分析** | 搜寻高风险的 WinAPI 调用（如 `CreateRemoteThread`、`VirtualAllocEx` 等） |
| **可疑 DLL 检测** | 标记危险的 DLL，如 `urlmon.dll`、`wininet.dll`、`mshtml.dll` |
| **区段熵值** | 对每个区段进行熵值评分，以检测混淆的代码段 |
| **导出表分析** | 木马和注入器常见的无导出模式 |
| **字符串提取** | 从原始二进制文件中搜寻 ASCII 和 UTF-16LE 字符串 |
| **内嵌 IP 及 URL 提取** | 基于正则表达式从字符串中提取 C2 指标 |
| **恶意软件字符串匹配** | 检测已知字符串，如 `mimikatz`、`meterpreter`、`cobaltstrike`、`shellcode` |
### 📊 统一威胁评分
- **自适应加权算法** —— 根据可用数据源自动调整
- **风险分类**：`LOW` → `MEDIUM` → `HIGH` → `CRITICAL`
- **判定 + 缓解措施** 随每次结果一同提供
- **完整的证据 JSON** —— 本地启发式结果、API 结果、原始评分组件
## 🏗 架构
```
┌──────────────────────────────────────────────────┐
│ User Browser │
└────────────────────┬─────────────────────────────┘
│
┌────────────────────▼─────────────────────────────┐
│ Frontend — Next.js / React │
│ Neo Brutalist UI (TailwindCSS) │
│ Chart.js for visual risk breakdown │
└────────────────────┬─────────────────────────────┘
│ HTTP / REST
┌────────────────────▼─────────────────────────────┐
│ Backend — FastAPI (Python) │
│ ┌─────────────────────────────────────────────┐ │
│ │ /api/v1/analyze/url │ │
│ │ /api/v1/analyze/file │ │
│ │ /api/v1/reports │ │
│ └──────────┬──────────────────────┬──────────┘ │
│ │ │ │
│ ┌──────────▼──────────┐ ┌────────▼───────────┐ │
│ │ URL Analysis Engine │ │ Binary Analysis │ │
│ │ - Local Heuristics │ │ Engine │ │
│ │ - External APIs │ │ - pefile │ │
│ │ - Scoring │ │ - Entropy/Strings │ │
│ └─────────────────────┘ └────────────────────┘ │
│ │ │
│ ┌──────────▼──────────┐ ┌────────────────────┐ │
│ │ PostgreSQL (Async) │ │ Redis │ │
│ │ (Analysis Reports) │ │ (Rate Limiting) │ │
│ └─────────────────────┘ └────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Celery Workers (Async heavy tasks) │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
│
┌────────────────────▼─────────────────────────────┐
│ Prometheus + Grafana (Production Metrics) │
└──────────────────────────────────────────────────┘
```
## 🛠 技术栈
### 后端
| 组成部分 | 技术 |
|---|---|
| 框架 | [FastAPI](https://fastapi.tiangolo.com/) 0.104 |
| 运行时 | Python 3.10 |
| 数据库 ORM | SQLAlchemy 2.0 (异步) |
| 数据库 | PostgreSQL 15 |
| 缓存 / 限流 | Redis 7 + `fastapi-limiter` |
| 任务队列 | Celery |
| HTTP 客户端 | `aiohttp` (异步) |
| PE 分析 | `pefile` |
| URL 解析 | `tldextract` |
| WHOIS | `python-whois` |
| 监控指标 | Prometheus + `prometheus-fastapi-instrumentator` |
### 前端
| 组成部分 | 技术 |
|---|---|
| 框架 | Next.js |
| UI 库 | React |
| 样式 | TailwindCSS (新野兽派主题) |
| 图表 | Chart.js |
| 字体 | IBM Plex Mono, Space Mono |
### 基础设施
| 组成部分 | 技术 |
|---|---|
| 容器化 | Docker + Docker Compose |
| 监控 | Prometheus + Grafana |
| 生产服务器 | Uvicorn (4 个 worker) |
## 📡 API 参考
Base URL：`http://localhost:8000/api/v1`
### `POST /analyze/url`
分析 URL 以检测钓鱼指标。
**请求体：**
```
{
"url": "http://login-secure-verify.xn--paypa1.com/update"
}
```
**响应：**
```
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"risk_score": 95.0,
"risk_level": "CRITICAL",
"verdict": "PHISHING / MALWARE",
"sources": ["VT:72/90", "Google:Blocked", "Local:85.0/100"],
"indicators": [
"Punycode (Homograph attack)",
"Suspicious keywords: login, verify, update",
"Possible typosquatting of paypal"
],
"mitigations": ["BLOCK IMMEDIATELY", "Report to PhishTank", "Isolate endpoint if clicked"],
"evidence": {
"local_data": { ... },
"api_results": [ ... ],
"scoring_components": { ... }
}
}
```
### `POST /analyze/file`
上传二进制文件以进行静态 PE 分析。（最大：**25 MB**）
**请求：** 包含 `file` 字段的 `multipart/form-data`。
```
curl -X POST http://localhost:8000/api/v1/analyze/file \
-F "file=@suspicious.exe"
```
**响应：**
```
{
"id": "a1b2c3d4-...",
"risk_score": 75.0,
"risk_level": "HIGH",
"verdict": "HIGHLY SUSPICIOUS",
"sources": ["Local:75.0/100", "⚠️ External APIs: Not Configured (local-only mode)"],
"indicators": [
"High Shannon Entropy (7.63) - packed/encrypted",
"Section .text is highly obfuscated (7.81)",
"No exports (common in droppers/malware)",
"Embedded IP addresses found (3)"
],
"mitigations": ["BLOCK", "Manual SOC Review"],
"evidence": {
"local_data": {
"suspicious_imports": ["kernel32.dll!virtualAllocEx"],
"embedded_ips": ["192.168.1.100"],
"embedded_urls": ["http://evil.c2server.net/beacon"]
}
}
}
```
### `GET /reports`
获取最近 50 份分析报告。
```
curl http://localhost:8000/api/v1/reports
```
### `GET /`
健康检查端点。
```
{ "status": "ok", "version": "v2.ultimate" }
```
## 🧮 评分算法
PhishBIN Guard 使用**自适应加权评分**系统：
### 当配置了外部 API 时：
```
Final Score = (0.4 × Local Heuristics)
+ (0.3 × API Consensus) ← average of top 2 API scores
+ (0.2 × Reputation Score)
+ (0.1 × Behavior Score)
```
### 在离线 / 演示模式下运行时（无 API 密钥）：
```
Final Score = Local Heuristics (100% weight)
```
这确保了平台在没有任何 API 密钥的情况下也能完全运行——非常适合演示、离线环境和学术使用。
### 风险阈值
| 分数 | 风险等级 | 判定 | 缓解措施 |
|---|---|---|---|
| ≥ 80 | 🔴 CRITICAL | PHISHING / MALWARE | 立即拦截、上报、隔离端点 |
| ≥ 55 | 🟠 HIGH | HIGHLY SUSPICIOUS | 拦截，升级到 SOC |
| ≥ 30 | 🟡 MEDIUM | SUSPICIOUS | 警告用户，持续监控 |
| < 30 | 🟢 LOW | CLEAN | 允许 |
## 📁 项目结构
```
PishBIN-Guard/
│
├── backend/
│ ├── main.py # FastAPI app entry point
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── init_db.py # DB initializer script
│ │
│ ├── api/
│ │ └── routes/
│ │ └── analyzer.py # URL & binary analysis endpoints
│ │
│ ├── services/
│ │ ├── local_url.py # Local URL heuristics engine
│ │ ├── local_binary.py # Local PE static analysis engine
│ │ ├── external_apis.py # VirusTotal, GSB, AbuseIPDB integrations
│ │ ├── scoring.py # Adaptive scoring algorithm
│ │ ├── url_service.py # Full URL analysis service (alt heuristics)
│ │ ├── binary_service.py # Full binary analysis service
│ │ └── file_tasks.py # File upload handling utilities
│ │
│ ├── core/
│ │ ├── database.py # Async SQLAlchemy engine & session
│ │ └── tasks.py # Celery task definitions
│ │
│ └── models/
│ └── report.py # AnalysisReport SQLAlchemy model
│
├── frontend/ # Next.js / React application
│
├── docker-compose.yml # Development stack (MongoDB)
├── docker-compose.prod.yml # Production stack (PostgreSQL, Redis, Celery, Monitoring)
│
├── test_ultimate.py # Async API integration tests
├── test_services.py # Service-level tests
├── verify_api.py # Quick verification script
├── demo_malware.bin # Sample binary for testing
│
├── PRD.md # Product Requirements Document
└── rules.md # Development rules & constraints
```
## 🚀 快速开始
### 前置条件
- [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/)
- 或者：Python 3.10+、Node.js 18+、PostgreSQL 15、Redis 7
### 开发环境 (Docker)
开发环境栈将启动后端、前端和 MongoDB 实例：
```
git clone https://github.com/hx010207/PishBIN-Gaurd.git
cd PishBIN-Gaurd
docker compose up --build
```
| 服务 | URL |
|---|---|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:8000 |
| API 文档 (Swagger) | http://localhost:8000/docs |
| MongoDB | mongodb://localhost:27017 |
### 生产环境 (Docker)
生产环境栈增加了 PostgreSQL、Redis、Celery worker、Prometheus 和 Grafana：
```
# 1. 创建您的环境文件
cp .env.example .env
# 编辑 .env 并填写您的 API keys 和 secrets
# 2. 启动生产 stack
docker compose -f docker-compose.prod.yml up --build -d
```
| 服务 | URL |
|---|---|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:8000 |
| Prometheus | http://localhost:9090 |
| Grafana | http://localhost:3001 (admin / admin) |
### 手动设置
#### 后端
```
cd backend
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 设置环境变量
export DATABASE_URL="postgresql+asyncpg://postgres:password@localhost:5432/phishbin"
export REDIS_URL="redis://localhost:6379/1"
# 初始化数据库
python init_db.py
# 启动服务器
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
#### 前端
```
cd frontend
npm install
npm run dev
```
## 🔑 环境变量
在项目根目录创建一个包含以下变量的 `.env` 文件：
```
# ─── 数据库 ────────────────────────────────────────────────
DATABASE_URL=postgresql+asyncpg://postgres:phishbin_secure@postgres:5432/phishbin
# ─── Redis ───────────────────────────────────────────────────
REDIS_URL=redis://redis:6379/1
# ─── 前端 ────────────────────────────────────────────────
NEXT_PUBLIC_API_URL=http://localhost:8000
# ─── Threat Intelligence API Keys (全部可选) ─────────────
VT_API_KEY= # VirusTotal API key
GSB_API_KEY= # Google Safe Browsing API key
ABUSEIPDB_API_KEY= # AbuseIPDB API key
URLSCAN_API_KEY= # URLScan.io API key
PHISHTANK_API_KEY= # PhishTank API key (optional, often keyless)
OTX_API_KEY= # AlienVault OTX API key
HYBRID_ANALYSIS_API_KEY= # Hybrid Analysis API key
```
## 🌐 外部 API 集成
| 服务 | 用途 | 免费套餐 |
|---|---|---|
| [VirusTotal](https://www.virustotal.com/) | URL 和文件扫描共识 | 4 次请求/分钟，500 次/天 |
| [Google Safe Browsing](https://developers.google.com/safe-browsing) | 恶意软件/钓鱼 URL 检测 | 免费（通过 GCP 密钥） |
| [AbuseIPDB](https://www.abuseipdb.com/) | IP 信誉评分 | 1000 次/天 |
| [URLScan.io](https://urlscan.io/) | URL 截图和行为分析 | 提供免费套餐 |
| [PhishTank](https://www.phishtank.com/) | 社区钓鱼数据库 | 免费 |
| [AlienVault OTX](https://otx.alienvault.com/) | 威胁脉冲指标 | 免费 |
| [Hybrid Analysis](https://www.hybrid-analysis.com/) | 沙箱行为报告 | 免费（受限） |
所有 API 调用均使用 `asyncio.gather` 进行**异步**操作，以满足 3 秒内响应的目标。
## 📐 开发规则
所有贡献必须遵守这些约束（见 [`rules.md`](rules.md)）：
1. 项目必须完全开源
2. 后端必须使用 Python FastAPI
3. 前端必须使用 Next.js 和 React
4. UI 主题必须遵循新野兽派设计（黑色背景、白色文本、硬边框、等宽字体）
5. 所有分析必须是**静态**的——绝不执行二进制文件
6. 文件上传必须沙箱化
7. 文件上传最大限制：**25 MB**
8. 所有输出必须包含用于教育目的的解释说明
9. 所有 API 必须返回**结构化的 JSON**
10. 使用模块化架构
## 🧪 测试
### 快速 API 验证（需要运行后端）：
```
python verify_api.py
```
### 异步集成测试：
```
# 需要：pip install aiohttp
python test_ultimate.py
```
### 服务级别测试：
```
python test_services.py
```
### 使用内置的恶意软件演示样本进行测试：
```
curl -X POST http://localhost:8000/api/v1/analyze/file \
-F "file=@demo_malware.bin"
```
### 基准测试 URL：
| URL | 预期结果 |
|---|---|
| `http://login-secure-verify.xn--test.com/update` | **CRITICAL**（触发多个指标） |
| `https://google.com` | **LOW / CLEAN** |
## 📈 监控
生产环境栈内置了 **Prometheus** 指标（通过 `prometheus-fastapi-instrumentator`）和 **Grafana** 仪表盘。
- **Prometheus** 从 `/metrics` 端点抓取 FastAPI 后端的指标
- **Grafana** 连接到位于 `http://prometheus:9090` 的 Prometheus
- 默认 Grafana 凭据：`admin` / `admin`
自定义监控配置可放置在 `monitoring/prometheus.yml` 中。
## 🎨 UI 设计
PhishBIN Guard 采用**新野兽派**视觉设计语言：
- ⬛ 黑色背景
- ⬜ 白色文本
- 🔳 坚实的硬边框——无阴影，无渐变
- 📦 方块状的基于网格的布局
- 🔤 等宽字体：**IBM Plex Mono** + **Space Mono**
© 2026 PhishBIN Guard — 开源网络威胁分析平台
*为教育而构建。为安全而部署。*
标签：AV绕过, DAST, DeepSeek, Docker, FastAPI, Go语言工具, MongoDB, Punycode检测, URL分析, Web安全, 二进制分析, 云安全运维, 免费API, 启发式分析, 威胁分析平台, 威胁情报, 安全运营, 安全防御评估, 开发者工具, 恶意软件分析, 扫描框架, 搜索引擎查询, 搜索语句（dork）, 沙箱, 测试用例, 熵值分析, 网络安全, 自定义请求头, 蓝队分析, 请求拦截, 逆向工具, 钓鱼检测, 隐私保护, 风险API检测