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.3 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

Audit Readiness

What It Checks

Verifies the system is ready for compliance audits by querying the Evidence Locker at /api/v1/evidence/audit-readiness. The check evaluates four readiness criteria:

Retention policy configured: whether a data retention policy is active.
Audit logging enabled: whether audit log capture is turned on.
Backup verified: whether the most recent backup has been validated.
Evidence retention age: whether the oldest evidence meets the required retention period (default 365 days).

Condition	Result
Evidence Locker unreachable	Warn
3 or more issues found	Fail
1-2 issues found	Warn
All criteria satisfied	Pass

Evidence collected: issues_count, retention_policy_configured, audit_log_enabled, backup_verified, evidence_count, oldest_evidence_days.

The check only runs when EvidenceLocker:Url or Services:EvidenceLocker:Url is configured. It uses a 15-second HTTP timeout.

Why It Matters

Compliance audits (SOC2, FedRAMP, HIPAA, PCI-DSS) require verifiable evidence retention, continuous audit logging, and validated backups. If any of these controls is missing, the organization cannot demonstrate compliance during an audit. A missing retention policy means evidence may be silently deleted. Disabled audit logging creates gaps in the chain of custody. Unverified backups risk data loss during incident recovery.

Common Causes

No retention policy configured (default is not set)
Audit logging disabled in configuration or by error
Backup verification job not running or failing silently
Evidence retention shorter than the required period (e.g., 90 days configured but 365 required)

How to Fix

Docker Compose

# Configure retention policy
docker compose exec evidence-locker stella evidence retention set --days 365

# Enable audit logging
docker compose exec platform stella audit enable

# Verify backup status
docker compose exec evidence-locker stella evidence backup verify

# Set environment variables if needed
# EvidenceLocker__Retention__Days=365
# AuditLog__Enabled=true

Bare Metal / systemd

# Configure retention policy
stella evidence retention set --days 365

# Enable audit logging
stella audit enable

# Verify backup status
stella evidence backup verify

# Edit appsettings.json
# "EvidenceLocker": { "Retention": { "Days": 365 } }
# "AuditLog": { "Enabled": true }

sudo systemctl restart stellaops-evidence-locker

Kubernetes / Helm

# values.yaml
evidenceLocker:
  retention:
    days: 365
  backup:
    enabled: true
    schedule: "0 2 * * *"
    verifyAfterBackup: true
auditLog:
  enabled: true

helm upgrade stellaops ./charts/stellaops -f values.yaml

Verification

stella doctor run --check check.compliance.audit-readiness

check.compliance.evidence-integrity — verifies evidence has not been tampered with
check.compliance.export-readiness — verifies evidence can be exported for auditors
check.compliance.evidence-rate — monitors evidence generation health
check.compliance.framework — verifies compliance framework controls are passing

3.3 KiB Raw Blame History