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:
76
docs/doctor/articles/integration/registry-credentials.md
Normal file
76
docs/doctor/articles/integration/registry-credentials.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
checkId: check.integration.oci.credentials
|
||||
plugin: stellaops.doctor.integration
|
||||
severity: fail
|
||||
tags: [registry, oci, credentials, secrets, auth]
|
||||
---
|
||||
# OCI Registry Credentials
|
||||
|
||||
## What It Checks
|
||||
Determines the authentication method from configuration: bearer token (`OCI:Token` / `Registry:Token`), basic auth (`OCI:Username` + `OCI:Password` / `Registry:Username` + `Registry:Password`), or anonymous. Immediately **fails** if a username is provided without a password. Then validates credentials by sending an authenticated HTTP GET to `<registryUrl>/v2/`. The check **passes** on 200 OK, or on 401 if the response includes a `WWW-Authenticate: Bearer` challenge and basic credentials are configured (OAuth2 token exchange scenario). It **fails** on 401 (invalid credentials) or 403 (forbidden), and **fails** on connection errors or timeouts.
|
||||
|
||||
## Why It Matters
|
||||
Invalid or expired registry credentials cause image pull/push failures across all deployment pipelines. Because credentials are often rotated on a schedule, this check provides early detection of expired tokens before they silently break promotions, SBOM ingestion, or attestation storage. A username-without-password misconfiguration indicates a secret reference that failed to resolve.
|
||||
|
||||
## Common Causes
|
||||
- Credentials are invalid or have been rotated without updating the configuration
|
||||
- Token has been revoked by the registry administrator
|
||||
- Username provided without a corresponding password (broken secret reference)
|
||||
- Service account token expired
|
||||
- IP address or network not in the registry's allowlist
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
# Check credential configuration
|
||||
grep 'OCI__USERNAME\|OCI__PASSWORD\|OCI__TOKEN\|REGISTRY__' .env
|
||||
|
||||
# Test credentials manually
|
||||
docker login registry.example.com
|
||||
|
||||
# Rotate credentials
|
||||
echo 'OCI__Username=stellaops-svc' >> .env
|
||||
echo 'OCI__Password=<new-password>' >> .env
|
||||
docker compose restart platform
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
```bash
|
||||
# Check credential configuration
|
||||
cat /etc/stellaops/appsettings.Production.json | jq '.OCI | {Username, Password: (if .Password then "****" else null end), Token: (if .Token then "****" else null end)}'
|
||||
|
||||
# Test with curl
|
||||
curl -u stellaops-svc:<password> https://registry.example.com/v2/
|
||||
|
||||
# Update credentials
|
||||
sudo nano /etc/stellaops/appsettings.Production.json
|
||||
sudo systemctl restart stellaops-platform
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
```yaml
|
||||
# values.yaml
|
||||
oci:
|
||||
registryUrl: https://registry.example.com
|
||||
existingSecret: stellaops-registry-creds # Secret with username/password keys
|
||||
```
|
||||
```bash
|
||||
# Create or update the secret
|
||||
kubectl create secret generic stellaops-registry-creds \
|
||||
--from-literal=username=stellaops-svc \
|
||||
--from-literal=password=<new-password> \
|
||||
--dry-run=client -o yaml | kubectl apply -f -
|
||||
|
||||
helm upgrade stellaops ./chart -f values.yaml
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.integration.oci.credentials
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.integration.oci.registry` -- basic connectivity (does not test auth)
|
||||
- `check.integration.oci.pull` -- verifies pull authorization with these credentials
|
||||
- `check.integration.oci.push` -- verifies push authorization with these credentials
|
||||
Reference in New Issue
Block a user