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.9 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

OCI Registry Push Authorization

What It Checks

Sends an authenticated HTTP POST to <registryUrl>/v2/<testRepo>/blobs/uploads/ to initiate a blob upload session. Uses the test repository from OCI:TestRepository or OCI:PushTestRepository (default stellaops/doctor-test). Only runs if credentials are configured. The check passes on 202 Accepted (the upload session is immediately cancelled by sending a DELETE to the returned Location header), fails on 401 (invalid credentials), fails on 403 (valid credentials but no push permission), and fails on connection errors or timeouts. No data is actually written to the registry.

Why It Matters

Push authorization is required for storing attestations, SBOMs, signatures, and promoted images in the registry. Without push access, Stella Ops cannot attach evidence artifacts to releases, sign images, or complete promotion workflows. This check verifies the actual push permission grant, not just credential validity, using a non-destructive probe that leaves no artifacts behind.

Common Causes

Credentials are valid but lack push (write) permissions
Repository does not exist and the registry does not support auto-creation
Service account has read-only access
Organization or team policy restricts push to specific accounts
Token has been revoked or expired
IP or network restrictions prevent write operations

How to Fix

Docker Compose

# Test push manually
echo "test" | docker push registry.example.com/stellaops/doctor-test:probe

# Grant push permissions to the service account in your registry UI

# Set a writable test repository
echo 'OCI__PushTestRepository=myorg/stellaops-test' >> .env
docker compose restart platform

Bare Metal / systemd

# Test push authorization with curl
curl -X POST \
  -u stellaops-svc:<password> \
  https://registry.example.com/v2/stellaops/doctor-test/blobs/uploads/

# Expected: 202 Accepted with Location header

# Fix permissions in registry
# Harbor: Add stellaops-svc as Developer/Admin to the project
# GitLab: Grant Reporter+ role to the service account
# ECR: Attach ecr:InitiateLayerUpload policy

sudo systemctl restart stellaops-platform

Kubernetes / Helm

# values.yaml
oci:
  registryUrl: https://registry.example.com
  pushTestRepository: myorg/stellaops-test
  existingSecret: stellaops-registry-creds

helm upgrade stellaops ./chart -f values.yaml

Verification

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

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

2.9 KiB Raw Blame History