SA2208/URLcheaker

# URLCHEAKER URLCHEAKER 是一款面向防御和 SOC 的 URL 分流应用程序。它将精确的威胁情报源匹配与确定性的词法特征提取以及可插拔的分类器结合在一起。它返回 `malicious`（恶意）、`benign`（良性）或 `uncertain`（不确定），并且在默认分析路径中绝不会访问提交的目标地址。 ## 已实现组件 - 带有严格 URL 验证和规范化的 FastAPI REST API。 - 精确匹配的本地威胁情报源层。 - 确定性的词法特征提取。 - 明确的不确定性阈值。 - 带有可选 HMAC 制品验证的 PyCaret 模型加载器。 - 隐私保护的分析历史和分析员裁定。 - React/TypeScript 分析员界面。 - PostgreSQL 生产配置和 SQLite 本地配置。 - Docker Compose 部署。 - 单元、集成、前端、对抗性和 CI 脚手架。 - 数据验证和分组 PyCaret 训练流水线。 - 安全、数据、模型、测试、部署和 SOC 文档。 ## 架构 ``` Browser -> Nginx -> FastAPI -> URL normalization -> Threat-feed lookup -> Feature extraction -> Heuristic or PyCaret predictor -> Decision policy -> PostgreSQL ``` 该 API 不执行 DNS 解析、HTTP 请求、重定向、屏幕截图或页面渲染。网络扩充必须作为单独隔离的 worker 来实现。 ## 环境 - API: Python 3.11+ - ML 训练: Python 3.11, PyCaret 3.3.2 - Web: Node.js 24 LTS, React, TypeScript, Vite - 数据库: Docker 中的 PostgreSQL 17；SQLite 用于本地开发 ## 本地后端 ``` python3.11 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e ".[dev]" cp .env.example .env alembic upgrade head uvicorn urlchecker.main:app --reload --host 127.0.0.1 --port 8000 ``` 在生产模式之外，API 文档可在 `http://127.0.0.1:8000/docs` 获取。 ## 本地前端 ``` cd web npm install npm run dev ``` Vite 服务器将 `/api` 和 `/health` 代理到 `http://127.0.0.1:8000`。 ## Docker Compose ``` cp .env.example .env # 在部署前，请将 .env 中的 POSTGRES_PASSWORD 替换为生成的 secret。 docker compose up --build ``` 打开 `http://localhost:8080`。 ## 示例 API 请求 ``` curl --fail-with-body \ --request POST \ --header 'Content-Type: application/json' \ --data '{"url":"http://known-malware.test/dropper.exe"}' \ http://127.0.0.1:8000/api/v1/analyses ``` 代表性响应： ``` { "classification": "malicious", "threat_type": "malware", "decision_source": "threat_feed", "requires_analyst_review": false } ``` ## CLI ``` urlchecker 'https://www.example.com/docs?token=secret' ``` 查询值默认会从已存储和返回的历史记录中进行脱敏处理。 ## 测试 ``` pytest --cov=src/urlchecker --cov-report=term-missing ruff check . ruff format --check . mypy src bandit -c pyproject.toml -r src cd web npm test -- --run npm run lint npm run build ``` ## PyCaret 训练 使用专用的 Python 3.11 环境： ``` python3.11 -m venv .venv-ml source .venv-ml/bin/activate python -m pip install -e . python -m pip install -r ml/requirements.txt python ml/pipelines/validate_dataset.py --dataset data/sample_urls.csv python ml/pipelines/train_pycaret.py \ --dataset data/sample_urls.csv \ --output ml/models/urlchecker_pycaret ``` 训练流水线： 1. 提取与生产推理使用的相同特征。 2. 按可注册域名对 URL 进行分组。 3. 创建保留域名的测试集。 4. 使用分组交叉验证。 5. 比较、调优和校准 PyCaret 模型。 6. 写入模型元数据和评估指标。 合成样本仅用于流水线冒烟测试。生产环境的推行还需要基于时间和来源保留的评估。 可选的 DVC 和 MLflow 工具与核心 runtime 分离： ``` python -m pip install -r ml/requirements-ops.txt dvc repro validate_data dvc repro train ``` ## 启用 PyCaret 推理 ``` export URLCHECKER_MODEL_BACKEND=pycaret export URLCHECKER_MODEL_PATH=ml/models/urlchecker_pycaret export URLCHECKER_MODEL_VERSION=urlchecker-approved-version ``` 序列化的 Python 模型是可执行制品。仅加载内部生成的制品。进行 HMAC 验证： ``` export URLCHECKER_MODEL_HMAC_KEY='replace-with-a-secret-at-least-32-characters' python scripts/sign_model.py ml/models/urlchecker_pycaret.pkl ``` 在生产环境中请使用 secret manager。切勿提交 key 或签名工作流的机密信息。 ## 数据接入策略 `configs/data_sources.yaml` 记录了候选来源，但禁用了下载。在启用任何收集器之前： - 审查当前的提供商条款和 API 认证。 - 记录署名、再分发、保留和商业使用限制。 - 存储不可变快照和 SHA-256 校验和。 - 移除训练和测试之间重叠的 URL 和可注册域名。 - 排除冲突或不确定的标签。 - 切勿假设受欢迎程度就能证明其良性。 ## 安全限制 - 仅接受 HTTP 和 HTTPS 输入。 - 拒绝嵌入的凭据。 - 拒绝控制字符和无效的 IDNA。 - 默认流水线不执行任何出站请求。 - URL 会被转义，并且不会呈现为可点击的链接。 - 查询值会从历史记录中脱敏。 - 生产容器在无 root 权限且降低能力的情况下运行。 - 内存速率限制器仅供开发级别使用；对于多副本部署，请使用网关或基于 Redis 的限制器。 ## 仓库文档 - [架构](docs/architecture.md) - [威胁模型](docs/threat-model.md) - [数据卡片](docs/data-card.md) - [模型卡片](docs/model-card.md) - [测试策略](docs/testing.md) - [验证报告](docs/verification.md) - [部署与回滚](docs/deployment.md) - [SOC 运行手册](docs/soc-playbook.md) - [API 示例](docs/api.md) ## 局限性 - 词法信号无法观察页面内容或重定向后的行为。 - 威胁情报源存在覆盖范围和时效性限制。 - 低分不能证明安全。 - 启发式后端不是训练好的模型。 - 示例威胁情报源和数据集使用保留的演示域名。 - 对于面向公众的多用户部署，身份验证和分布式速率限制仍是后续发布加固的工作。

标签：测试用例, 请求拦截, 逆向工具