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>
This commit is contained in:
master
2026-03-27 12:28:00 +02:00
parent fbd24e71de
commit c58a236d70
326 changed files with 18500 additions and 463 deletions

View File

@@ -0,0 +1,74 @@
---
checkId: check.integration.oci.push
plugin: stellaops.doctor.integration
severity: fail
tags: [registry, oci, push, authorization, credentials]
---
# 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
```bash
# 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
```bash
# 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
```yaml
# values.yaml
oci:
registryUrl: https://registry.example.com
pushTestRepository: myorg/stellaops-test
existingSecret: stellaops-registry-creds
```
```bash
helm upgrade stellaops ./chart -f values.yaml
```
## Verification
```
stella doctor run --check check.integration.oci.push
```
## Related Checks
- `check.integration.oci.credentials` -- validates credential configuration and token validity
- `check.integration.oci.pull` -- verifies pull authorization
- `check.integration.oci.registry` -- basic registry connectivity