checkId: check.verification.artifact.pull plugin: stellaops.doctor.verification severity: fail tags: [verification, artifact, registry, supply-chain]

Test Artifact Pull

This Stella Ops Doctor check confirms that the verification plugin can actually fetch the artifact it is meant to validate — the very first link in the release-verification chain. It is aimed at platform operators wiring up Doctor in both connected and air-gapped deployments: every downstream signature, SBOM, VEX, and policy check is meaningless if Doctor cannot retrieve the artifact in the first place.

What It Checks

Requires the verification plugin to be enabled and a test artifact to be configured with either Doctor:Plugins:Verification:TestArtifact:Reference or Doctor:Plugins:Verification:TestArtifact:OfflineBundlePath.

• Offline mode — confirms the offline bundle file exists.
• Online mode — performs a registry HEAD request against the OCI manifest and optionally compares the returned digest to the expected digest.

Why It Matters

The rest of the verification pipeline is meaningless if Doctor cannot retrieve the artifact it is supposed to validate. Pinning the reference by immutable digest (rather than a mutable tag) keeps this check deterministic and aligns with the suite’s supply-chain integrity posture.

Common Causes

• No test artifact reference or offline bundle path is configured
• Registry credentials are missing or do not allow manifest access
• The artifact digest or tag points to content that no longer exists

How to Fix

Docker Compose

services:
  doctor-web:
    environment:
      Doctor__Plugins__Verification__Enabled: "true"
      Doctor__Plugins__Verification__TestArtifact__Reference: ghcr.io/example/app@sha256:<digest>

For air-gapped mode:

Doctor__Plugins__Verification__TestArtifact__OfflineBundlePath: /var/lib/stella/verification/offline-bundle.json

docker compose -f devops/compose/docker-compose.stella-ops.yml exec doctor-web crane manifest ghcr.io/example/app@sha256:<digest>

Bare Metal / systemd

Use an immutable digest reference instead of a mutable tag whenever possible.

Kubernetes / Helm

Mount registry credentials and the offline bundle path into the Doctor workload if the cluster is disconnected.

Verification

stella doctor run --check check.verification.artifact.pull

Related Checks

• Signature Verification (check.verification.signature) — signature validation depends on the same artifact input
• Registry Pull Authorization (check.integration.oci.pull) — registry authorization issues often surface there too