anasahhm/Specter
GitHub: anasahhm/Specter
基于异步架构的 AI URL 威胁情报分析平台，融合技术信号提取与行为模式识别输出确定性风险评分。
Stars: 0 | Forks: 0
# SPECTER：基于 Wire API 的 AI 威胁情报平台
实时 URL 威胁分析。Wire API 提取技术信号，Google Generative AI 识别行为模式，确定性评分输出风险 (0-100)。异步架构可处理 120秒的 Wire API 和 45秒的 AI 调用，而不会造成阻塞。
[实时演示](https://specter-weld.vercel.app)
## 为什么开发这个项目
静态 URL 威胁检测存在缺陷：
- 基于黑名单的工具会漏掉 60% 以上的新钓鱼活动
- SaaS 解决方案每月花费 500 美元，且有 5 分钟的延迟
- 开源工具仅使用 regex 模式（误报率太高）
我需要混合智能：原始技术信号（域名年龄、SSL 有效性、重定向链）+ AI 模式识别（行为聚类、社会工程学向量）。而且它必须快速。
## 架构问题
**问题：** Wire API 耗时 120秒，Google Generative AI 耗时 45秒。如果我阻塞请求线程等待两者完成，用户将盯着加载动画长达 175 秒。
**解决方案：** 异步 worker 架构。
```
POST /api/investigations/start → returns investigation ID immediately (300ms)
Background: Wire API (120s) → AI Analysis (45s) → Threat Scoring (10s)
Frontend polls GET /api/investigations/:id every 2s with 3-min graceful timeout
Status persisted: processing → completed
User gets results without waiting (8-15s typical, 180s max)
```
这种模式具有可扩展性。调查 50 个 URL，稍后再回来查看。没有轮询地狱，也没有 WebSocket 的复杂性。
## 技术栈
**前端：** React 18 + Vite（比 Webpack 快 3-4 倍）+ Tailwind + Framer Motion
**后端：** Node.js/Express + MongoDB + Mongoose + Helmet.js + express-rate-limit
**智能分析：** Wire API（技术元数据）+ Google Generative AI（模式分析）
**认证：** JWT（30天过期）+ bcryptjs（salt: 10）+ 输入验证
**部署：** Vercel（前端）+ Render（后端）+ MongoDB Atlas（数据库）
## 安装与设置
### 前置条件
```
Node.js v18+, npm/yarn, MongoDB (Atlas free tier works)
```
### 克隆与安装
```
git clone https://github.com/anasahhm/specter.git
cd specter
# Backend
cd backend
npm install
cp .env.example .env # Add your API keys
# Frontend
cd frontend
npm install
cp .env.example .env
```
### 环境变量
**后端 (.env)：**
```
NODE_ENV=development
PORT=5000
MONGODB_URI=mongodb+srv://user:password@cluster.mongodb.net/specter
JWT_SECRET=your-super-secret-key-minimum-32-characters
WIRE_API_KEY=your-wire-api-key-here
GOOGLE_GENERATIVE_AI_KEY=your-key-here
FRONTEND_URL=http://localhost:5173
```
**前端 (.env)：**
```
VITE_API_URL=http://localhost:5000
VITE_APP_NAME=SPECTER
```
### 本地运行
**终端 1 (后端)：**
```
cd backend && npm run dev
# 应输出：
# ╔══════════════════════════════════════════╗
# ║ SPECTER - SERVER STARTED ║
# ║ Port: 5000 | Database: Connected ║
# ║ Wire API: ✓ | Google AI: ✓ ║
# ╚══════════════════════════════════════════╝
```
**终端 2 (前端)：**
```
cd frontend && npm run dev
# http://localhost:5173
```
**终端 3 (测试 API)：**
```
curl http://localhost:5000/api/health
# {"status":"operational","timestamp":"2024-05-31T12:00:00.000Z"}
```
## 工作原理
### 3 阶段 Pipeline
**步骤 1：Wire API（120秒超时）**
- 域名元数据、SSL 证书、年龄、MX 记录
- 重定向链、技术栈检测
- 嵌入的链接、表单、脚本
- 输出：原始技术信号
**步骤 2：AI 分析（45秒超时）**
- Google Generative AI 模式识别
- 针对已知威胁的行为聚类
- 钓鱼向量识别
- 置信度评分和摘要生成
- 后备方案：AI 不可用时使用基于规则的分析
**步骤 3：威胁评分（10秒超时）**
- 风险评分 (0-100)
- 威胁分类（严重/高/中/低/安全）
- 诈骗概率、毒性评级、置信度
- 输出：最终判定
### 数据流
```
1. User submits URL
2. POST /api/investigations/start
3. Backend returns investigationId (status: processing)
4. Frontend polls GET /api/investigations/:id every 2s
5. Background: Step 1 → Step 2 → Step 3
6. Status changes to completed
7. Frontend renders results
```
## 我解决的棘手问题
### 1. **慢速外部 API 导致的阻塞**
- **问题：** Wire API + AI = 165秒。阻塞请求线程会严重影响用户体验 (UX)。
- **解决方案：** 异步 worker + 轮询。POST 请求会立即返回 ID，前端每 2秒轮询一次。
- **经验教训：** 对于耗时超过 10秒的外部 API，请务必使用异步 + 轮询或 WebSocket。
### 2. **速率限制滥用**
- **问题：** 用户频繁请求 API。机器人恶意抓取 URL 威胁情报。
- **解决方案：** 双重速率限制：
- 全局：100 次请求/15分钟（捕获分布式攻击）
- 单用户：5 次调查/分钟（防止单个用户滥用）
- 滑动窗口（非固定桶）
- **经验教训：** 单一速率限制是不够的。来自单个用户的攻击看起来与僵尸网络流量是不同的。
### 3. **外部 API 弹性**
- **问题：** 如果 Wire API 宕机了怎么办？如果 Google AI 返回错误怎么办？
- **解决方案：** 优雅降级：
- Wire API 失败 → 使用缓存的域名信誉数据
- Google AI 超时 → 回退到基于规则的威胁评分
- 两者均失败 → 返回带有明确警告的部分结果
- **经验教训：** 单点故障会引发连锁反应。必须在每一层构建后备方案。
### 4. **JWT Token 过期处理**
- **问题：** 用户调查需要数小时，但 token 在 30 天后就过期了。
- **解决方案：** Token 刷新模式：
- 30天 access token + refresh token
- 前端 axios 拦截器自动刷新
- 错误消息中不包含敏感数据
- **经验教训：** 切勿在错误响应中泄露 token 详情。
### 5. **重度依赖 JavaScript 的网站**
- **问题：** Wire API 只能看到静态 HTML。动态表单、混淆链接、JS 渲染的内容是不可见的。
- **解决方案：** 混合方法：
- Wire API 用于结构/技术分析
- Google AI 用于行为/模式分析
- 三角测量捕获各自遗漏的内容
- **经验教训：** 没有任何单一工具是完美的。需结合各自优势。
### 6. **MongoDB 连接池**
- **问题：** Mongoose 默认连接池大小 (5) 在并发负载下太小。
- **解决方案：** 在连接 URI 中调整连接池设置，并添加连接监控。
- **经验教训：** 数据库瓶颈会在负载下暴露，而不是在开发环境中。
## API 参考
### 认证
```
POST /api/auth/register
{ email, password, displayName? }
POST /api/auth/login
{ email, password }
GET /api/auth/profile
Headers: Authorization: Bearer {token}
```
### 调查
```
POST /api/investigations/start
{ targetType: "url", targetValue: "https://..." }
Returns: { investigationId, status: "processing" }
GET /api/investigations/:investigationId
Returns: Complete threat analysis
GET /api/investigations?page=1&limit=10
Returns: User's investigation history
PUT /api/investigations/:investigationId/bookmark
{ isBookmarked: boolean }
```
### 报告与分析
```
GET /api/reports/:investigationId
GET /api/reports/:investigationId/export?format=pdf|json
GET /api/analytics/user-stats
GET /api/analytics/threat-distribution
```
## 威胁指标
| 指标 | 范围 | 含义 |
|--------|-------|---------|
| **风险评分** | 0-100 | 整体威胁严重程度 |
| **威胁等级** | 严重/高/中/低/安全 | 分类 |
| **检测到钓鱼** | 是/否 | 已知的钓鱼模式 |
| **诈骗概率** | 0-100% | 欺诈意图的可能性 |
| **毒性评分** | 0-100 | 内容毒性 |
| **置信度得分** | 0-100% | 分析的确定性 |
## 性能
| 指标 | 目标 | 实际 |
|--------|--------|--------|
| 页面加载 | <2s | 1.2s |
| 调查启动 (API) | <500ms | 300ms |
| 结果可用 | <30s | 8-15s |
| API 响应时间 | <1s | 200-400ms |
| 数据库查询 | <100ms | 50-80ms |
## 安全性
**JWT 认证** - 30天 token 过期 + 刷新轮换
**密码哈希** - bcryptjs (salt rounds: 10)
**速率限制** - 100 次请求/15分钟 (全局) + 5 次/分钟 (单用户)
**Helmet.js** - CSP, X-Frame-Options, HSTS 等
**CORS** - 仅允许前端域名白名单
**输入验证** - 邮箱格式、密码熵、URL 结构
**错误处理** - 无敏感数据泄露
**环境隔离** - 密钥存放在 .env 中，绝不写入代码
## 部署
**前端 (Vercel)：**
1. 推送至 GitHub
2. vercel.com/new → 导入仓库
3. 设置 `VITE_API_URL` 环境变量
4. 部署
**后端 (Render)：**
1. render.com → 创建 Web Service
2. 关联 GitHub 仓库
3. 设置所有环境变量（MONGODB_URI、WIRE_API_KEY 等）
4. 部署
**数据库 (MongoDB Atlas)：**
1. cloud.mongodb.com → 创建集群（免费套餐）
2. 获取连接字符串
3. 将你的 IP 加入白名单
4. 将其设置为 MONGODB_URI
## 项目结构
```
specter/
├── frontend/
│ ├── src/
│ │ ├── pages/ # Route components
│ │ ├── components/ # Reusable UI components
│ │ ├── hooks/ # Custom React hooks
│ │ ├── api/ # API client + interceptors
│ │ ├── context/ # Auth context
│ │ ├── utils/ # Helpers
│ │ └── styles/ # Global CSS
│ ├── vite.config.js
│ ├── tailwind.config.js
│ └── package.json
│
├── backend/
│ ├── src/
│ │ ├── routes/ # Express route handlers
│ │ ├── services/ # Business logic (Wire, AI, Scoring)
│ │ ├── models/ # Mongoose schemas
│ │ ├── config/ # Validation, constants
│ │ ├── scripts/ # Database seeders
│ │ ├── server.js # Express app setup
│ │ └── index.js # Entry point
│ └── package.json
│
└── docs/
├── ARCHITECTURE.md # System design
├── API.md # Endpoint reference
└── DEPLOYMENT.md # Production setup
```
## 测试
### 手动 API 测试
```
# 注册
curl -X POST http://localhost:5000/api/auth/register \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","password":"Test123!"}'
# 登录
curl -X POST http://localhost:5000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","password":"Test123!"}'
# 开始调查
curl -X POST http://localhost:5000/api/investigations/start \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"targetType":"url","targetValue":"https://example.com"}'
# 获取结果
curl http://localhost:5000/api/investigations/INVESTIGATION_ID \
-H "Authorization: Bearer YOUR_TOKEN"
```
### 浏览器测试
1. 注册账户
2. 测试 URL：`example.com`（安全）、`malicious-url.com`（可疑）
3. 验证威胁评分、钓鱼检测、报告生成
4. 检查调查历史记录和书签
## 故障排除
### 前端无法连接到后端
```
# 检查 Backend 是否正在运行
curl http://localhost:5000/api/health
# 检查 frontend/.env 中的 VITE_API_URL 是否与 Backend 匹配
# 检查 backend/.env 中的 FRONTEND_URL 是否与 frontend origin (http://localhost:5173) 匹配
# 检查浏览器控制台是否有 CORS 错误
```
### MongoDB 连接失败
```
# 验证 connection string
MONGODB_URI=mongodb+srv://user:password@cluster.mongodb.net/specter
# 检查 MongoDB Atlas 中的 IP 白名单（在开发环境中添加 0.0.0.0/0）
# 验证数据库用户是否具有正确的凭据
```
### Wire API 错误
- 检查 API key 是否有效且配额未超限
- 查看 Wire API 文档了解速率限制
- 启用调试日志：`DEBUG=* npm run dev`
### 调查超时 (>180s)
- 默认超时时间为 180 秒
- 检查后端日志以查找特定步骤的错误
- 先使用简单的 URL（例如 example.com）进行测试
## 统计数据
- **48 小时构建**（黑客松冲刺）
- **2100+ 行代码** (1200 行前端，900 行后端)
- **12 个 API endpoint**（认证、调查、报告、分析）
- **3 阶段 pipeline**（Wire API → AI → 评分）
- **典型延迟 8-15秒**（含超时最长为 8-180秒）
- **4 个数据库集合**（用户、调查、报告、分析）
- **18 个 React 组件**（模块化、可复用）
- **3 个后端服务**（Wire client、AI 分析器、威胁评分器）
## 学到了什么
1. **异步胜过阻塞。** 外部 API 超过 10秒？不要等待。异步 + 轮询的可扩展性更好。
2. **优雅降级拯救系统。** 当 Wire API 失败时，使用缓存数据。当 AI 超时时，使用规则。
3. **速率限制是多维度的。** 全局限制捕获僵尸网络。单用户限制捕获个人滥用。
4. **混合智能有效。** 单一数据源存在盲区。Wire API + AI 可以捕获各自遗漏的内容。
5. **安全就是分层。** JWT + bcryptjs + Helmet + CORS + 输入验证 = 纵深防御。
## 许可证
MIT — 查看 [LICENSE](./LICENSE)
## 由 Anas Ahmed 制作
有问题？提交一个 [GitHub issue](https://github.com/anasahhm/specter/issues)
**在线访问：** https://specter-weld.vercel.app
标签：AI应用, MITM代理, URL分析, 威胁情报, 开发者工具, 异步架构, 搜索语句（dork）, 自定义脚本