README
¶
imagegate is a Docker authorization plugin. It denies container creation
unless the image digest carries a cosign
signature from an identity you trust and a signed SPDX or CycloneDX SBOM
attestation. It runs on the host, next to dockerd, so Dockerfiles, Compose
files and docker run commands stay exactly as they are.
$ docker run ghcr.io/acme/api:1.4.2
docker: Error response from daemon: authorization denied by plugin imagegate: imagegate: denied ghcr.io/acme/api@sha256:3f9c…
reason: NO_SBOM — no SPDX or CycloneDX attestation signed by identity "ci-main"
fix: https://wiki.acme.internal/imagegate#no_sbom
Documentation · Getting started · Policy reference · Runbook · Security model
How it works
Only POST /containers/create, /start and /restart are ever denied.
Every other call passes, even when imagegate errors, so it can't lock you
out of the daemon.
- Verifies by digest. Tags resolve through dockerd to the digest it will run, and start re-checks the container's actual image.
- Real Sigstore. Keyless (Fulcio, SCT, Rekor, TUF trusted root) or your
own public keys; cosign v2
.sig/.atttags and v3 bundles via OCI referrers. - Fast when warm. One verification per digest and policy, cached in memory and on disk. Concurrent requests share it.
- Built for rollout. Audit mode, ticketed break-glass overrides that expire within 7 days, a JSON audit log and Prometheus metrics.
Install
Releases ship .deb, .rpm and .apk packages, archives and a container
image for amd64, arm64, arm/v7, ppc64le and s390x, all with SBOMs and
cosign signatures.
# Debian / Ubuntu (rpm and apk work the same way)
curl -fsSLO https://github.com/rossedman/imagegate/releases/download/v0.1.0/imagegate_0.1.0_amd64.deb
sudo apt install ./imagegate_0.1.0_amd64.deb
sudoedit /etc/imagegate/policy.yaml && imagegate validate # starts in audit mode
sudo systemctl start imagegate && imagegate health
# then add {"authorization-plugins": ["imagegate"]} to /etc/docker/daemon.json:
sudo systemctl restart docker
Packages install a systemd service (deb, rpm) or an OpenRC service (apk),
never edit daemon.json, and refuse removal while dockerd still enables the
plugin (apk can only warn). The image is ghcr.io/rossedman/imagegate. See
Getting started
for every install method and how to verify a release.
Then follow Rolling out and Signing in CI.
[!WARNING] A dead authorization plugin makes dockerd reject every API call. Read the lockout runbook before enabling imagegate.
A minimal policy
apiVersion: imagegate.dev/v1
mode: enforce
identities:
ci-main:
issuer: https://token.actions.githubusercontent.com
subjectRegExp: ^https://github\.com/acme/.+/\.github/workflows/release\.ya?ml@refs/heads/main$
rules:
- name: internal
images: ["ghcr.io/acme/**"]
signature: { identities: [ci-main] }
sbom: { identities: [ci-main] }
Status
imagegate is new and pre-1.0. It has unit tests for the full verification matrix (keyless and keyed, both cosign layouts, multi-platform images, tampered and replayed signatures) and an end-to-end suite against a real dockerd, a zot registry and cosign v2 and v3. Read the security model for what it does not cover: it proves where an image came from, not what a container may do.
Contributing
Issues and pull requests are welcome; see CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
imagegate
command
Command imagegate is a Docker authorization plugin that denies container creation unless the image is cosign-signed by a trusted identity and carries a signed SBOM attestation.
|
Command imagegate is a Docker authorization plugin that denies container creation unless the image is cosign-signed by a trusted identity and carries a signed SBOM attestation. |
|
internal
|
|
|
admin
Package admin serves root-only maintenance commands (warm, cache purge) on a Unix socket, and the client the CLI uses to call them.
|
Package admin serves root-only maintenance commands (warm, cache purge) on a Unix socket, and the client the CLI uses to call them. |
|
audit
Package audit writes one structured JSON record per decision.
|
Package audit writes one structured JSON record per decision. |
|
authz
Package authz implements Docker's authorization plugin protocol.
|
Package authz implements Docker's authorization plugin protocol. |
|
cache
Package cache stores verdicts by (repository, digest, policyHash) in an in-memory LRU backed by a bbolt file, so a restart does not cause a burst of cold verifications.
|
Package cache stores verdicts by (repository, digest, policyHash) in an in-memory LRU backed by a bbolt file, so a restart does not cause a burst of cold verifications. |
|
docker
Package docker is a minimal dockerd API client for the two inspect calls imagegate needs.
|
Package docker is a minimal dockerd API client for the two inspect calls imagegate needs. |
|
gate
Package gate decides whether a container create or start may proceed.
|
Package gate decides whether a container create or start may proceed. |
|
imageref
Package imageref normalizes Docker image references.
|
Package imageref normalizes Docker image references. |
|
metrics
Package metrics defines imagegate's Prometheus metrics.
|
Package metrics defines imagegate's Prometheus metrics. |
|
policy
Package policy loads, validates and hashes the imagegate policy file.
|
Package policy loads, validates and hashes the imagegate policy file. |
|
verdict
Package verdict defines reason codes and the verdicts imagegate caches, logs and returns to dockerd.
|
Package verdict defines reason codes and the verdicts imagegate caches, logs and returns to dockerd. |
|
verify
Package verify checks that an image digest carries a cosign signature and a signed SBOM attestation from identities allowed by a policy rule.
|
Package verify checks that an image digest carries a cosign signature and a signed SBOM attestation from identities allowed by a policy rule. |