StandFast1/SMISHWATCH

# SMISHWATCH [](https://github.com/StandFast1/SMISHWATCH/actions/workflows/ci.yml) [](https://github.com/StandFast1/SMISHWATCH/actions/workflows/codeql.yml) [](https://github.com/StandFast1/SMISHWATCH/actions/workflows/security.yml) 专注于法国背景下短信诈骗 / 钓鱼（smishing）的防御性威胁情报平台： 假冒银行顾问、CPF诈骗、“您的包裹”、冒充 AMELI / 税务局等。 基于诈骗短信或可疑 URL，SMISHWATCH 会执行一个**被动**分析 pipeline： 提取并展开 URL，在沙箱中获取 landing page，对钓鱼工具包进行指纹识别，聚类为Campaign， 进行 OSINT 丰富化（WHOIS、Certificate Transparency、ASN、地理定位）并生成分析报告 + 带有时间戳的证据包。 ## 使用声明 SMISHWATCH 是一款**防御性分析师**工具，秉承了 URLhaus、PhishTank 或 Spamhaus 的理念。它观察**已存在且公开的**恶意基础设施； 它不会创建、攻击、绕过任何保护，也**绝不**提交任何凭据。 仅限于合法的研究、欺诈调查和防御。所有分析均限于公开可观察的内容。 架构中编码的保证： - **仅限被动分析** — 不提交表单，不向目标基础设施发送 POST 请求，只读 fetch。 - **沙箱化 Fetch** — 隔离的 headless 浏览器，无 credential store，无 持久化 cookies，受控的网络出口。 - 对所有由用户输入触发的传出请求实施 **SSRF guard**。 - **默认进行 Defang 处理**（`hxxp://`、`evil[.]com`、`1[.]2[.]3[.]4`）； refang 需要分析师明确操作。 - **Rate limiting**、超时机制、最大响应大小限制、诚实的 User-Agent。 - **不绕过** WAF、captcha 或反机器人保护。 - **最小化 PII**：静态加密受害者数据，绝不以明文记录，绝不外泄。 - **证据链**（时间戳、hash）以保持可用性。 ## 技术栈 - **Backend**：Python 3.12、FastAPI、异步 (`httpx`, `asyncio`) - **数据库**：PostgreSQL + SQLAlchemy 2.0 (异步) + Alembic - **沙箱化 Fetch**：Playwright (Chromium headless)，隔离的 `fetcher` 服务 - **Frontend**：Next.js (App Router, TypeScript) + Tailwind — 分析师 dashboard - **容器化**：Docker + docker-compose - **代码质量**：ruff、black、mypy (strict)、pytest ## 安装说明 ### 前置条件 - **Docker + Docker Compose**（推荐路径），**或者** - **Python 3.12+** 和一个 **PostgreSQL** 实例（本地/开发路径）。 - 使用 `git` 克隆仓库。 ``` git clone https://github.com/StandFast1/SMISHWATCH.git cd SMISHWATCH ``` ### 一键启动 (Docker) ``` make demo # Linux/macOS .\tasks.ps1 demo # Windows PowerShell ``` `demo` 会生成 `.env` + 一个 `PII_SECRET_KEY`，启动 `db` + `api` + `fetcher` + `web`，自动应用迁移并创建一个示例提交记录。 然后打开 **http://localhost:3000**。 ### 选项 A — Docker (逐步操作) ``` .\tasks.ps1 setup # crée .env + génère PII_SECRET_KEY (ou: make setup) docker compose up --build # db + api + fetcher + web ; migrations auto au démarrage curl http://localhost:8000/health # -> {"status":"ok"} ``` API 位于 `http://localhost:8000` · Swagger 位于 `http://localhost:8000/docs` · dashboard 位于 `http://localhost:3000`。Alembic 迁移会由 `api` 容器自动应用。 手动生成 PII 密钥：`docker compose run --rm api python -m smishwatch.security.vault`。 ### 选项 B — 本地无 Docker (Windows / 开发) 适合用于开发和运行测试。捕获 artifacts（`fetcher` 服务）还需要 Playwright； 其余功能在本地 Postgres 下即可运行。 ``` cd api python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -e ".[dev]" ``` 在 `.env` 中将 `DATABASE_URL` 指向您的本地 Postgres，例如： ``` DATABASE_URL=postgresql+asyncpg://smishwatch:changeme@localhost:5432/smishwatch ``` 应用迁移，然后启动 API： ``` alembic upgrade head uvicorn smishwatch.main:app --reload ``` 要在本地捕获 artifacts，请同时启动 `fetcher` 服务： ``` cd ..\fetcher pip install -r requirements.txt playwright install chromium uvicorn app:app --port 8080 # 然后在 API 的 .env 中：FETCHER_URL=http://localhost:8080 ``` ### Dashboard (Web) Next.js 的 dashboard 会调用 API。使用 Docker 时，它会通过 `docker compose up` 在 `http://localhost:3000` 启动。在本地运行： ``` cd web copy .env.local.example .env.local # NEXT_PUBLIC_API_URL=http://localhost:8000 npm install npm run dev # http://localhost:3000 ``` 完整流程（提交 -> 报告 -> Campaign）均可在 UI 中控制： 所有内容默认以 **defang** 形式显示，每个值都有一个明确的“refang”按钮； 没有任何指向恶意基础设施的可点击链接。 ## 使用说明 所有指标在存储和返回时均进行了 **defang** 处理（`hxxp://`、`evil[.]com`、 `1[.]2[.]3[.]4`）；电话号码 (PII) 已被加密和掩码。您可以完全通过 `http://localhost:8000/docs` 或使用 `curl` 进行控制。 ### 1. 提交短信或 URL ``` curl -X POST http://localhost:8000/submissions \ -H "Content-Type: application/json" \ -d '{"raw_input": "votre colis https://exemple-colis.test/track 06 12 34 56 78", "source": "sms"}' ``` 提取指标（URL、域名、IP、手机号码），通过 SSRF guard 展开短链接， 并追踪重定向链。请注意返回的 `id`。 ### 2. 捕获 artifacts (沙箱化 Fetch) ``` curl -X POST http://localhost:8000/submissions//artifacts ``` 每个 URL 都会通过 SSRF guard 重新验证，然后由 `fetcher` 服务进行渲染 （隔离的 Chromium headless，只读，不提交任何表单，不使用持久化 cookies）。 我们会存储静态 HTML、屏幕截图和 favicon 及其哈希值 （SHA-256，用于 favicon 的 Shodan 风格 mmh3，用于截图的感知 dhash）。 受保护 / 无法访问的页面会被原样记录，不会进行任何绕过。 ### 3. OSINT 丰富化 ``` curl -X POST http://localhost:8000/submissions//enrich ``` 域名 -> WHOIS/RDAP（注册商，创建日期）+ Certificate Transparency (crt.sh)。IP -> ASN/托管商 (RIPEstat) + 地理定位。 每项数据都包含其**来源**及其 **Admiralty 评分** （可靠性 A–F，可信度 1–6）。查询绝不会触及恶意基础设施： 指标仅作为参数传递给第三方服务。 ### 4. 钓鱼工具包指纹识别 ``` curl -X POST http://localhost:8000/submissions//fingerprint ``` 将捕获的 HTML 和 favicon 哈希与可扩展的特征库进行比对 （`api/src/smishwatch/data/kit_signatures.json` — 法国特色家族：假冒 La Poste、AMELI、 税务、CPF、银行顾问）。在提交记录中填充 `kit_family` + 分数。 ### 5. 聚类至 Campaign ``` curl -X POST http://localhost:8000/submissions//cluster ``` 将提交记录归入共享相同工具包 + 基础设施 (ASN) 组合的 **Campaign**。 此操作是增量式的：具有相同工具包 + ASN 的新提交记录会加入现有的 Campaign。 ### 6. 查看报告和 Campaign ``` curl http://localhost:8000/submissions/ # fiche complète curl http://localhost:8000/submissions # 50 dernières soumissions curl http://localhost:8000/campaigns # campagnes curl http://localhost:8000/campaigns/ # timeline + indicateurs agrégés ``` 报告汇总了各项指标，包含展开链、已哈希的 artifacts、 带评分的丰富化信息以及识别出的工具包。Campaign 展示其提交时间线和聚合指标。 ### 7. 生成证据包 ``` curl -X POST http://localhost:8000/submissions//bundle # crée le bundle curl -OJ http://localhost:8000/bundles//download # télécharge le .zip curl -X POST http://localhost:8000/bundles//verify ``` 证据包是一个 ZIP 文件，包含 artifacts 以及一个 `manifest.json`，其中列出了每个 文件的 SHA-256 和指标，并附有时间戳。 验证过程会重新计算所有哈希值：如果检测到篡改 -> `ok: false`。 RFC 3161 时间戳是可选接入的 (TSA)；如果未配置 TSA，证据包依然可以通过重新计算 哈希值进行自我验证。 ### 8. 导入 Feed (关联分析) ``` curl -X POST http://localhost:8000/feeds/urlhaus/ingest curl -X POST http://localhost:8000/feeds/openphish/ingest curl -X POST http://localhost:8000/feeds/phishtank/ingest # nécessite PHISHTANK_API_KEY ``` URLhaus / OpenPhish / PhishTank 的 **只读** 连接器： 每个条目都会创建一个提交记录，并通过共享的指标与现有的 Campaign 进行 **关联**。响应结果会指出导入的条目数量和所关联的 Campaign 数量。 ## 开发 通过 Docker 运行 Lint 和测试： ``` make lint make test ``` 在 Windows (PowerShell) 环境下，不使用 `make` (在 `api/` 目录下，已激活 venv)： ``` ruff check src tests black --check src tests mypy src pytest ``` ## CI/CD 与安全 三个具有最小权限的 GitHub Actions 工作流 (`.github/workflows/`)： - **`ci.yml`** — 强制性的质量门禁：backend (`ruff`、`black --check`、 `mypy --strict`、`pytest`) 和 frontend (`eslint`、`tsc`、`next build`)。 - **`codeql.yml`** — CodeQL Python + TypeScript 静态分析 (SAST)，使用 `security-extended` 查询，在 push/PR 时以及每周一运行。 - **`security.yml`** — 密钥扫描 (**gitleaks**，强制性)，依赖审计 (**pip-audit**、**npm audit**)，以及 **Trivy**（漏洞、密钥、 配置错误），并在 *Security* 选项卡中输出 SARIF。 **`.github/dependabot.yml`** 会保持 pip、npm、Docker 和 GitHub Actions 依赖项的 更新（每周）。 ### 应用加固 - **CORS** 限制在 `CORS_ORIGINS`（默认为 `http://localhost:3000`），不使用 cookies。 - 在所有 API 响应上设置**安全响应头**（`X-Content-Type-Options`、 `X-Frame-Options: DENY`、`Referrer-Policy`、`Permissions-Policy`、 `Content-Security-Policy: frame-ancestors 'none'`），Next.js 端同样适用。 - 按 IP 进行 **Rate limiting**（`RATE_LIMIT_PER_MINUTE`，默认 120/min）-> `429`。 - **可选的 API Key 身份验证**：如果定义了 `API_KEY`，所有路由 （除 `/health` 外）都需要 `X-API-Key` 请求头（常数时间比较）。 默认不启用，以便于本地开发。 - 根目录包含 `LICENSE` (MIT) 和 `SECURITY.md`（披露政策）。 ## 环境变量 请参考 `.env.example`。`.env` 绝不会被提交。 | 变量 | 描述 | | ----------------- | -------------------------------------------- | | `APP_ENV` | `development` / `production` | | `LOG_LEVEL` | 日志级别 | | `DATABASE_URL` | DSN SQLAlchemy async (asyncpg) | | `USER_AGENT` | 诚实且可识别的 User-Agent | | `PII_SECRET_KEY` | 用于加密 PII 的 Fernet 密钥 | | `FETCH_TIMEOUT` | 传出请求的超时时间 (秒) | | `FETCH_MAX_REDIRECTS` | 最大跟随的重定向次数 | | `FETCH_MAX_BYTES` | 每次响应读取的最大大小 | | `FETCHER_URL` | Playwright fetcher 服务的内部 URL | | `FETCHER_TIMEOUT` | 页面渲染的超时时间 (秒) | | `ARTIFACT_DIR` | 存储 artifacts 的目录 | | `FETCH_MAX_URLS` | 每次提交捕获的最大 URL 数量 | | `KIT_SIGNATURES_PATH` | 工具包特征库 (覆盖) | | `BUNDLE_DIR` | 证据包的目录 | | `FEED_MAX_ENTRIES`| 每个 feed 导入的最大条目数 | | `PHISHTANK_API_KEY` | PhishTank API 密钥 (否则禁用 feed) | | `CORS_ORIGINS` | 允许的来源 (CSV)，默认为 localhost:3000 | | `RATE_LIMIT_PER_MINUTE` | 请求限制/IP/分钟 (超出则返回 429) | | `API_KEY` | 如果定义，则要求提供 `X-API-Key` 请求头 | | `POSTGRES_*` | Postgres 容器参数 | ## 项目状态 - [x] **阶段 0** — 脚手架与基础 (FastAPI `/health`、Postgres、代码质量) - [x] **阶段 1** — 摄取与 SSRF 防护 (Defang 提取、PII 保险库、短链接展开) - [x] **阶段 2** — 沙箱化 Playwright Fetch 与 artifacts (HTML/截图/favicon、哈希值) - [x] **阶段 3** — OSINT 丰富化 (WHOIS/RDAP、CT、ASN、地理定位) + Admiralty 评分 - [x] **阶段 4** — 工具包指纹识别 (可扩展特征) + Campaign 聚类 - [x] **阶段 5** — Next.js Dashboard (提交、报告、Campaign、Defang/Refang) - [x] **阶段 6** — 可验证的证据包与 Feed 导入 (URLhaus/OpenPhish/PhishTank)

标签：ESC4, OSINT, 反钓鱼, 域渗透, 威胁情报, 安全沙箱, 开发者工具, 测试用例, 版权保护, 特征检测, 电子数据取证, 请求拦截, 逆向工具