JuaanReis/scamlens
GitHub: JuaanReis/scamlens
ScamLens 是一个用于检测钓鱼和恶意 URL/二维码的模块化后端分析平台，通过多源数据采集与声明式启发式规则生成风险评分。
Stars: 0 | Forks: 0
# ScamLens
模块化的后端 API，用于分析 URL 和 QR code，基于声明式启发式方法进行钓鱼特征检测，并支持多层级的结构化数据采集。
## 目录
- [概述](#visão-geral)
- [前置条件](#pré-requisitos)
- [安装说明](#instalação)
- [使用指南](#uso)
- [Endpoints](#endpoints)
- [身份验证](#autenticação)
- [开源协议](#open-source)
- [贡献指南](#contribuição)
## 概述
ScamLens 会分析 URL 和 QR code 以寻找恶意模式。该系统将多层级的结构化采集 pipeline（DNS、RDAP、SSL、Safe Browsing、HTTP/HTML）与通过 `@register` 注册的声明式启发式方法相结合，从而生成风险评分。
URL 分析 pipeline：
```
validate_url → collect → target_structure → context_apply → execute → score → response_builder
```
QR 引擎（`scqr`）会解码图像，对 payload 类型进行分类，并且当其为 URL 时，会将其传入上述相同的 pipeline 中。其他 payload 类型（Pix、Wi-Fi、vCard、电子邮件等）会被检测到，但在当前版本中尚未进行深入分析。
## 前置条件
- Python 3.10+
- SQLite 3.x（包含在标准库中）
- Nginx（仅用于生产环境部署）
## 安装说明
```
git clone https://github.com/JuaanReis/scamlens.git
cd scamlens
python -m venv .venv
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
pip install -e .
```
配置环境变量（在根目录创建一个 `.env` 文件）：
```
EMAIL_ADMIN=admin@exemplo.com
PASSWORD_ADMIN=senha_forte
JWT_SECRET=string_longa_e_aleatoria
GOOGLE_SAFE_BROWSING_KEY=sua_chave
# 可选 — 默认为 "production"（禁用 /docs 和 /redoc）
SCAMLENS_ENV=development
# 可选 — 默认从 repo 推断
SCAMLENS_DB_PATH=./providers/database/storage/db/scamlens.db
```
启动服务器：
```
scamlens-api
```
API 将可以通过 `http://localhost:8000` 访问。首次运行时，系统会根据 `EMAIL_ADMIN`/`PASSWORD_ADMIN` 自动创建管理员账户。
当设置 `SCAMLENS_ENV=development` 时，交互式文档将通过 `/docs` 和 `/redoc` 提供。
## 使用指南
### 分析 URL
```
curl -X POST http://localhost:8000/api/scurl/analyze/url \
-H "Content-Type: application/json" \
-d '{"url": "https://exemplo-suspeito.com", "use_cache": false}'
```
响应 (`200`)：
```
{
"scan": {
"status": "ok",
"engine": { "name": "scurl", "version": "..." },
"meta": {
"scan_id": "abc123",
"scan_time_s": 1.42,
"url_hash": "sha256...",
"url": "https://exemplo-suspeito.com",
"threads": 1,
"timestamp": "2026-07-28T00:00:00Z"
},
"result": {
"score": 0.83,
"risk_level": "high",
"verdict": "likely_phishing"
},
"stats": {
"rules_total": 20,
"rules_triggered": 7,
"trigger_rate": 0.35
},
"heuristics": [...],
"insight": ["Domain registered less than 7 days ago", "Invalid SSL certificate"]
},
"target": {
"identity": { "hostname": "exemplo-suspeito.com", "is_idn": false, ... },
"network": { "ipv4": [...], "asn": {...}, "geo": {...}, ... },
"tls": { "enabled": true, "valid_from": "...", "self_signed": true, ... },
"dns": { "a": [...], "ns": [...], "spf": false, "dmarc": false, ... },
"http": { "status_code": 200, "redirects": 2, "security_headers": {...}, ... },
"content": { "title": "...", "forms": {"count": 1, "password_fields": 1}, ... },
"domain": { "registrar": "...", "age_days": 3, ... }
}
}
```
在未进行身份验证的情况下，该 endpoint 允许每个 IP 每天最多进行 **3 次分析**。超出限制的请求将返回 `401`。
### 分析 QR code
```
curl -X POST http://localhost:8000/api/scurl/qr/analyze/qr \
-F "file=@qrcode.png"
```
接受 JPEG、PNG、WebP、GIF 格式（通过 magic bytes 验证，而非 `Content-Type`）。从 QR 中提取的 payload 必须是一个 URL —— 其他类型将返回 `400` 及 `error.type: "unsupported_qr_type"`。
### CLI
除了 API 之外，URL 引擎还可以直接使用：
```
scurl https://exemplo-suspeito.com
scurl https://exemplo-suspeito.com -v # verbose
scurl https://exemplo-suspeito.com -o resultado.json
scurl https://exemplo-suspeito.com -t 4 -T 10 # 4 threads, timeout 10s
scurl https://exemplo-suspeito.com -c # usa cache local
```
## Endpoints
| 方法 | Endpoint | 认证 | 描述 |
|--------|----------|------|-----------|
| `POST` | `/api/scurl/analyze/url` | 可选 | 分析 URL |
| `POST` | `/api/scurl/qr/analyze/qr` | 可选 | 分析带有 QR code 的图像 |
| `GET` | `/api/scurl/scans` | — | 列出公开的扫描历史记录 |
| `GET` | `/api/scurl/scans/{id}` | — | 某次扫描的详细信息 |
| `POST` | `/api/auth/register` | — | 注册用户 |
| `POST` | `/api/auth/login` | — | 登录（设置 httpOnly cookies） |
| `POST` | `/api/auth/refresh` | Cookie | 刷新 access token |
| `POST` | `/api/auth/logout` | Cookie | 吊销 token 并清除 cookies |
| `GET` | `/api/user/me` | Cookie | 用户资料与活动记录 |
| `POST` | `/api/user/avatar` | Cookie | 上传头像（JPEG/PNG/WebP/GIF，最大 2MB） |
| `GET` | `/api/admin/*` | Admin | 指标、用户、扫描、日志 |
| `GET` | `/health` | — | 存活探针（检查数据库） |
有关完整的参考资料，请参阅 [docs/usage.md](./docs/USAGE.md)。
## 身份验证
ScamLens 使用两个通过 `HS256` 签名的 JWT，并以 `httpOnly` cookies 的形式传输。受保护的路由也接受 `Authorization: Bearer ` 作为 cookie 的替代方案。
| Token | 有效期 |
|-------|---------|
| Access token | 30 分钟 |
| Refresh token | 1 天（`remember: false`）或 30 天（`remember: true`） |
通过 `jti` 黑名单进行吊销 —— 注销操作会立即使这两个 token 失效，无论其是否过期。
每日分析配额：
| 用户 | 限制 |
|---------|--------|
| 匿名（按 IP） | 3 |
| `standard` | 5 |
| `go_pro` | 25 |
| `plus_premium` | 无限制 |
## 开源协议
ScamLens 根据 [MIT](LICENSE.md) 许可证分发。可自由用于个人、学术和商业用途。
## 贡献指南
欢迎您的贡献。若要参与贡献：
1. Fork 该仓库
2. 创建一个分支：`git checkout -b feat/minha-feature`
3. 提交：`git commit -m 'feat: descrição clara do que foi feito'`
4. 发起一个 Pull Request
如发现 bug 或有建议，请提交一个 [issue](https://github.com/JuaanReis/ScamLens/issues)。
标签：AV绕过, DAST, FastAPI, Python, Web安全, 反欺诈, 恶意软件分析, 无后门, 蓝队分析, 钓鱼检测