Files

master c58a236d70 Doctor plugin checks: implement health check classes and documentation

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>

2026-03-27 12:28:00 +02:00

3.1 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

OCI Registry Credentials

What It Checks

Determines the authentication method from configuration: bearer token (OCI:Token / Registry:Token), basic auth (OCI:Username + OCI:Password / Registry:Username + Registry:Password), or anonymous. Immediately fails if a username is provided without a password. Then validates credentials by sending an authenticated HTTP GET to <registryUrl>/v2/. The check passes on 200 OK, or on 401 if the response includes a WWW-Authenticate: Bearer challenge and basic credentials are configured (OAuth2 token exchange scenario). It fails on 401 (invalid credentials) or 403 (forbidden), and fails on connection errors or timeouts.

Why It Matters

Invalid or expired registry credentials cause image pull/push failures across all deployment pipelines. Because credentials are often rotated on a schedule, this check provides early detection of expired tokens before they silently break promotions, SBOM ingestion, or attestation storage. A username-without-password misconfiguration indicates a secret reference that failed to resolve.

Common Causes

Credentials are invalid or have been rotated without updating the configuration
Token has been revoked by the registry administrator
Username provided without a corresponding password (broken secret reference)
Service account token expired
IP address or network not in the registry's allowlist

How to Fix

Docker Compose

# Check credential configuration
grep 'OCI__USERNAME\|OCI__PASSWORD\|OCI__TOKEN\|REGISTRY__' .env

# Test credentials manually
docker login registry.example.com

# Rotate credentials
echo 'OCI__Username=stellaops-svc' >> .env
echo 'OCI__Password=<new-password>' >> .env
docker compose restart platform

Bare Metal / systemd

# Check credential configuration
cat /etc/stellaops/appsettings.Production.json | jq '.OCI | {Username, Password: (if .Password then "****" else null end), Token: (if .Token then "****" else null end)}'

# Test with curl
curl -u stellaops-svc:<password> https://registry.example.com/v2/

# Update credentials
sudo nano /etc/stellaops/appsettings.Production.json
sudo systemctl restart stellaops-platform

Kubernetes / Helm

# values.yaml
oci:
  registryUrl: https://registry.example.com
  existingSecret: stellaops-registry-creds   # Secret with username/password keys

# Create or update the secret
kubectl create secret generic stellaops-registry-creds \
  --from-literal=username=stellaops-svc \
  --from-literal=password=<new-password> \
  --dry-run=client -o yaml | kubectl apply -f -

helm upgrade stellaops ./chart -f values.yaml

Verification

stella doctor run --check check.integration.oci.credentials

check.integration.oci.registry -- basic connectivity (does not test auth)
check.integration.oci.pull -- verifies pull authorization with these credentials
check.integration.oci.push -- verifies push authorization with these credentials

3.1 KiB Raw Blame History