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

2.8 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

OCI Registry Pull Authorization

What It Checks

Sends an authenticated HTTP HEAD request to <registryUrl>/v2/<testRepo>/manifests/<testTag> with OCI and Docker manifest accept headers. Uses the test repository from OCI:TestRepository (default library/alpine) and test tag from OCI:TestTag (default latest). The check passes on 2xx (records manifest digest and content type), returns info on 404 (test image not found -- cannot verify), fails on 401 (invalid credentials), fails on 403 (valid credentials but no pull permission), and fails on connection errors or timeouts.

Why It Matters

Pull authorization is the most fundamental registry operation. Stella Ops pulls images for scanning, SBOM extraction, attestation verification, and deployment. If pull authorization fails, the entire image-based workflow is blocked. This check tests actual pull permissions rather than just credential validity, catching permission misconfigurations that check.integration.oci.credentials cannot detect.

Common Causes

Credentials are invalid or expired
Token has been revoked
Anonymous pull is not allowed and no credentials are configured
Service account has been removed from the repository's access list
Repository access restricted by IP, network, or organization policy
Test image does not exist in the registry (404 -- configure OCI:TestRepository)

How to Fix

Docker Compose

# Test pull manually
docker pull registry.example.com/library/alpine:latest

# Check configured test repository
grep 'OCI__TESTREPOSITORY\|REGISTRY__TESTREPOSITORY' .env

# Set a valid test image that exists in your registry
echo 'OCI__TestRepository=myorg/base-image' >> .env
echo 'OCI__TestTag=latest' >> .env
docker compose restart platform

Bare Metal / systemd

# Test pull authorization with curl
curl -I -H "Accept: application/vnd.oci.image.manifest.v1+json" \
  -u stellaops-svc:<password> \
  https://registry.example.com/v2/library/alpine/manifests/latest

# Configure a test image that exists in your registry
sudo nano /etc/stellaops/appsettings.Production.json
# Set OCI:TestRepository and OCI:TestTag
sudo systemctl restart stellaops-platform

Kubernetes / Helm

# 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.pull

check.integration.oci.credentials -- validates credential configuration and token validity
check.integration.oci.push -- verifies push authorization
check.integration.oci.registry -- basic registry connectivity

2.8 KiB Raw Blame History