feat: include registry and repository in artifact ID calculation

[knqyf263]

Background

Trivy recently introduced an ArtifactID field to uniquely identify scan targets across different artifact types (#9662, #9663). For container images, the current implementation uses the Image ID (config blob hash) directly as the Artifact ID.

After team discussion, we identified that this approach is insufficient for our use cases. We need a more nuanced Artifact ID generation that considers the repository context while maintaining consistency across tags of the same image.

Problem Statement

The current implementation using only Image ID as Artifact ID does not meet our requirements for distinguishing between:

• Images from different repositories within the same registry
• Images from different registries
• Images with the same content but different repository contexts

This leads to incorrect deduplication and tracking of vulnerabilities across different deployment contexts.

Requirements

The new Artifact ID generation for container images must satisfy the following requirements:

1. Same Artifact ID Requirements

Images should have the same Artifact ID when:

• They share the same Image ID (config blob hash)
• They are from the same registry
• They are from the same repository
• They only differ in tags

Example:

ghcr.io/aquasecurity/trivy:latest
ghcr.io/aquasecurity/trivy:v0.65.0

These should have the same Artifact ID (assuming same Image ID).

2. Different Artifact ID Requirements

Images should have different Artifact IDs when they are from:

a. Different Repositories (Same Registry)

Example:

ghcr.io/aquasecurity/trivy:v0.65.0
ghcr.io/aqua-sec/trivy:v0.65.0

Even with the same Image ID, these should have different Artifact IDs.

b. Different Registries

Example:

ghcr.io/aquasecurity/trivy:v0.65.0
docker.io/aquasecurity/trivy:v0.65.0

Even with the same Image ID, these should have different Artifact IDs.

Proposed Solution

Artifact ID Calculation

The Artifact ID for container images should be calculated as:

ArtifactID = hash(ImageID + Registry + Repository)

Where:

• ImageID: The existing image configuration blob hash (sha256:...)
• Registry: The registry hostname (e.g., ghcr.io, docker.io)
• Repository: The repository path without the tag (e.g., aquasecurity/trivy)

Implementation Details

1. Parsing Image References

The implementation must correctly parse image references to extract:

• Registry hostname
• Repository path
• Tag/digest (to be excluded from calculation)

// Example parsing
// Input: ghcr.io/aquasecurity/trivy:v0.65.0
// Parsed:
//   Registry: ghcr.io
//   Repository: aquasecurity/trivy
//   Tag: v0.65.0 (excluded from Artifact ID)

2. Hash Function

• Use SHA256 for consistency with existing Image ID format
• Combine components in a deterministic order
• Format: sha256:<hash>

func GenerateArtifactID(imageID, registry, repository string) string {
    input := fmt.Sprintf("%s:%s:%s", imageID, registry, repository)
    hash := sha256.Sum256([]byte(input))
    return fmt.Sprintf("sha256:%x", hash)
}

3. Edge Cases Handling

• Default Registry: Images without explicit registry should default to docker.io
• Port Handling: Registry URLs with ports should be normalized (e.g., localhost:5000)
• Multi-level Repositories: Handle paths like registry/org/team/image correctly
• Digest References: Images referenced by digest should still use the repository path

Examples

Given two images with the same Image ID sha256:abc123...:

Example 1: Same Repository, Different Tags → Same Artifact ID

Input 1: ghcr.io/aquasecurity/trivy:latest
Input 2: ghcr.io/aquasecurity/trivy:v0.65.0

Components:
  ImageID: sha256:abc123...
  Registry: ghcr.io
  Repository: aquasecurity/trivy

Result: sha256:def456... (same for both)

Example 2: Different Repositories → Different Artifact IDs

Input 1: ghcr.io/aquasecurity/trivy:v0.65.0
  Components: ImageID=sha256:abc123..., Registry=ghcr.io, Repository=aquasecurity/trivy
  Result: sha256:def456...

Input 2: ghcr.io/aqua-sec/trivy:v0.65.0
  Components: ImageID=sha256:abc123..., Registry=ghcr.io, Repository=aqua-sec/trivy
  Result: sha256:ghi789... (different)

Example 3: Different Registries → Different Artifact IDs

Input 1: ghcr.io/aquasecurity/trivy:v0.65.0
  Components: ImageID=sha256:abc123..., Registry=ghcr.io, Repository=aquasecurity/trivy
  Result: sha256:def456...

Input 2: docker.io/aquasecurity/trivy:v0.65.0
  Components: ImageID=sha256:abc123..., Registry=docker.io, Repository=aquasecurity/trivy
  Result: sha256:jkl012... (different)

[itaysk]

Default Registry: Images without explicit registry should default to docker.io

can we differentiate between docker.io and local images? for example if I docker build -t test vs docker pull test.

[knqyf263]

can we differentiate between docker.io and local images? for example if I docker build -t test vs docker pull test.

Do you have any ideas to recognize the difference? AFAIK, a remote image pulled from Docker Hub also shows repo tags without index.docker.io.

Remote images

$ docker pull alpine:3.20
$ docker inspect alpine:3.20 | jq '.[].RepoTags[]'
"alpine:3.20"
$ docker inspect alpine:3.20 | jq '.[].RepoDigests[]'
"alpine@sha256:765942a4039992336de8dd5db680586e1a206607dd06170ff0a37267a9e01958"

Local images

$ docker build -t test .
$ docker inspect test | jq '.[].RepoTags[]'
"test:latest"
$ docker inspect test | jq '.[].RepoDigests[]'
"test@sha256:1c0bfefcb3e1f4a0369086ace6d136041aebd5925f3dba370039b05b08792c7d"

[itaysk]

yeah I didn't find any way to determine this. looks like this is guessed by client libraries https://github.com/containers/image/blob/df7e80d2d19872b61f352a8a182ec934dc0c2346/docker/reference/normalize.go#L90

[knqyf263]

When I built it without using containerd-snapshotter, the local image had an empty RepoDigests field. This means it might be possible to determine the condition using this value. However, when the containerd snapshotter is used, RepoDigests are generated, so this method cannot distinguish between them.

containerd-snapshotter: false

$ docker build -t test .
$ docker inspect test | jq '.[].RepoTags[]'
"test:latest"
 $ docker inspect test | jq '.[].RepoDigests[]'
[]

containerd-snapshotter: true

$ docker build -t test .
$ docker inspect test | jq '.[].RepoTags[]'
"test:latest"
$ docker inspect test | jq '.[].RepoDigests[]'
"test@sha256:1c0bfefcb3e1f4a0369086ace6d136041aebd5925f3dba370039b05b08792c7d"

[knqyf263]

I'm not sure it's a reliable way to determine if Docker images were built locally or pulled from a remote registry, but we may be able to use the Parent field.

Test Results

With containerd-snapshotter: true (enabled)

• Local build: Parent field populated, RepoDigests populated
• Remote pull: Parent field empty, RepoDigests populated

With containerd-snapshotter: false (disabled)

• Local build: Parent field populated, RepoDigests empty
• Remote pull: Parent field empty, RepoDigests populated

Key Finding: The Parent field works consistently regardless of containerd-snapshotter setting.

Important Note: FROM scratch Images

The Parent field represents the previous build layer, not the base image:

• FROM scratch with multiple layers: Parent field is populated (correctly detected as LOCAL)
• FROM scratch with single layer: Parent field is empty (incorrectly detected as REMOTE)

Example verified:

FROM scratch
ADD file1.txt /layer1.txt
ADD file2.txt /layer2.txt
ADD file3.txt /layer3.txt

→ Final image has Parent pointing to the previous layer

Test Commands Used

# Build local test image
docker build -t local-test:latest .

# Pull remote image
docker pull nginx:alpine

# Compare Parent fields
docker inspect local-test:latest nginx:alpine | jq -r '.[] | "\(.RepoTags[0]) | Parent: \(.Parent)"'
local-test:latest | Parent: sha256:7aab056cecc6dbca58f1bb83771b82d17aff9028629746dbb25c39f0b8938cce
nginx:alpine | Parent: 

# Test FROM scratch with multiple layers
cat > Dockerfile << 'DOCKERFILE'
FROM scratch
ADD test.txt /layer1.txt
ADD test.txt /layer2.txt
ADD test.txt /layer3.txt
DOCKERFILE
docker build -t scratch-multilayer:latest .
docker inspect scratch-multilayer:latest | jq -r '.[0] | {Id, Parent}'

Conclusion

✅ Works with both containerd-snapshotter enabled/disabled
✅ Correctly identifies most local builds
✅ Correctly identifies all remote pulls

⚠️ Limitation: Single-layer FROM scratch images are misidentified as REMOTE (rare edge case)

Reference

• Related discussion: https://stackoverflow.com/questions/45821389/is-docker-inspect-f-parent-a-safe-way-to-get-the-base-image-id

[knqyf263]

It's explicitly explained in the comment.

Depending on how the image was created, this field may be empty and is only set for images that were built/created locally. This field is empty if the image was pulled from an image registry.

https://github.com/moby/moby/blob/2f09e6d6d8436d9a7a8d2750c4c640e863bce921/daemon/internal/image/image.go#L35-L40

However, it's deprecated and kept for compatibility.

field is deprecated with the legacy builder, but still included in response when present (built with legacy builder).

https://github.com/moby/moby/blob/2f09e6d6d8436d9a7a8d2750c4c640e863bce921/daemon/images/image_inspect.go#L83

@itaysk Do you want to rely on Parent? It may be going to be removed in the future.

[itaysk]

When I built it without using containerd-snapshotter, the local image had an empty RepoDigests field. This means it might be possible to determine the condition using this value. However, when the containerd snapshotter is used, RepoDigests are generated, so this method cannot distinguish between them.

from this I understand that there's one certein state - if we see empty RepoTags, we can indicate it's local with confidence. The problem is that indicating local is the same as the default state (no indication) so we need to create a 3rd state, something like a local:// prefix to only these cases. It won't cover all cases but maybe better than nothing in other words no false positives at the cost of false negatives. This is just my raw thoughts I'm not sure this would be good UX yet just wanted to clearly explain the suggested approach.

we may be able to use the Parent field

nice find!

Single-layer FROM scratch images are misidentified as REMOTE (rare edge case)

agree sounds like almost impossible edge case.

However, it's deprecated and kept for compatibility

we need to better understand this, if it means compatibility of consumer (docker daemon/inspec command) then I think it's fine, but if it's compatibility of the builder (meaning buildkit doesn't populate it while docker build does) then it's more of a problem.