c58a236d70
Implement remediation-aware health checks across all Doctor plugin modules (Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment, EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release, Scanner, Storage, Vex) and their backing library counterparts (AI, Attestation, Authority, Core, Cryptography, Database, Docker, Integration, Notify, Observability, Security, ServiceGraph, Sources, Verification). Each check now emits structured remediation metadata (severity, category, runbook links, and fix suggestions) consumed by the Doctor dashboard remediation panel. Also adds: - docs/doctor/articles/ knowledge base for check explanations - Advisory AI search seed and allowlist updates for doctor content - Sprint plan for doctor checks documentation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3.4 KiB
checkId, plugin, severity, tags
| checkId | plugin | severity | tags | |||||
|---|---|---|---|---|---|---|---|---|
| check.integration.oci.referrers | stellaops.doctor.integration | warn |
|
OCI Registry Referrers API Support
What It Checks
First resolves the manifest digest for the test image (OCI:TestRepository:OCI:TestTag, defaults to library/alpine:latest) by sending a HEAD request to the manifests endpoint and reading the Docker-Content-Digest header. Then probes the referrers API at <registryUrl>/v2/<repo>/referrers/<digest> with the application/vnd.oci.image.index.v1+json accept header. The check passes on 200 OK or on 404 if the response body contains OCI index JSON (valid response meaning no referrers exist yet). It warns on 404 without OCI index (API not supported, tag-based fallback required) or 405 Method Not Allowed. Returns info if the test image is not found (cannot verify). Fails on connection errors.
Why It Matters
The OCI 1.1 referrers API enables artifact linking: attaching SBOMs, signatures, attestations, and VEX documents directly to container image manifests. Without it, Stella Ops must fall back to the tag-based referrer pattern (sha256-{digest}.{artifactType}), which is less efficient, harder to discover, and may conflict with registry tag naming policies. Knowing referrers API availability determines which linking strategy is used.
Common Causes
- Registry does not implement OCI Distribution Spec v1.1
- Registry version is too old (pre-referrers API)
- Referrers API disabled in registry configuration
- Test image does not exist in registry (cannot resolve digest to probe)
- Credentials lack pull permissions for the test image
How to Fix
Docker Compose
# Check registry version and referrers support
docker compose exec gateway curl -sv \
-H "Accept: application/vnd.oci.image.index.v1+json" \
https://registry.example.com/v2/library/alpine/referrers/sha256:abc...
# Upgrade registry to a version supporting OCI 1.1 referrers:
# - Harbor 2.6+
# - Quay 3.12+
# - ACR (default)
# - ECR (default)
# - GCR/Artifact Registry (default)
# - Distribution 2.8+
Bare Metal / systemd
# Verify registry version
curl -I https://registry.example.com/v2/ 2>&1 | grep -i distribution
# Test referrers API
DIGEST=$(curl -sI -H "Accept: application/vnd.oci.image.manifest.v1+json" \
https://registry.example.com/v2/library/alpine/manifests/latest \
| grep Docker-Content-Digest | awk '{print $2}' | tr -d '\r')
curl -H "Accept: application/vnd.oci.image.index.v1+json" \
https://registry.example.com/v2/library/alpine/referrers/$DIGEST
# Upgrade the registry package
sudo apt upgrade docker-registry # or equivalent
sudo systemctl restart docker-registry
Kubernetes / Helm
# Upgrade Harbor chart
helm upgrade harbor harbor/harbor --set registry.referrers.enabled=true
# Or configure Stella Ops with a test image that exists
# values.yaml
oci:
registryUrl: https://registry.example.com
testRepository: myorg/base-image
testTag: latest
helm upgrade stellaops ./chart -f values.yaml
Verification
stella doctor run --check check.integration.oci.referrers
Related Checks
check.integration.oci.capabilities-- broader capability matrix including referrerscheck.integration.oci.registry-- basic registry connectivitycheck.integration.oci.pull-- pull authorization (needed to resolve test image digest)