验证 API7 镜像签名
为了保护软件供应链安全，API7 的 Docker 容器镜像遵循行业最佳实践，使用开源工具 Cosign 进行签名。所有签名都存储在公共 Docker Hub 仓库 api7/notary 中。我们的构建和发布流程使用 GitHub Actions，并利用 GitHub 的 OIDC (OpenID Connect) 身份对镜像进行签名，从而提供了额外的可信认证层。
通过验证镜像签名，你可以确信：
- 真实的来源：镜像是由 API7 的官方 GitHub Actions 工作流构建和发布的。
- 完整性：镜像从发布到拉取过程中的任何环节都没有被任何第三方修改。
本指南将向你展示验证 API7 镜像签名的过程。
前置条件
验证签名
要验证 API7 容器镜像签名，你需要配置签名仓库的位置，检索镜像摘要，并使用 Cosign 验证签名。
设置签名仓库
设置 COSIGN_REPOSITORY 环境变量以指定镜像存储签名的位置：
export COSIGN_REPOSITORY=api7/notary
获取镜像摘要
每个 Docker 镜像都有一个唯一的 SHA-256 摘要，代表其内容的快照。为了确保你验证的是确切的镜像内容（而不是可变的标签），请使用 regctl 检索镜像摘要：
regctl manifest digest api7/api7-ee-3-gateway:3.9.1
你应该会看到镜像的摘要：
sha256:61a531d7ca8339712888bfdf7ad7af6d63f0e423e466818be96f0aaa3fc89578
运行 Cosign 验证
获取 镜像摘要后，运行 cosign verify 命令来验证镜像签名。该命令将验证签名、证书链和相关的声明（claims）：
cosign verify \
'api7/api7-ee-3-gateway:3.9.1@sha256:61a531d7ca8339712888bfdf7ad7af6d63f0e423e466818be96f0aaa3fc89578' \
--certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
--certificate-identity-regexp='https://github.com/api7/api7-ee-3-gateway/.github/workflows/push-release-image.yaml'
如果验证成功，你将看到类似于以下的响应，其中包括已执行检查的摘要：
Verification for index.docker.io/api7/api7-ee-3-gateway@sha256:61a531d7ca8339712888bfdf7ad7af6d63f0e423e466818be96f0aaa3fc89578 --
The following checks were performed on each of these signatures:
- The cosign claims were validated
- Existence of the claims in the transparency log was verified offline
- The code-signing certificate was verified using trusted certificate authority certificates
该命令还输出一个 JSON 对象，其中包含有关签名的详细元数据，例如构建工作流、代码库和触发事件：
[
{
"critical":{
"identity":{
"docker-reference":"index.docker.io/api7/api7-ee-3-gateway"
},
"image":{
"docker-manifest-digest":"sha256:61a531d7ca8339712888bfdf7ad7af6d63f0e423e466818be96f0aaa3fc89578"
},
"type":"cosign container image signature"
},
"optional":{
"1.3.6.1.4.1.57264.1.1":"https://token.actions.githubusercontent.com",
"1.3.6.1.4.1.57264.1.2":"push",
"1.3.6.1.4.1.57264.1.3":"757582d641f7bdcad3c1299cb7da113224f4f383",
"1.3.6.1.4.1.57264.1.4":"Build And Push Release Docker Image",
"1.3.6.1.4.1.57264.1.5":"api7/api7-ee-3-gateway",
"1.3.6.1.4.1.57264.1.6":"refs/tags/v3.9.1",
"Bundle":{
"SignedEntryTimestamp":"MEUCIQCj1Xupisdx7YosnqpdByE6pGpeMzeRcBF3H6+wgK0txgIgCImsRsV+tG+96tVkGiXcr6iNifirhk7Q4lW+S3tuOX4=",
"Payload":{
"body":"eyJhcGlWZXJzaW9uIjoiMC4wLjEiLCJraW5kIjoiaGFzaGVkcmVrb3JkIiwic3BlYyI6eyJkYXRhIjp7Imhhc2giOnsiYWxnb3JpdGhtIjoic2hhMjU2IiwidmFsdWUiOiI4ZjAyMzdlYzRhNTBlMzkwNWFjYWQ1ZWExYzE4ODFmMzMyZWM4NmE3Y2Y5ZGQ0OWU2NmQwYmQyMTVjMDBiZDlhIn19LCJzaWduYXR1cmUiOnsiY29udGVudCI6Ik1FWUNJUUQrM1U2T1NFYnpoVk9qZlFFWnRSWmZpYlgrSWVyWWpxWEMzb1U1ZWozYTBBSWhBTENYSG1yRXUvUXhHVUlncTdSZDQ2cVhCQkVwQS9qbm03ZTJtR1B6TE8yeiIsInB1YmxpY0tleSI6eyJjb250ZW50IjoiTFMwdExTMUNSVWRKVGlCRFJWSlVTVVpKUTBGVVJTMHRMUzB0Q2sxSlNVaEJha05EUW05cFowRjNTVUpCWjBsVlN5ODNUVmM0YTNodlYyUjFkRTFCYnpkMVFYUmtOVFpZY21aTmQwTm5XVWxMYjFwSmVtb3dSVUYzVFhjS1RucEZWazFDVFVkQk1WVkZRMmhOVFdNeWJHNWpNMUoyWTIxVmRWcEhWakpOVWpSM1NFRlpSRlpSVVVSRmVGWjZZVmRrZW1SSE9YbGFVekZ3WW01U2JBcGpiVEZzV2tkc2FHUkhWWGRJYUdOT1RXcFpkMDFVUVRSTlJFMTVUa1JOZVZkb1kwNU5hbGwzVFZSQk5FMUVUWHBPUkUxNVYycEJRVTFHYTNkRmQxbElDa3R2V2tsNmFqQkRRVkZaU1V0dldrbDZhakJFUVZGalJGRm5RVVZoUzJzelRFVmlRa0psVWtsaFNsWTFVbGw1YVZod1dtRXZVUzlaVEU1bVVtbFhOVTBLZFhweGJFbFVka1ptUWxCQ1YyRTNjRXBLZFZoTGEwOVZSVmxZT0VOUmJHRXlNMmg1TkN0MlNXdFliRmRITm05elRVdFBRMEpoWTNkbloxZHFUVUUwUndwQk1WVmtSSGRGUWk5M1VVVkJkMGxJWjBSQlZFSm5UbFpJVTFWRlJFUkJTMEpuWjNKQ1owVkdRbEZqUkVGNlFXUkNaMDVXU0ZFMFJVWm5VVlZwVGtONUNtcFVVMUY1YzJsTU9XbE5NbU50Ym5wd1ltbEtNVTl2ZDBoM1dVUldVakJxUWtKbmQwWnZRVlV6T1ZCd2VqRlphMFZhWWpWeFRtcHdTMFpYYVhocE5Ga0tXa1E0ZDJObldVUldVakJTUVZGSUwwSkhaM2RhYjFwcllVaFNNR05JVFRaTWVUbHVZVmhTYjJSWFNYVlpNamwwVERKR2QyRlVZM1paV0VKd1Rua3hiQXBhVXpCNlRGZGthR1JIVmpOWldHdDJURzFrY0dSSGFERlphVGt6WWpOS2NscHRlSFprTTAxMlkwaFdlbUZETVhsYVYzaHNXVmhPYkV4WGJIUlpWMlJzQ2t4dWJHaGlWM2hCWTIxV2JXTjVPVEJaVjJSNlRETlpla3hxYTNWTlZFRTFRbWR2Y2tKblJVVkJXVTh2VFVGRlFrSkRkRzlrU0ZKM1kzcHZka3d6VW5ZS1lUSldkVXh0Um1wa1IyeDJZbTVOZFZveWJEQmhTRlpwWkZoT2JHTnRUblppYmxKc1ltNVJkVmt5T1hSTlFrbEhRMmx6UjBGUlVVSm5OemgzUVZGSlJRcENTRUl4WXpKbmQwNW5XVXRMZDFsQ1FrRkhSSFo2UVVKQmQxRnZUbnBWTTA1VVozbGFSRmt3VFZkWk0xbHRVbXBaVjFGNldYcEZlVTlVYkdwWmFtUnJDbGxVUlhoTmVrbDVUa2RaTUZwcVRUUk5la0Y0UW1kdmNrSm5SVVZCV1U4dlRVRkZSVUpEVGtOa1YyeHpXa05DUW1KdFVXZFZTRlo2WVVOQ1UxcFhlR3dLV1ZoT2JFbEZVbl",
"integratedTime":1767842673,
"logIndex":804165791,
"logID":"c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d"
}
},
"Issuer":"https://token.actions.githubusercontent.com",
"Subject":"https://github.com/api7/api7-ee-3-gateway/.github/workflows/push-release-image.yaml@refs/tags/v3.9.1",
"githubWorkflowName":"Build And Push Release Docker Image",
"githubWorkflowRef":"refs/tags/v3.9.1",
"githubWorkflowRepository":"api7/api7-ee-3-gateway",
"githubWorkflowSha":"757582d641f7bdcad3c1299cb7da113224f4f383",
"githubWorkflowTrigger":"push"
}
}
]
证书身份和工作流
--certificate-identity-regexp 参数确保签名证书与预期的 GitHub Actions 工作流匹配。这可以验证镜像是通过正确的自动化流程构建的。
由于每个 API7 镜像都是由特定的工作流发布的，因此你必须使用匹配的正则表达式进行验证。使用下表查找你正在验证的镜像证书对应的 --certificate-identity-regexp 值：
| 镜像名称 | 证书身份正则表达式 (Certificate Identity RegExp) |
|---|---|
api7/api7-ee-3-gateway | https://github.com/api7/api7-ee-3-gateway/.github/workflows/push-release-image.yaml |
api7/api7-ee-3-integrated | https://github.com/api7/api7ee-3-control-plane/.github/workflows/release.yaml |
api7/api7-ee-dp-manager | https://github.com/api7/api7ee-3-control-plane/.github/workflows/release.yaml |
api7/api7-ee-developer-portal | https://github.com/api7/api7ee-3-control-plane/.github/workflows/release.yaml |
api7/api7-ee-developer-portal-fe | https://github.com/api7/api7ee-developer-portal/.github/workflows/release.yml |