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:
@@ -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
|
||||
Reference in New Issue
Block a user