donny-devops/threathunter-api

# ThreatHunter API **漏洞情报平台** — 一个生产级的 FastAPI 服务，用于聚合、评分和查询 CVE 数据，提供基于 CVSS 的风险分析，并支持从 NIST 国家漏洞数据库（NVD）实时同步。      ## 功能 - **完整的 CRUD API** — 通过 RESTful endpoint 创建、读取、更新和删除漏洞记录 - **NVD 实时同步** — 后台从 NIST NVD 2.0 API 导入数据，支持可配置的关键词种子 - **CVSS 风险评分** — 基于 CVSS v3.1/v3.0/v2.0 分数自动进行严重性分类，并提供人类可读的风险评级 - **高级过滤** — 支持按严重等级、CVSS 分数范围，以及对描述/厂商/产品的关键词搜索进行查询 - **分页结果** — 基于 offset 的分页，提供总数和页面元数据 - **仪表盘分析** — 聚合统计 endpoint，包含严重性分布、CVSS 平均值和最新 CVE 跟踪 - **全异步架构** — 基于 async SQLAlchemy + aiosqlite，实现非阻塞 I/O - **Docker 开箱即用** — 支持单命令部署，包含健康检查和持久化卷 - **CI/CD Pipeline** — GitHub Actions 工作流，包含代码检查、类型检查、多版本测试和 Docker 冒烟测试 ## 技术栈 | 层级 | 技术 | |-------|-----------| | 框架 | FastAPI 0.115+ | | ORM | SQLAlchemy 2.0 (async) | | 数据库 | SQLite (aiosqlite) — 可无缝切换至 PostgreSQL | | 数据验证 | Pydantic v2 | | HTTP Client | httpx (async) | | 测试 | pytest + pytest-asyncio | | 代码检查 | Ruff | | 类型检查 | mypy (strict mode) | | 容器化 | Docker + Docker Compose | | CI/CD | GitHub Actions | ## 快速开始 ### 本地开发 ``` # Clone 代码仓库 git clone https://github.com/donny-devops/threathunter-api.git cd threathunter-api # 创建虚拟环境 python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\Activate.ps1 # Windows PowerShell # 安装依赖 pip install -e ".[dev]" # 配置环境 cp .env.example .env # 编辑 .env — 可选添加你的 NVD API key 以获得更高的速率限制 # 运行服务器 uvicorn src.main:app --reload --port 8000 ``` ### Docker ``` # 构建并运行 docker compose up --build -d # 健康检查 curl http://localhost:8000/health ``` ## API 参考 服务启动后，可通过以下地址访问交互式文档： - **Swagger UI** → `http://localhost:8000/docs` - **ReDoc** → `http://localhost:8000/redoc` ### Endpoints | 方法 | Endpoint | 描述 | |--------|----------|-------------| | `GET` | `/health` | 存活探针 | | `GET` | `/api/v1/vulnerabilities` | 列出 CVE（支持分页和过滤） | | `GET` | `/api/v1/vulnerabilities/{cve_id}` | 根据 ID 获取单个 CVE | | `POST` | `/api/v1/vulnerabilities` | 手动创建 CVE 记录 | | `PATCH` | `/api/v1/vulnerabilities/{cve_id}` | 局部更新 | | `DELETE` | `/api/v1/vulnerabilities/{cve_id}` | 删除 CVE 记录 | | `GET` | `/api/v1/dashboard` | 聚合分析 | | `POST` | `/api/v1/sync` | 触发 NVD 同步 | ### 查询参数（列表 Endpoint） | 参数 | 类型 | 描述 | |-----------|------|-------------| | `page` | int | 页码（默认：1） | | `page_size` | int | 每页结果数，1–100（默认：25） | | `severity` | string | 过滤条件：CRITICAL, HIGH, MEDIUM, LOW | | `keyword` | string | 搜索 CVE ID、描述、厂商、产品 | | `min_cvss` | float | 最低 CVSS 分数（0–10） | | `max_cvss` | float | 最高 CVSS 分数（0–10） | ### 示例请求 ``` # 列出严重漏洞 curl "http://localhost:8000/api/v1/vulnerabilities?severity=CRITICAL&page_size=10" # 搜索 SQL injection CVEs curl "http://localhost:8000/api/v1/vulnerabilities?keyword=SQL+injection" # 获取仪表盘统计信息 curl http://localhost:8000/api/v1/dashboard # 使用自定义关键字触发 NVD 同步 curl -X POST "http://localhost:8000/api/v1/sync?keyword=privilege+escalation" # 创建手动 CVE 条目 curl -X POST http://localhost:8000/api/v1/vulnerabilities \ -H "Content-Type: application/json" \ -d '{ "cve_id": "CVE-2024-99999", "description": "Critical RCE in ExampleLib allowing unauthenticated remote code execution.", "severity": "CRITICAL", "cvss_score": 9.8, "cwe_id": "CWE-78", "vendor": "example_corp", "product": "example_lib" }' ``` ## 测试 ``` # 运行完整测试套件 pytest -v # 运行并生成覆盖率报告 pytest --cov=src --cov-report=term-missing -v # Lint ruff check src/ tests/ # Type check mypy src/ --ignore-missing-imports ``` ## 项目结构 ``` threathunter-api/ ├── .github/workflows/ci.yml # CI/CD pipeline ├── src/ │ ├── main.py # FastAPI app + lifespan │ ├── config.py # Pydantic settings │ ├── database.py # Async SQLAlchemy engine │ ├── models.py # ORM models │ ├── schemas.py # Pydantic request/response schemas │ ├── routers/ │ │ ├── vulnerabilities.py # CRUD endpoints │ │ ├── dashboard.py # Analytics endpoint │ │ └── sync.py # NVD sync trigger │ └── services/ │ ├── vuln_service.py # Business logic + risk scoring │ └── sync_service.py # NVD API integration ├── tests/ │ └── test_api.py # 14 async integration tests ├── Dockerfile ├── docker-compose.yml ├── pyproject.toml ├── .env.example └── .gitignore ``` ## 开源协议 MIT — 详情请参阅 [LICENSE](LICENSE)。

标签：AV绕过, FastAPI, GPT, REST API, SIEM集成, 威胁情报, 威胁情报集成, 安全规则引擎, 开发者工具, 漏洞管理, 请求拦截, 运行时操纵, 逆向工具