# Verify Image Signatures

API7 secures its Docker container images using [Cosign](https://www.sigstore.dev/), an open-source tool for container image signing. All signatures are stored in the public Docker Hub repository `api7/notary`. The build and release process uses GitHub Actions with GitHub's OIDC identity provider for keyless signing, ensuring the images are authentic and have not been modified.

Verifying image signatures before deployment protects your organization from supply chain attacks and guarantees that every container you run was produced by API7.ai.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Install the following tools on the machine that will run the verification:

1. [Cosign](https://www.sigstore.dev/) — to verify container image signatures.
2. [regctl](https://regclient.org/install/) — to retrieve the container image digest.

## Verification process[​](#verification-process "Direct link to Verification process")

### 1. Set the signature repository[​](#1-set-the-signature-repository "Direct link to 1. Set the signature repository")

API7 signatures are not stored alongside the image. Point Cosign at the dedicated signature repository:

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

### 2. Get the image digest[​](#2-get-the-image-digest "Direct link to 2. Get the image digest")

Retrieve the SHA-256 digest of the image you want to verify using `regctl`:

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

Example output:

```
sha256:61a531d7ca8339712888bfdf7ad7af6d63f0e423e466818be96f0aaa3fc89578
```

### 3. Run Cosign verification[​](#3-run-cosign-verification "Direct link to 3. Run Cosign verification")

Execute the `cosign verify` command against the image pinned to its digest, together with the certificate identity of the GitHub Actions workflow that signed the image:

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

A successful verification confirms:

* The Cosign claims were validated.
* The signature was recorded in the public transparency log.
* The code-signing certificate was verified via trusted certificate authorities.

## Certificate identity reference[​](#certificate-identity-reference "Direct link to Certificate identity reference")

Each API7 Enterprise image is signed by a specific GitHub Actions workflow. When you run `cosign verify`, use the certificate identity regular expression that matches the image you are verifying:

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

## Verification in Kubernetes[​](#verification-in-kubernetes "Direct link to Verification in Kubernetes")

For Kubernetes environments, we recommend using a policy engine such as [Kyverno](https://kyverno.io/) or [Sigstore Policy Controller](https://docs.sigstore.dev/policy-controller/overview/) to automatically verify image signatures before any pod is allowed to start. Configure the policy with the same `COSIGN_REPOSITORY`, OIDC issuer, and certificate identity regexp values shown above.

## Do not deploy unverified images[​](#do-not-deploy-unverified-images "Direct link to Do not deploy unverified images")

If verification fails, Cosign exits with a non-zero status and prints the error details. **Do not deploy images that fail verification.** Investigate the failure before continuing — a failed verification may indicate a tampered image, a network issue reaching the transparency log, or an incorrect certificate identity regexp for the image you are checking.

## Next steps[​](#next-steps "Direct link to Next steps")

* [Review Vulnerability Scanning](https://docs.api7.ai/api7-gateway/security-and-compliance/vulnerability-scanning.md) practices for API7 images.
* [Configure Audit Logs](https://docs.api7.ai/api7-gateway/security-and-compliance/audit-logs.md) to track deployment events.