Janhouse/dtrack-docker-scanner

# 用于 Dependency-Track 的 Docker SBOM 扫描器 一个 Docker 容器扫描器，可自动为运行中的容器生成软件物料清单 (SBOMs)，并将其上传至 [OWASP Dependency-Track](https://dependencytrack.org/) 以进行漏洞分析。 ## 功能特性 - 启动时扫描所有正在运行的 Docker 容器 - 监听 Docker 事件，自动扫描新容器 - 使用 [Trivy](https://trivy.dev/) 生成 CycloneDX SBOMs - 将带有适当标签的 SBOMs 上传至 Dependency-Track - 按主机名将项目归类到父项目下 - 当容器版本变更时，克隆漏洞分析决策 - 当容器被移除时，自动清理过期的项目 - 当容器长时间停止时，将项目标记为非活跃状态 - 缓存最近扫描的镜像列表以避免重复扫描 - 通过 cron 表达式配置扫描计划 ## 快速开始 ### 使用 Docker Compose 1. 复制示例环境文件： cp .env.example .env 2. 编辑 `.env` 并填入你的 Dependency-Track 凭证： DTRACK_URL=https://dependency-track.example.com DTRACK_API_KEY=your-api-key-here 3. 启动扫描器： docker compose up -d 要使用自定义镜像，请设置 `SCANNER_IMAGE`： SCANNER_IMAGE=my-registry/dtrack-docker-scanner:v1.0.0 docker compose up -d ### 使用 Docker Run ``` docker run -d \ --name dtrack-docker-scanner \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -e DTRACK_URL=https://dependency-track.example.com \ -e DTRACK_API_KEY=your-api-key \ ghcr.io/janhouse/dtrack-docker-scanner:latest ``` ## 配置 所有配置均通过环境变量完成： ### 必需配置 | 变量 | 描述 | |----------|-------------| | `DTRACK_URL` | Dependency-Track API URL (例如 `https://dtrack.example.com`) | | `DTRACK_API_KEY` | 具有创建/更新项目和上传 BOMs 权限的 API key | ### 可选配置 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `SCAN_INTERVAL` | `0 */6 * * *` | 用于计划扫描的 cron 表达式 | | `SCAN_ON_START` | `true` | 在容器启动时运行全面扫描 | | `EXCLUDE_IMAGES` | `` | 要跳过的镜像名称模式的逗号分隔列表 | | `DTRACK_PARENT_PROJECT` | `` | 用于将所有已扫描容器归类其下的父项目名称 | | `SCANNER_HOSTNAME` | `` | 用于标记项目的主机名 | | `CLEANUP_STALE` | `true` | 移除不再运行的容器的项目 | | `SCAN_CONCURRENCY` | `2` | 并发 SBOM 上传的数量 | | `WATCH_DOCKER` | `true` | 监听 Docker 事件以获取新容器 | | `CACHE_TTL_MINUTES` | `60` | 缓存已扫描镜像哈希值的时长（分钟） | | `INACTIVE_AFTER_MINUTES` | `60` | 容器停止多长时间后将项目标记为非活跃（分钟） | | `INITIAL_CLEANUP_DELAY_MINUTES` | `3` | 初始扫描后延迟清理的时间，以便其他容器启动（分钟） | | `TZ` | `UTC` | 用于 cron 计划的时区 | ## 工作原理 ### 容器扫描 1. 启动时，扫描器会列出所有正在运行的 Docker 容器 2. 对于每个容器，它会使用 Trivy 生成 CycloneDX SBOM 3. SBOM 会被上传至 Dependency-Track，并附带以下标签： - 镜像基础名称 - `host:` - 标识容器运行所在的主机 - `docker-scanner` - 将其标记为由扫描器管理 - `compose:` - compose 项目名称（如果适用） - `imageid:` - 用于去重的 Docker 镜像哈希值 ### Docker 事件监听 当 `WATCH_DOCKER=true` 时，扫描器会监听 Docker 事件： - **容器启动**：立即扫描新容器（如果最近未扫描过） - **容器停止/死亡**：跟踪已停止的容器，并在配置的超时时间后将它们标记为非活跃状态 ### 项目生命周期 - 新容器会在 Dependency-Track 中创建新项目 - 当容器镜像更新时，分析决策将从旧版本克隆 - 成功克隆后，旧版本将被删除 - 在配置的超时时间后，已停止的容器会被标记为非活跃状态（而非删除） - 重新启动的容器会自动恢复为活跃状态 ### 去重 扫描器通过以下方式避免冗余扫描： 1. 检查最近扫描的镜像哈希值的本地缓存 2. 查询 Dependency-Track 中具有匹配 `imageid:` 标签的现有项目 3. 仅扫描在任一缓存中都不存在的镜像 ## 开发 ### 前置条件 - [Bun](https://bun.sh/) - Docker ### 设置 ``` # 安装 dependencies bun install # 在开发模式下运行 bun run dev # Type 检查 bun run typecheck # Linting bun run lint bun run lint:fix ``` ### 构建 ``` # 构建 Docker image docker build -t dtrack-docker-scanner . # 或者使用 compose docker compose build ``` ## CI/CD 工作流 本项目包含用于自动构建和 SBOM 生成的 Gitea Actions 工作流。 ### 构建器工作流 (`.gitea/workflows/build.yml`) 构建 Docker 镜像并将其推送到容器镜像仓库。 **输入参数：** - `custom_tags` - 逗号分隔的版本标签（例如 `v1.0.0,v1.0`） - `push_to_github` - 同时推送到 GitHub Container Registry **必需的仓库变量：** - `REGISTRY_URL` - 主容器镜像仓库 URL - `REPOSITORY_IMAGE` - 完整的镜像引用地址（例如 `registry.example.com/org/image:latest`） - `GHCR_IMAGE` - GitHub Container Registry 镜像（例如 `ghcr.io/org/image:latest`） **必需的 Secrets：** - `REGISTRY_USERNAME` - 主镜像仓库用户名 - `REGISTRY_ACCESS_TOKEN` - 主镜像仓库密码/token - `GHCR_USERNAME` - GitHub 用户名 - `GHCR_TOKEN` - 具有 `write:packages` 权限范围的 GitHub personal access token ### SBOM 工作流 (`.gitea/workflows/sbom.yml`) 为已构建的容器生成 SBOM 并上传到 Dependency-Track。在成功构建后自动运行。 **输入参数：** - `include_github` - 同时为 `github-latest` 版本上传 SBOM - `custom_tags` - 逗号分隔的用于上传 SBOMs 的版本标签 **必需的 Secrets：** - `ACTIONS_GITEA_TOKEN` - 用于在工作流之间下载 artifacts 的 token - `DEPENDENCY_TRACK_URL` - Dependency-Track API URL - `DEPENDENCY_TRACK_API_KEY` - Dependency-Track API key - `DEPENDENCY_TRACK_PROJECT_NAME` - Dependency-Track 中的项目名称 ### 检查工作流 (`.gitea/workflows/checks.yml`) 在 pull request 和 push 时运行 linting 和类型检查。 ## Dependency-Track API 权限 API key 需要以下权限： - `BOM_UPLOAD` - 上传 SBOMs - `PROJECT_CREATION_UPLOAD` - 自动创建项目 - `VIEW_PORTFOLIO` - 列出和搜索项目 - `PORTFOLIO_MANAGEMENT` - 更新项目属性，删除项目 ## 许可证 AGPL-3.0

标签：DevSecOps, Docker, GPT, SBOM, 上游代理, 安全合规, 安全防御评估, 漏洞管理, 版权保护, 硬件无关, 网络代理, 自动化攻击, 请求拦截