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,104 @@
---
checkId: check.compliance.export-readiness
plugin: stellaops.doctor.compliance
severity: warn
tags: [compliance, export, audit]
---
# Evidence Export Readiness
## What It Checks
Verifies that evidence can be exported in auditor-ready formats by querying the Evidence Locker at `/api/v1/evidence/export/capabilities`. The check evaluates four export capabilities:
- **PDF export**: ability to generate PDF evidence reports.
- **JSON export**: ability to export evidence as structured JSON.
- **Signed bundle export**: ability to create cryptographically signed evidence bundles.
- **Chain of custody report**: ability to generate chain-of-custody documentation.
| Condition | Result |
|---|---|
| Evidence Locker unreachable | Warn |
| 2 or more export formats unavailable | Fail |
| 1 export format unavailable | Warn |
| All 4 export formats available | Pass |
Evidence collected: `pdf_export`, `json_export`, `signed_bundle`, `chain_of_custody`, `available_formats`.
The check only runs when `EvidenceLocker:Url` or `Services:EvidenceLocker:Url` is configured. It uses a 10-second HTTP timeout.
## Why It Matters
Auditors require evidence in specific formats. PDF reports are the most common delivery format for compliance reviews. Signed bundles provide cryptographic proof of evidence authenticity. The chain of custody report demonstrates that evidence has not been modified since collection. If these export capabilities are not available when an auditor requests them, it delays the audit process and may raise concerns about evidence integrity.
## Common Causes
- Export dependencies not installed (e.g., PDF rendering libraries)
- Signing keys not configured for evidence bundle signing
- Template files missing for PDF report generation
- Evidence Locker deployed without export module enabled
## How to Fix
### Docker Compose
```bash
# Check export configuration
docker compose exec evidence-locker stella evidence export --check
# Verify export dependencies are installed
docker compose exec evidence-locker dpkg -l | grep -i wkhtmltopdf
# Enable export features in environment
# EvidenceLocker__Export__PdfEnabled=true
# EvidenceLocker__Export__SignedBundleEnabled=true
# EvidenceLocker__Export__ChainOfCustodyEnabled=true
# Restart after configuration changes
docker compose restart evidence-locker
```
### Bare Metal / systemd
```bash
# Check export configuration
stella evidence export --check
# Install PDF rendering dependencies if missing
sudo apt install wkhtmltopdf
# Configure export in appsettings.json
# "EvidenceLocker": {
# "Export": {
# "PdfEnabled": true,
# "SignedBundleEnabled": true,
# "ChainOfCustodyEnabled": true
# }
# }
sudo systemctl restart stellaops-evidence-locker
```
### Kubernetes / Helm
```yaml
# values.yaml
evidenceLocker:
export:
pdfEnabled: true
jsonEnabled: true
signedBundleEnabled: true
chainOfCustodyEnabled: true
signingKeySecret: "stellaops-export-signing-key"
```
```bash
# Create signing key secret for bundles
kubectl create secret generic stellaops-export-signing-key \
--from-file=key.pem=./export-signing-key.pem
helm upgrade stellaops ./charts/stellaops -f values.yaml
```
## Verification
```
stella doctor run --check check.compliance.export-readiness
```
## Related Checks
- `check.compliance.audit-readiness` — overall audit readiness including retention and logging
- `check.compliance.attestation-signing` — signing key health required for signed bundle export
- `check.compliance.evidence-integrity` — integrity of the evidence being exported