HarborGuard扫描流水线代码剖析一次镜像扫描请求从ScanQueue到6大扫描器的全流程【免费下载链接】HarborGuardModern image vulnerability scanning patching platform with multi-tool integration.项目地址: https://gitcode.com/gh_mirrors/ha/HarborGuardHarborGuard 是一款现代化的容器镜像扫描与修复平台它把一次镜像扫描请求拆解成一条清晰可控的扫描流水线请求先经接口校验进入 ScanQueue 优先级队列再由 Go 编写的 sensor 传感器统一调度 Trivy、Grype、Syft、OSV-Scanner、Dockle、Dive 这 6 大扫描器并行工作最后将报告结构化落库并实时推送到前端界面。本文带你走读这条镜像扫描流水线的完整链路从 API 接口的第一行校验代码到队列的优先级调度再到六大扫描器各扫一摊、结果四张表落库的全过程帮你建立对整套扫描引擎的完整认知。 全景视图一次镜像扫描要闯过的 6 道关卡在看代码之前先建立整体地图。一次扫描请求依次经过以下站点API 入口POST /api/scans/start校验参数、预检扫描器可用性数据库预登记DatabaseAdapter为镜像和扫描记录建档优先级队列ScanQueue按优先级排序并控制并发扫描数模式分发SensorBridge决定本地直跑还是派发给远程 agent六大扫描器执行sensor 二进制调用 6 个 CLI 工具产出报告结果落库 实时推送JSON 报告写入结构化数据表进度经 SSE 推到前端 请求入口/api/scans/start 如何把关流水线的第一关是 route.ts 中的POST处理器它做三件关键的事Zod 参数校验单个扫描需提供image tag或tarPath批量请求一次最多 100 个镜像每 5 个一批并发提交避免瞬间打满资源扫描器可用性预检调用detectScanMode()如果既没有可用的本地 sensor 也没有已注册的 agent直接返回 503提前拦截注定失败的请求审计日志每次启动扫描都通过auditLogger.scanStart()留痕校验通过后请求以统一的ScanRequest结构交给核心服务并支持priority-10 到 10参数为任务设定优先级。⏱️ ScanQueue 队列优先级排序与并发控制队列逻辑集中在 ScanQueue.ts。它是一个基于全局单例的内存队列核心机制非常直观机制说明优先级排序新任务入队时按priority降序 入队时间升序重排高优先级任务先执行并发上限processQueue()只在运行中任务数小于config.maxConcurrentScans默认 3时才放出新任务事件驱动通过scan-queued、scan-started、scan-completed、scan-cancelled四类事件解耦队列与执行器排队透明度对外暴露队列位置、预估等待时间、队列统计前端可以显示排队中第 2 位任务出队时状态置为running队列发出scan-started事件——这是整条流水线的发令枪。️ 数据库预登记DatabaseAdapter 先为扫描建档在任务入队前ScannerService.ts 的startScan()会先生成带时间戳的requestId然后调用 DatabaseAdapter.ts 的initializeScanRecord()预登记按来源分三条路径registry 来源解析镜像名中的仓库地址通过RegistryProviderFactory创建对应仓库Docker Hub、GHCR、GCR、ECR、GitLab 等的 provider 去 inspect 镜像拿 digest再以事务 upsert 镜像记录 创建扫描记录local 来源直接调用本地 Docker API 检查镜像取 digest 建档tar 来源为上传的 tar 包生成占位 digest 建档这一步保证了即使扫描还没跑前端列表里已经能看到一条运行中的扫描记录用户体验上不出现空白等待。 SensorBridge本地直跑 vs 分布式派发任务出队后SensorBridge.ts 的detectScanMode()决定执行路径agent-dispatch分布式模式只要数据库中存在ACTIVE状态的 sensor agent就创建一条AgentJob记录写入数据库立刻释放队列槽位——真正的扫描在远程 sensor 容器里完成完成后由 agent 回传结果local-sensor单体模式检查/app/sensor/harborguard-sensor二进制是否存在存在则通过execFile直接执行 sensor CLI超时 30 分钟unavailable两者皆无标记扫描失败并给出明确错误提示本地模式有一个值得细看的健壮性设计见 executeScanViaSensor即使 sensor CLI 因 stderr 日志而非零退出只要 stdout 中仍有合法 JSON 报告也会尝试解析并采用——避免因日志输出导致整次扫描被误判失败。️ 六大扫描器各扫一摊覆盖漏洞、SBOM、合规与效率sensor 是一个 Go 编写的二进制源码位于 harborguard-sensor/在 Dockerfile 的第一个构建阶段编译它接收scan 镜像引用 --source 来源 --output json指令内部并行调度六大扫描器。六大扫描器分工如下扫描器职责对应结果维度Trivy综合漏洞扫描CVE、配置、密钥泄露漏洞发现GrypeAnchore 出品的包漏洞匹配引擎漏洞发现OSV-ScannerGoogle 开源漏洞库OSV匹配漏洞发现Syft生成 SBOM 软件物料清单软件包清单Dockle基于 CIS 基准的镜像安全体检合规检查Dive逐层分析镜像结构与膨胀浪费效率分析可以看到三个漏洞扫描器交叉验证降低漏报Syft 负责这个镜像里到底有什么Dockle 负责配置合不合规Dive 负责层结构健不健康——六个视角拼出一张完整的镜像安全画像。六大 CLI 工具在 Dockerfile 的 runtime 阶段统一安装并配置缓存目录。每个扫描器都实现了统一的IScannerBase接口scan()getVersion()想接入第 7 个扫描器官方文档 docs/ADDING-A-SCANNER.md 提供了从零到一的完整教程。 结果落库一份 JSON 信封变成四张结构化表扫描完成后sensor 输出一个标准化的ScanEnvelopeJSON 信封包含镜像信息、四类 findings 和聚合指标。ingestEnvelope 负责把信封拆开入库Scan 记录更新状态SUCCESS / PARTIAL / FAILED、风险评分、结束时间ScanMetadata写入五级漏洞计数critical/high/medium/low/info、合规评分、各扫描器版本号四类归一化发现表scanVulnerabilityFinding漏洞、scanPackageFindingSBOM 包、scanComplianceFinding合规、scanEfficiencyFinding效率所有扫描器的输出都经严重级别归一化后汇入统一视图这套设计让前端无论用哪个扫描器都能在同一套界面上查看结果。 进度实时推送ProgressTracker 到扫描详情页整个过程中ProgressTracker.ts 持续把ScanProgressEvent状态、百分比、当前步骤广播给所有监听者最终通过 SSE 推送到浏览器前端在扫描详情页实时显示运行中 30% — Running sensor scan这样的进度条。结果呈现上前端为每个扫描器准备了独立的结果页签src/components/scan-results/ 下的 TrivyResultsTab、GrypeResultsTab 等 6 个组件同时提供统一的漏洞、软件包、合规、效率四个归一化页签src/components/scan/findings/还支持 PDF / XLSX 报告导出。⚙️ 上手调优3 个环境变量决定流水线节奏部署时可以通过环境变量微调这条流水线的吞吐详见 README.md 的环境变量说明变量默认值作用MAX_CONCURRENT_SCANS3ScanQueue 同时执行的扫描数资源紧张调小、性能充足调大SCAN_TIMEOUT_MINUTES30单次扫描的超时上限ENABLED_SCANNERS全部 6 个按需裁剪如只跑trivy,grype可显著提速 总结一张流程图记住整条流水线回顾这次镜像扫描请求的完整旅程API 校验建档 → ScanQueue 优先级排队 → SensorBridge 选择本地/分布式执行 → sensor 调度 6 大扫描器 → JSON 信封落库四张表 → SSE 实时推送前端几个值得借鉴的架构亮点队列与执行解耦事件驱动的 ScanQueue 让并发控制、排队查询、取消操作互不干扰执行路径可插拔同一个ingestEnvelope同时服务本地直跑和 agent 回传两种模式单体与分布式部署结果格式完全一致归一化视图六大扫描器各产原始报告但前端只看统一的四类发现换工具零成本如果你想继续深入建议按此顺序阅读源码ScannerService.ts执行调度核心、SensorBridge.ts模式分发与结果入库再看 docs/ADDING-A-SCANNER.md 理解扩展机制即可完全掌握 HarborGuard 的扫描引擎设计。【免费下载链接】HarborGuardModern image vulnerability scanning patching platform with multi-tool integration.项目地址: https://gitcode.com/gh_mirrors/ha/HarborGuard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考