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