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

Raw Blame History

checkId, plugin, severity, tags

checkId

plugin

severity

Compliance Framework

What It Checks

Verifies that configured compliance framework requirements are met by querying the Policy service at /api/v1/compliance/status. The check supports SOC2, FedRAMP, HIPAA, PCI-DSS, and custom frameworks. It evaluates:

Failing controls: any compliance controls in a failed state trigger a fail result.
Compliance score: a score below 100% (but with zero failing controls) triggers a warning.
Control counts: reports total, passing, and failing control counts along with the framework name.

Condition	Result
Policy service unreachable	Warn
Any controls failing (failingControls > 0)	Fail
Compliance score < 100%	Warn
All controls passing, score = 100%	Pass

The check only runs when Compliance:Frameworks is configured. It uses a 15-second HTTP timeout.

Why It Matters

Compliance frameworks define the security and operational controls your organization must satisfy. Failing controls mean the system is not meeting regulatory requirements, which can result in audit findings, failed certifications, or legal exposure. Even partial non-compliance (score below 100%) indicates controls that need attention before the next audit cycle.

Common Causes

Control requirements not implemented in the platform configuration
Evidence gaps where expected artifacts are missing
Policy violations detected by the policy engine
Configuration drift from the established compliance baseline
New controls added to the framework that have not been addressed

How to Fix

Docker Compose

# List all failing controls
docker compose exec policy stella compliance audit --failing

# Generate remediation plan
docker compose exec policy stella compliance remediate --plan

# Review compliance status in detail
docker compose exec policy stella compliance status --framework soc2

# Configure frameworks in your .env
# Compliance__Frameworks=soc2,hipaa

Bare Metal / systemd

# List failing controls
stella compliance audit --failing

# Generate remediation plan
stella compliance remediate --plan

# Configure frameworks in appsettings.json
# "Compliance": { "Frameworks": "soc2,hipaa" }

sudo systemctl restart stellaops-policy

Kubernetes / Helm

# values.yaml
compliance:
  frameworks: "soc2,hipaa"
  autoRemediate: false
  reportSchedule: "0 6 * * 1"  # Weekly Monday 6am

# Apply and check
helm upgrade stellaops ./charts/stellaops -f values.yaml
kubectl exec deploy/stellaops-policy -- stella compliance audit --failing

Verification

stella doctor run --check check.compliance.framework

check.compliance.audit-readiness — verifies the system is ready for compliance audits
check.compliance.evidence-integrity — verifies evidence integrity for compliance evidence
check.compliance.provenance-completeness — verifies provenance records support compliance claims
check.compliance.export-readiness — verifies evidence can be exported for auditor review

3.1 KiB Raw Blame History