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