# 验证镜像签名

API7 使用开源容器镜像签名工具 [Cosign](https://www.sigstore.dev/) 保护 Docker 容器镜像。所有签名都存储在公共 Docker Hub 仓库 `api7/notary` 中。构建和发布流程通过 GitHub Actions 使用 GitHub 的 OIDC 身份提供商进行无密钥签名，确保镜像真实且未被修改。

部署前验证镜像签名可以保护组织免受供应链攻击，并确保运行的每个容器都由 API7.ai 生成。

## 前置条件[​](#前置条件 "前置条件的直接链接")

在执行验证的计算机上安装以下工具：

1. [Cosign](https://www.sigstore.dev/)——用于验证容器镜像签名。
2. [regctl](https://regclient.org/install/)——用于获取容器镜像摘要。

## 验证流程[​](#验证流程 "验证流程的直接链接")

### 1. 设置签名仓库[​](#1-设置签名仓库 "1. 设置签名仓库的直接链接")

API7 签名与镜像分开存储。将 Cosign 指向专用签名仓库：

```
export COSIGN_REPOSITORY=api7/notary
```

### 2. 获取镜像摘要[​](#2-获取镜像摘要 "2. 获取镜像摘要的直接链接")

使用 `regctl` 获取待验证镜像的 SHA-256 摘要：

```
regctl manifest digest api7/api7-ee-3-gateway:3.9.1
```

输出示例：

```
sha256:61a531d7ca8339712888bfdf7ad7af6d63f0e423e466818be96f0aaa3fc89578
```

### 3. 运行 Cosign 验证[​](#3-运行-cosign-验证 "3. 运行 Cosign 验证的直接链接")

对固定到摘要的镜像执行 `cosign verify` 命令，并指定签署镜像的 GitHub Actions 工作流的证书身份：

```
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'
```

验证成功表示：

* Cosign 声明已通过验证。
* 签名已记录在公共透明日志中。
* 代码签名证书已通过可信证书颁发机构验证。

## 证书身份参考[​](#证书身份参考 "证书身份参考的直接链接")

每个 API7 企业版镜像都由特定的 GitHub Actions 工作流签名。运行 `cosign verify` 时，请使用与待验证镜像匹配的证书身份正则表达式：

| 镜像                               | 证书身份正则表达式                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------- |
| `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`       |

## 在 Kubernetes 中验证[​](#在-kubernetes-中验证 "在 Kubernetes 中验证的直接链接")

对于 Kubernetes 环境，建议使用 [Kyverno](https://kyverno.io/) 或 [Sigstore Policy Controller](https://docs.sigstore.dev/policy-controller/overview/) 等策略引擎，在允许 Pod 启动之前自动验证镜像签名。使用上文相同的 `COSIGN_REPOSITORY`、OIDC 颁发者和证书身份正则表达式值配置策略。

## 不要部署未经验证的镜像[​](#不要部署未经验证的镜像 "不要部署未经验证的镜像的直接链接")

如果验证失败，Cosign 会以非零状态退出并输出错误详情。**不要部署验证失败的镜像**。请先调查失败原因；验证失败可能意味着镜像被篡改、访问透明日志时发生网络问题，或待验证镜像使用了错误的证书身份正则表达式。

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

* 查看 API7 镜像的[漏洞扫描](https://docs.apiseven.com/api7-gateway/security-and-compliance/vulnerability-scanning.md)实践。
* [审计日志](https://docs.apiseven.com/api7-gateway/security-and-compliance/audit-logs.md)：跟踪部署事件。
