---
checkId: check.compliance.framework
plugin: stellaops.doctor.compliance
severity: warn
tags: [compliance, framework, soc2, fedramp]
---
# 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
```bash
# 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
```bash
# 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
```yaml
# values.yaml
compliance:
  frameworks: "soc2,hipaa"
  autoRemediate: false
  reportSchedule: "0 6 * * 1"  # Weekly Monday 6am
```

```bash
# 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
```

## Related Checks
- `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