git.stella-ops.org/docs/modules/doctor/registry-checks.md

Registry Diagnostic Checks

Module: Doctor Plugin: IntegrationPlugin Sprint: SPRINT_0127_001_0002_oci_registry_compatibility

This document covers the OCI registry diagnostic checks available in Stella Doctor for validating registry connectivity, capabilities, and authorization.

Overview

StellaOps Doctor includes comprehensive registry diagnostics to verify that configured OCI registries are properly accessible and support the features required for secure software supply chain operations. These checks are part of the IntegrationPlugin and can be run individually or as a group using the registry tag.

Quick Start

# Run all registry checks
stella doctor --tag registry

# Run a specific check
stella doctor --check check.integration.oci.referrers

# Export results as JSON
stella doctor --tag registry --format json --output registry-health.json

# Run with verbose output
stella doctor --tag registry --verbose

Available Checks

check.integration.oci.credentials

Purpose: Validate registry credential configuration and authentication.

Property	Value
Name	OCI Registry Credentials
Default Severity	Fail
Tags	registry, oci, credentials, secrets, auth
Estimated Duration	5 seconds

What it checks:

1. Credential configuration (username/password, bearer token, or anonymous)
2. Authentication against the /v2/ endpoint
3. OAuth2 token exchange for registries requiring it
4. Credential validity and format

Evidence collected:

• registry_url - Target registry URL
• auth_method - Authentication method (basic, bearer, anonymous)
• username - Username (if configured)
• credentials_valid - Whether authentication succeeded
• auth_challenge - WWW-Authenticate header if present

Pass criteria:

• Credentials are properly configured
• Authentication succeeds against /v2/ endpoint

Fail scenarios:

• Missing required credentials (username without password)
• Invalid credentials (401 Unauthorized)
• Network or TLS errors

---

check.integration.oci.pull

Purpose: Verify pull authorization for the configured test repository.

Property	Value
Name	OCI Registry Pull Authorization
Default Severity	Fail
Tags	registry, oci, pull, authorization
Estimated Duration	5 seconds

What it checks:

1. HEAD request to manifest endpoint (non-destructive)
2. Authorization for pull operations
3. Image/tag existence

Evidence collected:

• registry_url - Target registry URL
• test_repository - Repository used for testing
• test_tag - Tag used for testing
• pull_authorized - Whether pull is authorized
• manifest_digest - Manifest digest if successful
• http_status - HTTP status code

Pass criteria:

• HEAD request to manifest returns 200 OK
• Manifest digest is returned

Fail scenarios:

• 401 Unauthorized: Invalid credentials
• 403 Forbidden: Valid credentials but no pull permission
• Info (not fail) for 404: Test image not found (can't verify)

---

check.integration.oci.push

Purpose: Verify push authorization for the configured test repository.

Property	Value
Name	OCI Registry Push Authorization
Default Severity	Fail
Tags	registry, oci, push, authorization
Estimated Duration	10 seconds

What it checks:

1. Initiates blob upload via POST (non-destructive)
2. Immediately cancels the upload session
3. Verifies push authorization

Evidence collected:

• registry_url - Target registry URL
• test_repository - Repository used for testing
• push_authorized - Whether push is authorized
• upload_session_cancelled - Whether cleanup succeeded
• http_status - HTTP status code
• credentials_valid - Whether credentials are valid (for 403)

Pass criteria:

• POST to blob uploads returns 202 Accepted
• Upload session is successfully cancelled

Fail scenarios:

• 401 Unauthorized: Invalid credentials
• 403 Forbidden: Valid credentials but no push permission

Non-destructive design: This check initiates a blob upload session but immediately cancels it via DELETE. No data is actually pushed to the registry.

---

check.integration.oci.referrers

Purpose: Verify OCI 1.1 referrers API support for artifact linking.

Property	Value
Name	OCI Registry Referrers API Support
Default Severity	Warn
Tags	registry, oci, referrers, oci-1.1
Estimated Duration	10 seconds

What it checks:

1. Resolves manifest digest for test image
2. Probes the referrers API endpoint
3. Determines if native API or fallback is required

Evidence collected:

• registry_url - Target registry URL
• referrers_supported - Whether referrers API is supported
• fallback_required - Whether tag-based fallback is needed
• oci_version - OCI-Distribution-API-Version header
• referrers_count - Number of referrers found (if any)

Pass criteria:

• Referrers endpoint returns 200 OK with OCI index
• Or returns 404 with OCI index content (empty referrers)

Warn scenarios (not Fail):

• 404 without OCI index: API not supported, fallback required
• 405 Method Not Allowed: API not implemented

The severity is Warn (not Fail) because StellaOps automatically uses tag-based fallback discovery when the referrers API is unavailable.

---

check.integration.oci.capabilities

Purpose: Comprehensive registry capability matrix detection.

Property	Value
Name	OCI Registry Capability Matrix
Default Severity	Info
Tags	registry, oci, capabilities, compatibility
Estimated Duration	30 seconds

What it checks:

1. OCI Distribution version (via headers)
2. Referrers API support
3. Chunked upload support
4. Cross-repository blob mounting
5. Manifest delete support
6. Blob delete support

Evidence collected:

• registry_url - Target registry URL
• distribution_version - OCI/Docker distribution version
• supports_referrers_api - true/false/unknown
• supports_chunked_upload - true/false/unknown
• supports_cross_repo_mount - true/false/unknown
• supports_manifest_delete - true/false/unknown
• supports_blob_delete - true/false/unknown
• capability_score - Summary (e.g., "5/6")

Severity logic:

• Pass: All capabilities supported
• Info: Some non-critical capabilities missing
• Warn: Referrers API not supported (critical for StellaOps)

---

Configuration

Registry checks use the following configuration keys:

OCI:
  RegistryUrl: "https://registry.example.com"
  Username: "service-account"
  Password: "secret"  # Or use PasswordSecretRef
  Token: "bearer-token"  # Alternative to username/password
  TestRepository: "stellaops/test"  # Default: library/alpine
  TestTag: "latest"  # Default: latest

Environment Variables

export OCI__RegistryUrl="https://registry.example.com"
export OCI__Username="service-account"
export OCI__Password="secret"
export OCI__TestRepository="stellaops/test"
export OCI__TestTag="latest"

Registry Compatibility Matrix

Registry	Version	Referrers API	Chunked Upload	Cross-Mount	Delete	Recommended
ACR	Any	Native	Yes	Yes	Yes	Yes
ECR	Any	Native	Yes	Yes	Yes	Yes
GCR/Artifact Registry	Any	Native	Yes	Yes	Yes	Yes
Harbor	2.6+	Native	Yes	Yes	Yes	Yes
Quay	3.12+	Native	Yes	Yes	Yes	Yes
JFrog Artifactory	7.x+	Native	Yes	Yes	Yes	Yes
GHCR	Any	Fallback	Yes	Yes	Yes	With fallback
Docker Hub	Any	Fallback	Yes	Limited	Limited	With fallback
registry:2	2.8+	Fallback	Yes	Yes	Yes	For testing
Zot	Any	Native	Yes	Yes	Yes	Yes
Distribution	Edge	Partial	Yes	Yes	Yes	Yes

Legend

• Native: Full OCI 1.1 referrers API support
• Fallback: Requires tag-based discovery (sha256-{digest}.* tags)
• Partial: Support varies by configuration

Known Issues & Workarounds

GHCR (GitHub Container Registry)

Issue: Referrers API not implemented (returns 404 without OCI index)

Impact: Slower artifact discovery, requires tag-based fallback

Workaround: StellaOps automatically detects this and uses fallback discovery. No action required.

Tracking: GitHub feature request pending

Docker Hub

Issue: Rate limiting can affect capability probes

Impact: Probes may timeout or return 429

Workaround:

• Use authenticated requests to increase rate limits
• Configure retry with exponential backoff
• Consider using a pull-through cache

Harbor < 2.6

Issue: Referrers API not available in older versions

Impact: Requires tag-based fallback

Workaround: Upgrade to Harbor 2.6+ for native referrers API support

ACR with CMK Encryption

Issue: Customer-managed key encrypted registries may use tag fallback

Impact: Slightly slower referrer discovery

Workaround: Automatic fallback detection handles this transparently

Reference: Azure Container Registry CMK Documentation

Interpreting Results

Healthy Registry Output

Registry Checks Summary
=======================

check.integration.oci.credentials    PASS  Credentials valid for registry.example.com
check.integration.oci.pull           PASS  Pull authorized (sha256:abc123...)
check.integration.oci.push           PASS  Push authorization verified
check.integration.oci.referrers      PASS  Referrers API supported (OCI 1.1)
check.integration.oci.capabilities   PASS  Full capability support (6/6)

Overall: 5 passed, 0 warnings, 0 failures

Registry with Fallback Required

Registry Checks Summary
=======================

check.integration.oci.credentials    PASS  Credentials valid for ghcr.io
check.integration.oci.pull           PASS  Pull authorized (sha256:def456...)
check.integration.oci.push           PASS  Push authorization verified
check.integration.oci.referrers      WARN  Referrers API not supported (using fallback)
check.integration.oci.capabilities   INFO  Partial capability support (4/6)

Overall: 3 passed, 1 warning, 1 info, 0 failures

Recommendations:
- Referrers API: StellaOps will use tag-based fallback automatically
- Consider upgrading to a registry with OCI 1.1 support for better performance

Remediation Steps

Invalid Credentials (401)

1. Verify username and password are correct
2. Check if credentials have expired
3. For OAuth2 registries, ensure token refresh is working
4. Test with docker CLI: docker login <registry>

No Permission (403)

1. Verify the service account has required permissions
2. For pull: Reader/Viewer role is typically sufficient
3. For push: Contributor/Writer role is required
4. Check repository-level permissions (some registries have repo-specific ACLs)

Referrers API Not Supported

1. Check registry version against compatibility matrix
2. Upgrade registry if possible (Harbor 2.6+, Quay 3.12+)
3. If upgrade not possible, StellaOps will use fallback automatically
4. Monitor for performance impact with large artifact counts

Network/TLS Errors

1. Verify network connectivity: curl -v https://<registry>/v2/
2. Check TLS certificate validity
3. For self-signed certs, configure trust or use --insecure (not recommended for production)
4. Check firewall rules and proxy configuration

Related Documentation

• Registry Compatibility Quick Reference
• Registry Referrer Troubleshooting
• Export Center Registry Compatibility
• Doctor Architecture