mangrisano/cvewatcher

CVE Watcher 是一个可自托管的 FastAPI 服务，它能将你运行的软件列表转化为一个始终最新的漏洞影响视图。你只需注册资产（提供名称和版本即可），它就会按需或按计划查询 NIST NVD，然后对发现的结果进行去重，并按严重程度排序。 ``` # 添加一个 asset — 只需名称和版本 — 并列出其 CVE # （完整演练见下方的 End-to-End Example） curl -s "$BASE/assets/$ASSET/vulnerabilities" -H "Authorization: Bearer $TOKEN" | python3 -m json.tool # → 2 个漏洞 (CVE-2023-44487 HIGH 7.5 · CVE-2025-23419 MEDIUM 4.3) ``` ## 功能 - **资产清单** — 跟踪软件的名称、版本、可选的 CPE 和描述，并按用户进行隔离。 - **精准的 CVE 匹配** — NVD `cpeName` 查找会在服务端评估版本范围（不受关键词 100 条结果限制）。 - **自动解析 CPE** — 通过 NVD CPE 字典根据产品名称推导出 CPE。 - **关键词兜底** — 支持纯文本 NVD 搜索，并结合本地产品/版本过滤以减少干扰。 - **分类筛选** — 根据严重程度和时间窗口（过去 30/90/365 天）筛选发现的漏洞。 - **后台监控** — 可选的调度程序，可重新扫描资产并在发现新 CVE 时发出警报。 - **Web 仪表盘** — 单页 UI（原生 JS + Tailwind，无需构建步骤）。 - **安全的 JSON API** — JWT 认证，用户级隔离，在 `/docs` 和 `/redoc` 提供 OpenAPI 文档。 - **自托管** — PostgreSQL + Alembic 迁移，以 Docker 镜像形式发布于 GHCR。 ## 环境要求 - [Docker](https://docs.docker.com/get-docker/) 和 Docker Compose（推荐），**或者** - Python >= 3.12 和 PostgreSQL 数据库，用于本地运行 ## 快速开始 ``` git clone https://github.com/mangrisano/cvewatcher.git cd cvewatcher docker compose up --build ``` 然后打开： - API — http://localhost:8000 - 交互式文档 (Swagger UI) — http://localhost:8000/docs - Web 仪表盘 — http://localhost:8000/dashboard ## Web 仪表盘 自包含的 Web 仪表盘位于 [`/dashboard`](http://localhost:8000/dashboard)。 它无需构建步骤（通过 CDN 引入的原生 JS + Tailwind），可让你： - 使用你的 CVE Watcher 凭据登录（JWT 保存在 `localStorage` 中）。 - 添加包含名称、版本、CPE 和描述的资产。 - 浏览你的资产清单，**按名称和版本进行筛选**，并可以内联**编辑**或删除每个条目。 - 检查资产的漏洞，可通过**时间段**选择器（所有时间、过去 30/90/365 天）和**严重程度**（严重/高/中/低）进行筛选。每条记录都会显示 CVE ID（链接至 MITRE）、颜色编码的严重性徽章、CVSS 分数和摘要。 如果无法访问 NIST NVD 服务，仪表盘会显示明确的警告横幅，而不是返回空列表 — 只有当 NVD 确实报告没有匹配的 CVE 时，才会显示空结果。 ## 漏洞匹配原理 CVE Watcher 通过以下三种方式将资产与 CVE 进行匹配（自动选择）： 1. **CPE 查找** — 如果资产具有 CPE 2.3 ID，查询将委托给 NVD 的 `cpeName` 过滤器，该过滤器会在服务端评估版本范围。不完整的 CPE 会被填充为完整的 13 组件形式。 2. **自动解析 CPE** — 如果没有 CPE，则会在 NVD 的 CPE 字典（应用程序、操作系统和硬件）中查找产品名称，并追踪 `deprecatedBy` 链接。候选项仅在完全匹配（不区分分隔符）的 `product` 或 `vendor+product` 时才算作匹配，因此 `Apache HTTP Server` 会解析为 `apache:http_server`，而 `nginx` 绝不会匹配到 `nginx_proxy_manager`。随后会注入资产版本，并对每个解析出的组合执行步骤 1 中的查找。 3. **关键词搜索** — 在名称无法解析时的最后手段：通过 NVD 关键词搜索，并在本地通过产品标识和版本范围进行过滤；如果 CVE 不包含 CPE 数据，则回退至使用 CVE 摘要进行匹配。 ## 后台监控与通知 应用程序可以定期根据 NIST NVD 扫描每个已注册的资产，并在发现新漏洞时发出警报。此功能为**非强制启用**，通过环境变量进行配置（参见 `.env.example`）： | 变量 | 默认值 | 描述 | | -------------------------- | --------- | ------------------------------------------- | | `MONITOR_ENABLED` | `false` | 启用后台调度程序 | | `MONITOR_INTERVAL_MINUTES` | `360` | 扫描间隔分钟数 | | `NOTIFY_CONSOLE` | `true` | 通过应用程序 logger 记录新发现 | | `NOTIFY_WEBHOOK_URL` | _(未设置)_ | 将新发现以 JSON 格式 POST 到此 URL | 启用后，扫描将在启动时运行，然后按配置的间隔运行；只有新检测到的 CVE 才会触发通知。 ## API 端点 ### 认证 - `POST /auth/register` - 注册新用户 - `POST /auth/login` - 用户登录 - `POST /auth/refresh` - 刷新访问令牌 - `POST /auth/logout` - 用户登出 ### 资产管理 - `POST /assets/` - 创建新资产 - `GET /assets/` - 列出用户资产 - `GET /assets/{asset_id}` - 获取特定资产详情 - `PATCH /assets/{asset_id}` - 更新资产信息 - `DELETE /assets/{asset_id}` - 移除资产 ### CVE 监控 - `GET /assets/{asset_id}/vulnerabilities` - 获取特定资产的漏洞 - `GET /assets/{asset_id}/monitor` - 监控单个资产的 CVE - `POST /assets/monitoring/scan-all` - 扫描所有用户资产 - `GET /assets/monitoring/report` - 生成监控报告 ### CVE 数据 - `GET /cves/fetch-recent` - 从 NIST NVD 获取并存储最新的 CVE - `GET /cves/recent` - 列出最近存储的 CVE - `GET /cves/search` - 按产品（及可选版本）搜索 CVE - `GET /cves/vulnerabilities` - 检查所有资产中的漏洞 ### 用户与健康检查 - `GET /user` - 获取当前用户的个人资料 - `GET /health` - 服务健康检查 ### Web UI - `GET /dashboard` - 单页 Web 仪表盘（资产和漏洞） ## 技术栈 - **后端**：FastAPI (Python) - **数据库**：PostgreSQL 与 SQLAlchemy ORM - **认证**：使用 joserfc 的 JWT - **数据迁移**：Alembic - **任务调度**：APScheduler（可选的后台监控） - **容器**：Docker 与 Docker Compose - **外部 API**：NIST NVD API 集成 ## 部署 CVE Watcher 以 Docker 镜像和 Compose 堆栈（app + PostgreSQL）的形式提供。 ### Docker Compose ``` docker compose up --build -d # start app + database in the background docker compose logs -f app # follow the application logs docker compose down # stop and remove the stack ``` ### 预构建镜像 (GHCR) 每个带有标签的版本发布都会推送到 `ghcr.io/mangrisano/cvewatcher`。你可以直接在自己的 Compose 文件或 `docker run` 中引用它，而无需在本地构建： ``` docker pull ghcr.io/mangrisano/cvewatcher:latest ``` 通过环境变量提供数据库 URL 和密钥（参见 `.env.example`）；切勿将默认配置用于生产环境。 ## 端到端示例 一个从零开始到列出 CVE 的完整流程，仅使用 API 即可完成。同样的操作也可以在[仪表盘](http://localhost:8000/dashboard)中通过点击实现。 ``` BASE=http://localhost:8000 # 1. 注册用户 curl -s -X POST "$BASE/auth/register" \ -H "Content-Type: application/json" \ -d '{"username":"ciso","email":"ciso@example.com","password":"Password123"}' # 2. 登录并捕获 JWT access token TOKEN=$(curl -s -X POST "$BASE/auth/login" \ -H "Content-Type: application/json" \ -d '{"email":"ciso@example.com","password":"Password123"}' \ | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])") # 3. 添加一个 asset — 只需名称和版本，无需 CPE ASSET=$(curl -s -X POST "$BASE/assets/" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name":"nginx","version":"1.24.0","description":"edge reverse proxy"}' \ | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])") # 4. 查询其漏洞（所有时间、任何严重程度） curl -s "$BASE/assets/$ASSET/vulnerabilities" \ -H "Authorization: Bearer $TOKEN" | python3 -m json.tool ``` 你可以使用查询参数来缩小结果范围： ``` # 仅 HIGH 严重程度，发布于过去 365 天内 curl -s "$BASE/assets/$ASSET/vulnerabilities?severity=HIGH&days=365" \ -H "Authorization: Bearer $TOKEN" | python3 -m json.tool ``` | 查询参数 | 值 | 含义 | | --------------- | -------------------------------------- | ---------------------------------------------------------------- | | `severity` | `CRITICAL` / `HIGH` / `MEDIUM` / `LOW` | 仅保留该严重级别的发现 | | `days` | 整数 (例如 `30`, `90`, `365`) | 仅包含过去 N 天内发布的 CVE；省略或设为 `0` 表示所有时间 | ## 开发 ``` uv sync # install dependencies into .venv uv run ruff check app tests # lint uv run ruff format --check app tests # formatting check uv run pytest -q # run the test suite ``` 测试套件 Mock 了 NIST NVD 客户端，因此永远不会请求外部网络。 ## 贡献 1. Fork 本仓库 2. 创建功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交你的更改 (`git commit -m 'Add some amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 发起 Pull Request ## 许可证 本项目基于 [MIT 许可证](LICENSE) 授权。

标签：AV绕过, Docker, FastAPI, Python, 占用监测, 安全防御评估, 无后门, 测试用例, 漏洞追踪, 网络测绘, 请求拦截, 资产管理, 逆向工具