Add trusted identity to images by tonistiigi · Pull Request #51737 · moby/moby

tonistiigi · 2025-12-16T18:00:10Z

This PR adds a new Identity property to images visible with inspect command. This information describes the origin of the image contents, is verified by the daemon, and is immutable for the user. If the user retags the image to a different name, its identity remains immutable to the initial information.

This allows users to understand if the image content really is what it claims to be and can be used to make policy decisions.

Currently the image origin can be provided in three different ways:

Locally built images show their build ref that can be associated with BuildKit history API commands. Collecting this data is new and it will only be shown for images built with this PR. Depends on exporter: expose build ref to the exporter as part of buildinfo buildkit#6424
Pulled images show the registry location from where the image was pulled. This data was already saved for existing pulls.
Images that have a valid signed provenance attestation (cosign simplesigning or bundle format) are verified against trust roots and then can be inspected by the signature properties. This data is available for valid images since v29.1 . image: pull/load/save attestation manifest and signatures with image #51012 . These signatures persist when image is saved to tarball via docker save and loaded back later(to a different machine for example), and is the only way images created with docker load can currently be identified in a secure way.

Examples

Locally built image:

# docker inspect a24955b787
        "Identity": {
            "Build": [
                {
                    "Ref": "rm66qy4pboh3shq168ztcbu3j",
                    "CreatedAt": "2025-12-16T01:06:06.449507136Z"
                }
            ]
        }

Pulled image:

# docker inspect alpine
        "Identity": {
            "Pull": [
                {
                    "Repository": "docker.io/library/alpine"
                }
            ]
        }

Image signed with Docker Github Builder (currently experimental), proving artifact integrity against the source reference:

# docker image inspect tonistiigi/xx:master
        "Identity": {
            "Signature": [
                {
                    "Name": "Docker GitHub Builder Experimental (tonistiigi/xx@master)",
                    "Timestamps": [
                        {
                            "Type": "Tlog",
                            "URI": "https://rekor.sigstore.dev",
                            "Timestamp": "2025-12-04T07:42:20Z"
                        },
                        {
                            "Type": "TimestampAuthority",
                            "URI": "https://timestamp.sigstore.dev/api/v1/timestamp",
                            "Timestamp": "2025-12-04T07:42:20Z"
                        }
                    ],
                    "Signer": {
                        "CertificateIssuer": "CN=sigstore-intermediate,O=sigstore.dev",
                        "SubjectAlternativeName": "https://github.com/docker/github-builder-experimental/.github/workflows/bake.yml@8fc70909404a502fd0eca6601b99b32fa7192b03",
                        "Issuer": "https://token.actions.githubusercontent.com",
                        "BuildSignerURI": "https://github.com/docker/github-builder-experimental/.github/workflows/bake.yml@8fc70909404a502fd0eca6601b99b32fa7192b03",
                        "BuildSignerDigest": "8fc70909404a502fd0eca6601b99b32fa7192b03",
                        "RunnerEnvironment": "github-hosted",
                        "SourceRepositoryURI": "https://github.com/tonistiigi/xx",
                        "SourceRepositoryDigest": "a5592eab7a57895e8d385394ff12241bc65ecd50",
                        "SourceRepositoryRef": "refs/heads/master",
                        "SourceRepositoryIdentifier": "150307921",
                        "SourceRepositoryOwnerURI": "https://github.com/tonistiigi",
                        "SourceRepositoryOwnerIdentifier": "585223",
                        "BuildConfigURI": "https://github.com/tonistiigi/xx/.github/workflows/build.yml@refs/heads/master",
                        "BuildConfigDigest": "a5592eab7a57895e8d385394ff12241bc65ecd50",
                        "BuildTrigger": "push",
                        "RunInvocationURI": "https://github.com/tonistiigi/xx/actions/runs/19921023628/attempts/1",
                        "SourceRepositoryVisibilityAtSigning": "public"
                    },
                    "SignatureType": "bundle-v0.3"
                }
            ]

Manual cosign signature I created in laptop:

# docker pull tonistiigi/test:sig1
        "Identity": {
            "Signature": [
                {
                    "Name": "Self-Signed Local (GitHub: tonistiigi@gmail.com)",
                    "Timestamps": [
                        {
                            "Type": "Tlog",
                            "URI": "https://rekor.sigstore.dev",
                            "Timestamp": "2025-11-13T04:22:19Z"
                        },
                        {
                            "Type": "TimestampAuthority",
                            "URI": "https://timestamp.sigstore.dev/api/v1/timestamp",
                            "Timestamp": "2025-11-13T04:22:18Z"
                        }
                    ],
                    "Signer": {
                        "CertificateIssuer": "CN=sigstore-intermediate,O=sigstore.dev",
                        "SubjectAlternativeName": "tonistiigi@gmail.com",
                        "Issuer": "https://github.com/login/oauth"
                    },
                    "SignatureType": "bundle-v0.3"
                }
            ],
            "Pull": [
                {
                    "Repository": "docker.io/tonistiigi/test"
                }
            ]
        }

changelog:

New `Identity` field has been added to the inspect endpoint to show trusted origin information about the image. This includes build ref for locally built images, remote registry repository for pulled images, and verified signature information for images that contain a valid signed provenance attestation.

--

I think we should also add a caching layer to avoid the cost of rerunning the signature verification. Initially I thought we should add temporary opt-in for this until we have caching. But when testing I don't see any extra slowness for the user experience. I think caching is a requirement if we want to have a summary of identity information to the image list endpoint. If we want to give us more time to make potential changes in the struct I'm still ok with a temporary opt-in, but I'm not really sure if it should be in client or daemon side.

@dmcgowan @crazy-max @thaJeztah @colinhemmings

tonistiigi · 2025-12-16T18:06:50Z

go.mod

+	github.com/cyberphone/json-canonicalization v0.0.0-20241213102144-19d51d7fe467 // indirect
+	github.com/digitorus/pkcs7 v0.0.0-20230818184609-3a137a874352 // indirect
+	github.com/digitorus/timestamp v0.0.0-20231217203849-220c5c2851b7 // indirect
+	github.com/go-openapi/analysis v0.24.1 // indirect


I managed to remove ~800k lines of dependencies from sigstore verification. This is the main part of the remaining. I don't see any quick way to get rid of it unfortunately. Sigstore folks were ok to consider alternatives but this would be quite fundamental change in their upstreams.

tonistiigi · 2025-12-16T18:08:12Z

go.mod

 module github.com/moby/moby/v2

-go 1.24.3
+go 1.25.0


This was unfortunately forced on us in recent sigstore update (that we need to reduce dependencies) moby/policy-helpers#12 (review)

crazy-max · 2025-12-19T14:05:45Z

daemon/daemon.go

+		v, err := policyverifier.NewVerifier(policyverifier.Config{
+			StateDir: confDir,
+		})


I think we should be able to configure the update interval on daemon side and have a good default? Maybe require online as well? https://github.com/moby/policy-helpers/blob/9fcc1a9ec5c9573385c30ab81cac41e9da124f0e/verifier.go#L28-L29

Not against, but I think these are sort of advanced features that could be added later in a follow up.

daemon/containerd/image_inspect.go

api/types/image/image_inspect.go

thaJeztah · 2026-01-13T10:20:40Z

api/types/image/image_inspect.go

+	// DockerReference is the Docker image reference associated with the signature.
+	// This is an optional field only present in older hashedrecord signatures.
+	DockerReference string `json:"DockerReference,omitempty"`


What's a "Docker image reference"? Is that a "distribution" reference (name / tag) of the image? https://pkg.go.dev/github.com/distribution/reference

Wouldn't that always match the image that's inspected, or is this for situations where an image is tagged under multiple names?

Wondering if this should be a more generic term (not sure if we should consider this "docker" if it's defined by distribution 🤔)

This comes from https://github.com/containers/image/blob/a5061e5a5f00333ea3a92e7103effd11c6e2f51d/docs/containers-signature.5.md#criticalidentitydocker-reference .

This is actually an old signature format, only used by DHI atm for new images.

Wouldn't that always match the image that's inspected, or is this for situations where an image is tagged under multiple names?

No, as this is part of the reference, then it is immutable. It is like the name the signer gave to the image while singing. Eg. in DHI this is the upstream name of the image. If you mirror or copy DHI image under your org, this will remain the upstream name. So even if you pulled from your org, the signature can confirm that this is still the same image that was originally tagged as specific DHI name.

This comes from https://github.com/containers/image/blob/a5061e5a5f00333ea3a92e7103effd11c6e2f51d/docs/containers-signature.5.md#criticalidentitydocker-reference .

This is actually an old signature format, only used by DHI atm for new images.

Yeah it is recommended to use the Sigstore Bundle Format instead. Simple Signing is kinda deprecated now.

thaJeztah · 2026-01-13T10:25:35Z

daemon/containerd/image_inspect.go

+	identity, err := i.imageIdentity(ctx, target.Digest)
+	if err != nil {
+		log.G(ctx).WithError(err).Warn("failed to determine Identity property")
+	}


Given that this information is a new addition, and (technically) not available in older API versions, should we add an option to ImageInspectOpts to make inclusion optional (and gate it by API version?)?

moby/daemon/server/imagebackend/image.go

Lines 56 to 60 in 4d09d8c

// ImageInspectOpts holds parameters to inspect an image.

type ImageInspectOpts struct {

Manifests bool

Platform *ocispec.Platform

}

I don't think so. I think it is good that this doesn't require CLI side changes. The output is already a block of JSON for this specific API.

Oh, sorry, I was probably not clear; this is a backend option (so not user-facing) my thinking here was to add a boolean, then in the router set that boolean to true for API >= 1.53

That still means that it would require new CLI I think. I think it is nice that there aren't extra limitations like that (@colinhemmings). This is not an API where there would be some backward compatibility issues or changes in the current fields.

Older clients won't unmarshal it because it's not in the types they use, so the information won't be there, unless they dump the raw response.

I think it's fine just to version gate it and just set the Identity to nil on older versions.

This way we avoid complicating the backend implementation but still keep the backwards compatibility.

Older clients won't unmarshal it because it's not in the types they use, so the information won't be there, unless they dump the raw response.

No, this is not the case. I haven't built any new CLI in anywhere this has been tested. It would be impossible to use it atm if this was the case.

The CLI dumps the raw JSON, but clients following the API spec, or implementations using the unmarshaled response as returned by the client won't have the info.

daemon/containerd/image_inspect.go

thaJeztah · 2026-01-13T10:48:33Z

daemon/containerd/image_inspect.go

+	identity := &imagetypes.ImageIdentity{}
+
+	for k, v := range info.Labels {
+		if ref, ok := strings.CutPrefix(k, exporter.BuildRefLabel); ok {


Format here is something like moby/build.ref.docker.io/library/ubuntu:latest ? Is that also because the image can be tagged under different names?

I was curious why the ref wasn't part of the JSON value that's stored in the label 😅

This is not distribution reference. BuildRef is just a unique identifier for the build. You can make extra requests against buildkit with the identifier to extract more data.

I was curious why the ref wasn't part of the JSON value that's stored in the label 😅

There can be multiple refs for the same image contents. Putting it to the same value would mean it needs to be reencoded on each modification and creates race conditions and possible size limits. Easier if each build just adds own label.

daemon/internal/builder-next/exporter/wrapper.go

api/types/image/image_inspect.go

daemon/containerd/image_inspect.go

go.mod

crazy-max

LGTM

For TUF state/gc we can look at it as follow-up.

Can you PTAL @thaJeztah? Specially the api/swagger part? 🙏

daemon/containerd/image_inspect.go

thaJeztah · 2026-01-16T11:03:36Z

rebased after #51857 was merged, and moved some touch-up diffs to the right commit; need a slight cleanup / squash (the renames); I'll have a look at that later.

api/types/image/build_identity.go

thaJeztah · 2026-01-16T12:42:46Z

api/types/image/signer_identity.go


 // SignerIdentity contains information about the signer certificate used to sign the image.
-// This is certificate.Summary with deprecated fields removed and keys in Moby uppercase style.
+// This is [certificate.Summary] with deprecated fields removed and keys in Moby uppercase style.


I noticed the "and keys in Moby uppercase style" ...

Agh, this got lost when all the fields were copied again in #51737 (comment)

thaJeztah · 2026-01-16T12:43:36Z

api/types/image/signer_identity.go

But that only applies to the first 3 fields, but not for the other fields, which are lowercase; was that intentional?

Also curious what the //nolint:tagliatelle was for; is that because of the mixed upper/lowercase ?

edit: ah, probably copied from https://pkg.go.dev/github.com/sigstore/sigstore-go/pkg/fulcio/certificate#Extensions

thaJeztah · 2026-01-16T14:41:29Z

Squashed the last 3 commits with the first one.

thaJeztah · 2026-01-16T14:46:54Z

Opened a follow-up PR to add / discuss the API-version gate; inspect: add API-version gate for image identity #51862

thaJeztah

LGTM

but could use another review, because I pushed the last changes

vvoland

LGTM, but a follow up with some integration tests for this wouldn't hurt 😅

thaJeztah · 2026-01-16T15:11:23Z

Issue / glitch with docker hub auth, or just another GitHub actions glitch?

time="2026-01-16T15:08:02Z" level=info msg="fetch failed after status: 404 Not Found" host="localhost:64203"
time="2026-01-16T15:08:32Z" level=info msg="fetch failed" error="failed to authorize: failed to fetch oauth token: unexpected status from POST request to https://auth.docker.io/token: 504 Gateway Timeout" host=registry-1.docker.io

vvoland · 2026-01-16T15:25:13Z

Looks like Hub

thaJeztah · 2026-01-16T15:31:04Z

Yup; I see there's an incident; not sure if they already updated the status page though.

thaJeztah · 2026-01-16T15:32:08Z

Ah! They did https://www.dockerstatus.com

thaJeztah · 2026-01-16T16:00:39Z

api/types/image/signer_identity.go


 	// Reference to specific build instructions that are responsible for signing.
-	BuildSignerURI string `json:"buildSignerURI,omitempty"` // 1.3.6.1.4.1.57264.1.9
+	BuildSignerURI string `json:"BuildSignerURI,omitempty"` // 1.3.6.1.4.1.57264.1.9


@tonistiigi can you squash these case changes with the first commit, and I think the second commit also needs to be updated as the Swagger may be using lowercase.

Or should we make all fields match the upstream (and lowercase)? Not sure if it's a standard / spec that we should match?

Should be ok now.

Or should we make all fields match the upstream (and lowercase)?

It looks out of place in Inspect output then as all other fields are uppercase.

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Enable inspect endpoint to verify image signatures and expose signature information for inspection. Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

thaJeztah

LGTM

github-actions bot added area/logging platform/windows area/docs area/images Image Distribution area/daemon Core Engine area/builder/buildkit Build containerd-integration Issues and PRs related to containerd integration module/api labels Dec 16, 2025

tonistiigi commented Dec 16, 2025

View reviewed changes

tonistiigi requested review from crazy-max and dmcgowan December 16, 2025 18:15

tonistiigi mentioned this pull request Dec 17, 2025

vendor: update buildkit to d1e5d1a8f771 (master / v0.27.0-dev) #51756

Merged

tonistiigi added this to the 29.3.0 milestone Dec 18, 2025

crazy-max reviewed Dec 19, 2025

View reviewed changes

tonistiigi force-pushed the add-image-identity branch from 1b38ba6 to 80981ff Compare December 20, 2025 00:53

tonistiigi force-pushed the add-image-identity branch from 80981ff to 50459c7 Compare January 12, 2026 17:39

tonistiigi marked this pull request as ready for review January 12, 2026 17:39

thaJeztah reviewed Jan 13, 2026

View reviewed changes

github-actions bot added the impact/changelog label Jan 13, 2026

tonistiigi added the impact/api label Jan 13, 2026

tonistiigi requested a review from thaJeztah January 13, 2026 17:58

tonistiigi added the kind/feature Functionality or other elements that the project doesn't currently have. Features are new and shiny label Jan 13, 2026

crazy-max reviewed Jan 14, 2026

View reviewed changes

api/types/image/image_inspect.go Outdated Show resolved Hide resolved

crazy-max reviewed Jan 14, 2026

View reviewed changes

daemon/containerd/image_inspect.go Show resolved Hide resolved

crazy-max reviewed Jan 14, 2026

View reviewed changes

go.mod Outdated Show resolved Hide resolved

tonistiigi force-pushed the add-image-identity branch from e2d0bcb to 30314fa Compare January 14, 2026 16:09

crazy-max approved these changes Jan 14, 2026

View reviewed changes

thompson-shaun modified the milestones: 29.3.0, 29.2.0 Jan 14, 2026

vvoland reviewed Jan 15, 2026

View reviewed changes

daemon/containerd/image_inspect.go Show resolved Hide resolved

thaJeztah force-pushed the add-image-identity branch 2 times, most recently from 9710305 to ecacf5f Compare January 16, 2026 12:40

thaJeztah reviewed Jan 16, 2026

View reviewed changes

thaJeztah force-pushed the add-image-identity branch from ba403e8 to 72ce3a5 Compare January 16, 2026 14:41

thaJeztah mentioned this pull request Jan 16, 2026

inspect: add API-version gate for image identity #51862

Merged

1 task

thaJeztah approved these changes Jan 16, 2026

View reviewed changes

vvoland removed area/logging area/docs area/daemon Core Engine platform/windows labels Jan 16, 2026

vvoland approved these changes Jan 16, 2026

View reviewed changes

tonistiigi force-pushed the add-image-identity branch from 72ce3a5 to dc56d93 Compare January 16, 2026 15:53

github-actions bot added area/docs area/daemon Core Engine labels Jan 16, 2026

thaJeztah reviewed Jan 16, 2026

View reviewed changes

tonistiigi added 5 commits January 16, 2026 08:04

api: add inspect identity base type to expose trusted image origin

1d4e04b

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

api: add swagger definitions for new Identity type

7745b71

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

inspect: add build identity support

3540989

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

inspect: add pull identity to track origin registry repo

0adfe6c

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

inspect: add signature identity support

8890f81

Enable inspect endpoint to verify image signatures and expose signature information for inspection. Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

tonistiigi force-pushed the add-image-identity branch from dc56d93 to 8890f81 Compare January 16, 2026 16:07

thaJeztah approved these changes Jan 16, 2026

View reviewed changes

thaJeztah merged commit 397c7d6 into moby:master Jan 16, 2026
240 of 242 checks passed

	// ImageInspectOpts holds parameters to inspect an image.
	type ImageInspectOpts struct {
	Manifests bool
	Platform *ocispec.Platform
	}

Conversation

tonistiigi commented Dec 16, 2025 • edited by vvoland Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Examples

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

crazy-max left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thaJeztah commented Jan 16, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Jan 16, 2026

Uh oh!

thaJeztah commented Jan 16, 2026

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

vvoland left a comment

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Jan 16, 2026

Uh oh!

vvoland commented Jan 16, 2026

Uh oh!

thaJeztah commented Jan 16, 2026

Uh oh!

thaJeztah commented Jan 16, 2026

Uh oh!

tonistiigi commented Dec 16, 2025 •

edited by vvoland

Loading