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

4.1 KiB

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

Evidence Integrity

What It Checks

Detects evidence tampering or integrity issues by querying the Evidence Locker at /api/v1/evidence/integrity-check. The check verifies cryptographic signatures and hash chains across all stored evidence records. It evaluates:

Tampered records: evidence records where the signature or hash does not match the stored content.
Verification errors: records that could not be verified (e.g., missing certificates, unsupported algorithms).
Hash chain validity: whether the sequential hash chain linking evidence records is intact.

Condition	Result
Evidence Locker unreachable	Warn
Any tampered records detected (tamperedCount > 0)	Fail (CRITICAL)
Verification errors but no tampering	Warn
All records verified, no tampering	Pass

Evidence collected: tampered_count, verified_count, total_checked, first_tampered_id, verification_errors, hash_chain_valid.

The check only runs when EvidenceLocker:Url or Services:EvidenceLocker:Url is configured. It uses a 60-second HTTP timeout due to the intensive nature of the integrity scan.

Why It Matters

Evidence integrity is the cornerstone of compliance and audit trust. Tampered evidence records indicate either storage corruption, a security breach, or malicious modification of release decisions. Any tampering invalidates the entire evidence chain and must be treated as a security incident. Verification errors, while less severe, mean some evidence cannot be independently validated, weakening the audit posture.

Common Causes

Evidence modification after signing (accidental or malicious)
Storage corruption (disk errors, incomplete writes)
Malicious tampering by an attacker with storage access
Key or certificate mismatch after key rotation
Missing signing certificates needed for verification
Certificate expiration rendering signatures unverifiable
Unsupported signature algorithm in older evidence records

How to Fix

Docker Compose

# List tampered evidence (DO NOT DELETE - preserve for investigation)
docker compose exec evidence-locker stella evidence audit --tampered

# Check for storage corruption
docker compose exec evidence-locker stella evidence integrity-check --verbose

# If tampering is confirmed, escalate to security team
# Preserve all logs and evidence for forensic analysis
docker compose logs evidence-locker > evidence-locker-forensic.log

# For verification errors (missing certs), import the required certificates
docker compose exec evidence-locker stella evidence certs import --path /certs/

Bare Metal / systemd

# List tampered evidence
stella evidence audit --tampered

# Full integrity check with details
stella evidence integrity-check --verbose

# Check for disk errors
sudo smartctl -H /dev/sda
sudo fsck -n /dev/sda1

# Import missing certificates for verification
stella evidence certs import --path /etc/stellaops/certs/

# DO NOT delete tampered evidence - preserve for investigation

Kubernetes / Helm

# List tampered evidence
kubectl exec deploy/stellaops-evidence-locker -- stella evidence audit --tampered

# Full integrity check
kubectl exec deploy/stellaops-evidence-locker -- stella evidence integrity-check --verbose

# Check persistent volume health
kubectl describe pvc stellaops-evidence-data

# Export forensic logs
kubectl logs deploy/stellaops-evidence-locker --all-containers > forensic.log

Verification

stella doctor run --check check.compliance.evidence-integrity

check.compliance.attestation-signing — signing key health affects evidence signature creation
check.compliance.evidence-rate — evidence generation failures may relate to integrity issues
check.evidencelocker.merkle — Merkle anchor verification provides additional integrity guarantees
check.evidencelocker.provenance — provenance chain integrity validates the evidence chain
check.compliance.audit-readiness — overall audit readiness depends on evidence integrity

4.1 KiB Raw Blame History