HarborGuard开发者指南如何快速接入新的容器镜像仓库Provider含4种认证模式【免费下载链接】HarborGuardModern image vulnerability scanning patching platform with multi-tool integration.项目地址: https://gitcode.com/gh_mirrors/ha/HarborGuardHarborGuard 是一款现代化的容器镜像漏洞扫描与补丁平台支持多扫描工具集成。它的核心能力之一是通过Registry Provider镜像仓库提供者架构对接各种容器镜像仓库——Docker Hub、GHCR、GitLab、ACR、Nexus、Gitea 等。本文将带你像开发者一样理解这套架构并手把手教你为 HarborGuard 快速接入一个新的镜像仓库 Provider重点拆解项目中沉淀的4 种认证模式。一、Registry Provider 是什么为什么需要它不同镜像仓库的 API 风格、认证方式、限流策略各不相同。如果把这些差异直接写进业务代码代码会迅速变成一团乱麻。HarborGuard 用抽象基类 工厂模式解决了这个问题抽象基类RegistryProvider 定义了所有 Provider 必须实现的方法契约列镜像、取 Tag、测连接、返回认证头等增强基类EnhancedRegistryProvider 额外内置了基于 skopeo 的镜像拉取/推送/检查能力以及 401 令牌挑战处理等通用工具新 Provider 可以白嫖这些能力工厂RegistryProviderFactory 负责根据仓库类型RepositoryType枚举自动创建对应 Provider找不到专属 Provider 时会回退到通用的GenericOCIProvider。src/lib/registry/providers/ ├── base/ # 抽象基类 增强基类内置 skopeo 操作 ├── dockerhub/ # Docker HubJWT Bearer Token ├── ghcr/ # GitHub 容器注册表PAT Bearer Token ├── gitlab/ # GitLab 容器注册表PRIVATE-TOKEN ├── acr/ # 阿里云 ACRBasic Auth ├── nexus/ # NexusBasic Auth ├── gar/ # Google Artifact RegistryOAuth2 JWT ├── gitea/ # Gitea/ForgejoToken Challenge ├── generic/ # 通用 OCI 回退实现 └── RegistryProviderFactory.ts # 工厂注册与分发官方还配套了完整的贡献文档 docs/ADDING-A-REGISTRY.md建议与本文对照阅读。二、快速开始用脚手架脚本一键生成 Provider 骨架项目内置了脚手架脚本 scripts/create-provider.sh一条命令即可生成带完整 TODO 注释的 Provider 模板./scripts/create-provider.sh harbor Harbor Registry脚本会自动把harbor转成 PascalCase 类名HarborProvider在src/lib/registry/providers/harbor/下创建 Provider 文件预置配置接口、认证头、连接测试、镜像列表等方法的骨架代码打印接下来的注册步骤清单。模板里每个抽象方法都写明了该做什么你只需要把 TODO 替换成目标仓库的真实逻辑即可。三、核心难点4 种容器仓库认证模式全解析认证是接入新 Provider 最容易踩坑的部分。HarborGuard 现有 Provider 覆盖了 4 种典型模式基本能应对所有主流仓库。模式 1Basic Auth基础认证 最简单直接把用户名:密码做 Base64 编码放进请求头。适用仓库阿里云 ACR、Nexus、通用 OCI 仓库实现要点两个方法必须配对// 用于 HTTP API 调用 async getAuthHeaders(): PromiseRecordstring, string { const auth Buffer.from( ${this.config.username}:${this.config.password} ).toString(base64); return { Authorization: Basic ${auth} }; } // 用于 skopeo 拉取镜像 async getSkopeoAuthArgs(): Promisestring { return --creds ${this.config.username}:${this.config.password}; } 注意 HarborGuard 的双通道设计getAuthHeaders()服务于 REST API 调用getSkopeoAuthArgs()服务于 skopeo 命令行拉取镜像两者要覆盖同一种认证方式。模式 2Bearer Token静态令牌 直接用长期有效的 Token 作为Authorization: Bearer token请求头。适用仓库GHCR使用 GitHub PAT、Docker Hub通过hub.docker.com登录接口换取的 JWTasync getAuthHeaders(): PromiseRecordstring, string { return { Authorization: Bearer ${this.config.token}, Accept: application/vnd.github.v3json }; }可以参考 GHCRProvider 和 DockerHubProvider 的完整实现。模式 3Docker v2 Token Challenge令牌挑战 这是标准 Docker Registry v2 协议的经典流程首次请求返回401并在Www-Authenticate头里给出令牌端点地址realm、服务标识service和作用域scope客户端拿着 Basic 认证去令牌端点换取短期 Bearer Token再重试原请求。好消息是——基类已经帮你封装好了handleTokenChallenge(response)解析 401 挑战头自动完成令牌交换makeAuthenticatedRequestWithChallenge(url)包装 fetch遇到 401 自动走挑战流程并重试。所以你的listImages()只需换成一个方法调用const url ${this.getBaseUrl()}/v2/_catalog; const response await this.makeAuthenticatedRequestWithChallenge(url);适用仓库Gitea/Forgejo、Harbor、Quay 等遵循 OCI 规范的仓库。实现细节见 EnhancedRegistryProvider。模式 4OAuth2 JWT Grant服务账号签名换令牌 最复杂的一种使用云厂商服务账号的私钥签名 JWT再拿去 OAuth2 端点换取有时效的 Access Token并且要自己管理令牌缓存与过期刷新。适用仓库Google Artifact RegistryGCP 服务账号 JSON 密钥// 1. 用私钥 RS256 签名 JWT → 2. 换取 access_token → 3. 缓存到过期前 60 秒 async getSkopeoAuthArgs(): Promisestring { await this.ensureValidToken(); return --creds _dcgcloud_token:${this.accessToken}; }两个加分技巧覆写基类的refreshAuth()方法实现令牌刷新skopeo 命令失败时基类会自动检测认证错误并调用它重试令牌过期时间提前 60 秒失效避免令牌刚好过期的竞态。完整实现可参考 GARProvider。四、必须实现的 11 个方法脚手架已经帮你列好了这里按元数据 / 认证 / 数据三类快速过一遍类别方法作用元数据getProviderName/getSupportedCapabilities/getRateLimits名称、能力清单、限流参数配置parseConfig/validateConfiguration从Repository记录解析配置并校验必填字段认证getAuthHeaders/getSkopeoAuthArgs/testConnection三种认证出口API 请求头、skopeo 参数、连通性自检数据listImages/getImageMetadata/getTags镜像列表、元数据、Tag 列表引用formatFullImageReference拼接registry/ns/image:tag全限定镜像名另外还有一个静态方法canHandle(repository)供工厂做仓库识别判断repository.type或registryUrl特征。镜像列表有两种取法标准仓库走GET /v2/_catalog非标准仓库如 GAR、GitLab走各自的 REST API详见 docs/ADDING-A-REGISTRY.md 的 Image Listing 章节。五、注册 Provider四步让 HarborGuard 识别你的新仓库1️⃣ 添加 RepositoryType 枚举值如需要在 prisma/schema.prisma 的RepositoryType枚举中加入新类型现有 11 种DOCKERHUB、GHCR、GITLAB、GENERIC、ECR、GCR、ACR、HARBOR、NEXUS、ARTIFACTORY、QUAY、GITEA然后执行数据库迁移npx prisma migrate dev --name add-my-new-type2️⃣ 在工厂中注册编辑 RegistryProviderFactory在静态块中this.register(MY_TYPE, MyNewProvider)并在createFromRepository()中加一段canHandle判断。⚠️ 关键细节一定要放在GenericOCIProvider判断之前否则会被通用回退逻辑截胡。3️⃣ 添加配置接口在 src/lib/registry/types.ts 中定义你的配置接口如GARConfig、NexusConfig继承RegistryConfig基接口。4️⃣ 添加 UI 配置表单在 src/components/repository-config/ 下新增表单组件字段需与parseConfig()期望一致。用户随后就能在仓库页面像配置其他仓库一样完成接入。六、提交前测试清单官方 Checklist按 docs/ADDING-A-REGISTRY.md 的验收标准逐项打勾✅testConnection()对合法凭据成功、对错误凭据给出清晰报错✅listImages()/getTags()/getImageMetadata()返回真实数据✅validateConfiguration()能拦住缺失字段✅formatFullImageReference()产出的镜像引用 skopeo 能正常拉取✅canHandle()对匹配仓库返回 true其余返回 false✅ HTTPS 与 HTTP 仓库的 TLS 校验均正常接入成功后新仓库的镜像即可出现在扫描任务中漏洞结果统一汇入平台的漏洞库结语HarborGuard 的 Provider 架构把接入一个新镜像仓库变成了三件事选对认证模式4 选 1、实现 11 个契约方法、四步注册。配合脚手架脚本和内置的 skopeo/令牌挑战能力大部分标准 OCI 仓库半天内就能跑通。接下来你可以阅读 docs/ADDING-A-REGISTRY.md 了解各认证模式的完整代码示例研究 src/lib/registry/providers/ 下 8 个现成 Provider 作为模板运行 scripts/create-provider.sh 开始你的第一个 Provider 【免费下载链接】HarborGuardModern image vulnerability scanning patching platform with multi-tool integration.项目地址: https://gitcode.com/gh_mirrors/ha/HarborGuard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
