Rajarshi-Kar/cloud-security-scanner

# 云安全扫描器 用于扫描 Docker 镜像和源代码仓库中的漏洞、密钥和配置错误的生产级平台。 有关代码库统计信息、完整技术栈和 API 概览，请参阅 [PROJECT_REPORT.md](PROJECT_REPORT.md)。 ## 批次计划 - [x] **Batch 1** — 仓库脚手架、Docker Compose、认证（JWT + bcrypt + RBAC）、数据库/Repository/Service 层 - [x] **Batch 2** — Project/Scan/Vulnerability/Report 模型 + Projects/Scans API - [x] **Batch 3** — 仓库扫描器：克隆仓库、Gitleaks（密钥）、Semgrep + pip-audit/Safety（依赖）、Celery worker - [x] **Batch 4** — Docker 扫描器：镜像上传、Trivy 层/漏洞分析 - [x] **Batch 5** — 仪表盘聚合：安全评分、趋势、最近扫描、严重问题 - [x] **Batch 6** — 报告：PDF/JSON 导出、CVE 链接 - [x] **Batch 7** — 前端构建：扫描上传 UI、结果表格、仪表盘图表（Recharts）、搜索/过滤 - [x] **Batch 8** — 测试（Pytest）、CI（GitHub Actions）、Nginx 部署配置、Swagger 完善 ## 运行 Batch 1 ``` cp backend/.env.example backend/.env # edit JWT_SECRET_KEY docker compose -f docker/docker-compose.yml up --build ``` - 后端：http://localhost:8000/docs - 前端：http://localhost:5175（主机端口 5175 -> 容器中运行在 5173 的 Vite 开发服务器；如果你想使用不同的主机 端口，请修改 `docker/docker-compose.yml` 中的 `frontend` 端口映射，并同步更新 `backend/.env` 中的 `CORS_ORIGINS`） - 请求 `POST /api/v1/auth/register`，然后通过 `/auth/login` 获取 JWT，使用 `/auth/me` 验证 RBAC 角色声明。 ## Batch 2 说明 新增实体：`Project`（归用户所有）、`Scan`（repository 或 docker_image 类型，状态生命周期为 pending->running->completed/failed）、`Vulnerability`（严重程度/来源/CVE）、`Report`（pdf/json，目前仅添加了 schema 但尚未生成——将在 Batch 6 实现）。 新增端点：`POST/GET /projects`、`GET/DELETE /projects/{id}`、`POST/GET /projects/{id}/scans`、 `GET /scans/{id}`、`GET /scans/{id}/vulnerabilities`。所有权在 `ProjectService.get_owned` 中强制执行—— 非管理员只能查看自己的项目。创建扫描只会插入一条 `pending` 记录；真正运行 Gitleaks/Semgrep/Trivy 的 Celery worker 将在 Batch 3/4 引入。 ## Batch 3 说明 带有 `scan_type: "repository"` 的 `POST /projects/{id}/scans` 现在会执行实际工作：它会在新的 `worker` 容器（Celery + Redis）上将 `scan_repository_task` 加入队列。该任务会将仓库浅克隆到临时目录中，运行 Gitleaks（密钥）、Semgrep `--config=auto`（SAST），并对找到的任何 `requirements*.txt` 运行 pip-audit + Safety，将结果转换为 `Vulnerability` 记录，将 `Scan.status` 设置为 `completed`/`failed`，并计算 `security_score`（100 减去基于严重程度的扣分）。轮询 `GET /scans/{id}` 获取状态，轮询 `GET /scans/{id}/vulnerabilities` 获取结果。 引擎代码位于 `backend/app/scanner/`（每个工具一个模块 + `engine.py` 负责编排）； Celery 配置位于 `backend/app/workers/`。工具作为子进程调用——`gitleaks` 在 Docker 镜像中作为二进制文件安装，`semgrep`/`pip-audit`/`safety` 是 pip 包。Docker 镜像扫描（Trivy）及其 worker 路径属于 Batch 4。 ## Batch 4 说明 有两种方法可以通过 Trivy 扫描 Docker 镜像： - 带有 `scan_type: "docker_image"` 和 `target: ""` 的 `POST /projects/{id}/scans`（例如 `nginx:1.27`）——Trivy 直接拉取并扫描它，无需上传。 - `POST /projects/{id}/scans/docker-image`（multipart）上传通过 `docker save` 导出的 `.tar` 文件——该文件 会被写入 `UPLOAD_DIR`（通过现有的 bind mount 在 `backend`/`worker` 之间共享）， 使用 `trivy image --input` 进行扫描，并在扫描完成后删除。 `backend/app/scanner/image_scanner.py` 将 Trivy 的 JSON `Results[].Vulnerabilities[]` 解析为与仓库扫描器相同的 `Finding` 结构，因此 `Vulnerability` 记录和 `security_score` 公式（位于 `backend/app/scanner/scoring.py`，由两个引擎共享）在不同扫描类型之间是 一致的。Trivy 在后端 Docker 镜像中通过其官方安装脚本进行安装。 ## Batch 5 说明 `GET /dashboard/summary` 为整个仪表盘返回一个 payload：已完成扫描的平均 `security_score`、项目/扫描计数、严重程度细分（所有漏洞中每种严重程度的计数）、最近 5 次扫描、最近 10 条严重/高危发现，以及用于趋势图的 14 天每日漏洞计数。所有的聚合 SQL 位于 `backend/app/repositories/dashboard_repository.py`（关联 Vulnerability→Scan→Project，普通用户范围限定为 `Project.owner_id`，管理员不限范围）。 前端：`DashboardPage.tsx` 通过 React Query 将其接入到统计卡片以及两个 Recharts 组件（严重程度柱状图、漏洞趋势折线图）中。 ## Batch 6 说明 带有 `{"format": "json"}` 或 `{"format": "pdf"}` 的 `POST /scans/{id}/reports` 会根据扫描持久化的漏洞生成报告 文件（仅在 `Scan.status == completed` 时允许）， 将其写入 `REPORTS_DIR` 下，并记录一条 `Report` 数据。`GET /scans/{id}/reports` 列出过去的 报告；`GET /reports/{id}/download` 以流式方式传回文件。 - JSON 报告（`app/reporting/json_report.py`）：扫描元数据 + 发现结果，当存在 `cve_id` 时，每一个发现都带有一个通过 `CVE_LOOKUP_URL`（NVD）构建的 `cve_url`。 - PDF 报告（`app/reporting/pdf_report.py`，通过 `reportlab`）：包含相同 CVE 值的发现结果表格，这些值会被渲染为可点击的链接，并按严重程度着色。 ## Batch 7 说明 新页面，均位于 `ProtectedRoute` 之后并共享一个 `Layout`/`NavBar`： - `/projects` — 创建 + 列出项目。 - `/projects/:projectId` — 创建仓库扫描（目标 URL）或为镜像扫描上传 `docker save` 导出的 `.tar` 文件；每 5 秒实时轮询一次扫描列表。 - `/scans/:scanId` — 轮询扫描状态直到 `completed`/`failed`，然后显示漏洞 表格，支持客户端搜索（标题/包/CVE）、严重程度过滤、日期排序、指向 NVD 的可点击 CVE 链接，以及连接到 Batch 6 端点的报告生成/下载（JSON/PDF）功能。 报告下载通过 `apiClient`（blob + object URL）进行，而不是普通的 ``，因为 下载端点需要 JWT bearer 标头——直接通过浏览器导航不会携带该标头。 ## Batch 8 说明 - **测试**：`backend/tests/` 使用内存中的 SQLite 数据库（通过覆盖 `get_db` 依赖项）并 将 Celery 任务的 `.delay` monkeypatch 为无操作，因此运行测试套件不需要 Postgres/Redis ：`cd backend && pytest -v`。涵盖认证（register/login/me、重复邮箱、错误 密码、缺失 token）、项目所有权隔离以及扫描创建/所有权检查。 - **CI**：`.github/workflows/ci.yml` 会在每次推送/PR 时运行 `pytest`，并为前端运行 `npm run build`（`tsc -b && vite build`），作为两个并行任务执行。 - **Nginx / 生产部署**：`docker/docker-compose.prod.yml` + `frontend/Dockerfile.prod` 将 React 应用构建为由 Nginx（`frontend/nginx.conf`）提供服务的静态文件，Nginx 同时 将 `/api/` 反向代理到后端。后端/worker 运行时不带 `--reload` 且不带 开发环境的 bind mount。使用 `docker compose -f docker/docker-compose.prod.yml up --build` 运行。 - **Swagger**：`/docs` 现在拥有真实的标题、描述、版本以及基于标签的描述 （auth/projects/scans/reports/dashboard），而不是 FastAPI 简单的默认值。 ## 全部 8 个批次已完成 实现了 design.md/tech_stack.md 中的完整垂直切片：JWT+RBAC 认证、项目、 通过 Celery 进行仓库扫描（Gitleaks/Semgrep/pip-audit/Safety）和 Docker 镜像扫描（Trivy）、 带有聚合指标的仪表盘、带有 CVE 链接的 PDF/JSON 报告、完整的 React 前端，以及测试/CI/生产部署配置。扩展目标（GitHub OAuth、定时扫描、 邮件提醒、将 GitHub Actions 集成*到扫描中*、多项目工作区）尚未启动。 首次迁移（容器启动后）： ``` docker compose -f docker/docker-compose.yml exec backend alembic revision --autogenerate -m "create users table" docker compose -f docker/docker-compose.yml exec backend alembic upgrade head ```