Files

master c58a236d70 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>

2026-03-27 12:28:00 +02:00

3.5 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

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

# 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

# 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

# values.yaml
evidenceLocker:
  export:
    pdfEnabled: true
    jsonEnabled: true
    signedBundleEnabled: true
    chainOfCustodyEnabled: true
    signingKeySecret: "stellaops-export-signing-key"

# 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

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

3.5 KiB Raw Blame History