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,111 @@
---
checkId: check.security.evidence.integrity
plugin: stellaops.doctor.security
severity: fail
tags: [security, evidence, integrity, dsse, rekor, offline]
---
# Evidence Integrity
## What It Checks
Validates DSSE signatures, Rekor inclusion proofs, and evidence hash consistency for files in the evidence locker. The check only runs when `EvidenceLocker:LocalPath` or `Evidence:BasePath` is configured and the directory exists.
The check scans up to **100 evidence files** (`.json` and `.dsse`) and performs structural verification on three evidence formats:
### DSSE Envelopes
- Payload must be valid base64.
- At least one signature must exist.
- Each signature must have `keyid` and `sig` fields, with `sig` being valid base64.
- If `payloadDigest` is present, verifies SHA-256 digest matches the payload bytes.
### Evidence Bundles
- Manifest must have a `version` field.
- If `rekorReceipt` is present, validates the Rekor receipt structure.
### Rekor Receipts
- Must have non-empty `uuid`.
- Must have numeric `logIndex`.
- Must have `inclusionProof` with a non-empty `hashes` array.
### Content Digest
- Must have algorithm prefix (`sha256:` or `sha512:`).
Files that don't match any known format are skipped. Files that fail to parse as JSON are marked invalid.
## Why It Matters
Evidence integrity is the foundation of Stella Ops' auditability guarantee. Every release decision, scan result, and policy evaluation is recorded as signed evidence. If evidence files are tampered with, the entire audit trail becomes untrustworthy. Broken DSSE signatures mean attestations may have been modified after signing. Missing or invalid Rekor inclusion proofs mean the transparency log cannot verify the evidence was recorded.
## Common Causes
- Evidence files may have been tampered with or corrupted
- DSSE signatures are invalid (payload was modified after signing)
- Evidence digests do not match content (partial writes, disk corruption)
- Rekor inclusion proofs are invalid or missing required fields
- Evidence locker directory does not exist or has not been initialized
## How to Fix
### Docker Compose
Verify the evidence locker path is configured and accessible:
```yaml
environment:
EvidenceLocker__LocalPath: "/data/evidence"
volumes:
- stellaops-evidence:/data/evidence
```
Investigate invalid files:
```bash
# List evidence files
docker compose exec platform ls -la /data/evidence/
# Check a specific file
docker compose exec platform cat /data/evidence/<file>.json | jq
```
Re-generate affected evidence:
```bash
# Re-scan and re-sign evidence bundles
docker compose exec platform stella evidence regenerate --path /data/evidence/<file>
```
### Bare Metal / systemd
```bash
# Create the evidence directory if missing
mkdir -p /var/lib/stellaops/evidence
chown stellaops:stellaops /var/lib/stellaops/evidence
# Verify file integrity
sha256sum /var/lib/stellaops/evidence/*.json
# Check Rekor entries
rekor-cli get --uuid <uuid-from-evidence>
```
### Kubernetes / Helm
Ensure evidence is stored on a persistent volume:
```yaml
evidenceLocker:
localPath: "/data/evidence"
persistentVolume:
enabled: true
size: "10Gi"
storageClass: "standard"
```
Verify inside the pod:
```bash
kubectl exec -it <pod> -- ls -la /data/evidence/
kubectl exec -it <pod> -- stella doctor run --check check.security.evidence.integrity
```
## Verification
```
stella doctor run --check check.security.evidence.integrity
```
## Related Checks
- `check.security.encryption` — validates encryption keys used for evidence signing
- `check.core.crypto.available` — SHA-256 must be available for digest verification
- `check.core.env.diskspace` — insufficient disk space can cause incomplete evidence writes