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>
This commit is contained in:
master
141
docs/doctor/articles/crypto/fips.md
Normal file
141
docs/doctor/articles/crypto/fips.md
Normal file
@@ -0,0 +1,141 @@
|
||||
---
|
||||
checkId: check.crypto.fips
|
||||
plugin: stellaops.doctor.crypto
|
||||
severity: fail
|
||||
tags: [crypto, fips, compliance, security]
|
||||
---
|
||||
# FIPS 140-2 Compliance
|
||||
|
||||
## What It Checks
|
||||
Verifies that FIPS 140-2 mode is enabled and that FIPS-compliant algorithms are functional. The check performs two phases:
|
||||
|
||||
**Phase 1 - FIPS mode detection:**
|
||||
- On Linux: reads `/proc/sys/crypto/fips_enabled` (expects "1").
|
||||
- On Windows: checks the registry at `HKLM\System\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy\Enabled` and the `DOTNET_SYSTEM_NET_SECURITY_USEFIPSVALIDATED` environment variable.
|
||||
- Reports the platform, crypto provider (OpenSSL/bcrypt/CoreCrypto), and whether the OpenSSL FIPS module is loaded.
|
||||
|
||||
**Phase 2 - Algorithm verification** (actual crypto operations, not just configuration):
|
||||
- **AES-256**: creates key, encrypts test data, verifies output.
|
||||
- **SHA-256**: hashes test data, verifies 32-byte output.
|
||||
- **SHA-384**: hashes test data, verifies 48-byte output.
|
||||
- **SHA-512**: hashes test data, verifies 64-byte output.
|
||||
- **RSA-2048**: generates key pair, signs and verifies test data.
|
||||
- **ECDSA-P256**: generates key pair, signs and verifies test data.
|
||||
|
||||
| Condition | Result |
|
||||
|---|---|
|
||||
| FIPS mode not enabled at OS level | Fail |
|
||||
| FIPS mode enabled but some algorithms fail testing | Warn |
|
||||
| FIPS mode enabled and all algorithms pass | Pass |
|
||||
|
||||
Evidence collected: `fips_mode_enabled`, `platform`, `crypto_provider`, `openssl_fips_module_loaded`, `crypto_profile`, `algorithms_tested`, `algorithms_available`, `algorithms_missing`, per-algorithm test results.
|
||||
|
||||
The check only runs when `Crypto:Profile` or `Cryptography:Profile` contains "fips", "fedramp", or equals "us-gov".
|
||||
|
||||
## Why It Matters
|
||||
FIPS 140-2 compliance is mandatory for US government deployments (FedRAMP, DoD, ITAR) and many regulated industries (finance, healthcare). Running without FIPS mode means cryptographic operations may use non-validated implementations, which violates federal security requirements. Even with FIPS mode enabled, individual algorithm failures indicate a broken crypto subsystem that could silently produce invalid signatures or weak encryption.
|
||||
|
||||
## Common Causes
|
||||
- FIPS mode not enabled in the operating system
|
||||
- OpenSSL FIPS provider not loaded or not installed
|
||||
- .NET runtime not configured for FIPS-validated algorithms
|
||||
- FIPS module version incompatible with the OpenSSL version
|
||||
- Algorithm test failure due to incomplete FIPS provider installation
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
# Check if FIPS mode is enabled in the container
|
||||
docker compose exec gateway cat /proc/sys/crypto/fips_enabled
|
||||
|
||||
# Enable FIPS mode in the host OS first (container inherits host FIPS)
|
||||
# Then restart the compose stack
|
||||
|
||||
# Set crypto profile
|
||||
# Crypto__Profile=fips
|
||||
|
||||
# Verify algorithms inside container
|
||||
docker compose exec gateway openssl list -providers
|
||||
docker compose exec gateway openssl list -digest-algorithms
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
|
||||
**Linux (RHEL/CentOS/Fedora):**
|
||||
```bash
|
||||
# Enable FIPS mode
|
||||
sudo fips-mode-setup --enable
|
||||
|
||||
# Verify FIPS status
|
||||
fips-mode-setup --check
|
||||
|
||||
# Reboot required after enabling
|
||||
sudo reboot
|
||||
|
||||
# After reboot, verify
|
||||
cat /proc/sys/crypto/fips_enabled # Should output "1"
|
||||
|
||||
# Restart StellaOps services
|
||||
sudo systemctl restart stellaops
|
||||
```
|
||||
|
||||
**Linux (Ubuntu/Debian):**
|
||||
```bash
|
||||
# Install FIPS packages
|
||||
sudo apt install ubuntu-fips
|
||||
sudo ua enable fips
|
||||
|
||||
# Reboot required
|
||||
sudo reboot
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```
|
||||
Enable via Local Security Policy:
|
||||
Security Settings > Local Policies > Security Options >
|
||||
"System cryptography: Use FIPS compliant algorithms" = Enabled
|
||||
|
||||
Or via registry (requires reboot):
|
||||
reg add HKLM\System\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy /v Enabled /t REG_DWORD /d 1 /f
|
||||
```
|
||||
|
||||
```bash
|
||||
# Configure StellaOps
|
||||
# "Crypto": { "Profile": "fips" }
|
||||
|
||||
sudo systemctl restart stellaops-platform
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
```yaml
|
||||
# values.yaml
|
||||
crypto:
|
||||
profile: fips
|
||||
|
||||
# FIPS must be enabled at the node level
|
||||
# For EKS: use Amazon Linux 2 FIPS AMI
|
||||
# For AKS: use FIPS-enabled node pools
|
||||
# For GKE: use Container-Optimized OS with FIPS
|
||||
```
|
||||
|
||||
```bash
|
||||
# Verify FIPS in pod
|
||||
kubectl exec deploy/stellaops-gateway -- cat /proc/sys/crypto/fips_enabled
|
||||
|
||||
# Check OpenSSL FIPS provider
|
||||
kubectl exec deploy/stellaops-gateway -- openssl list -providers
|
||||
|
||||
helm upgrade stellaops ./charts/stellaops -f values.yaml
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.crypto.fips
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.crypto.certchain` — certificates must use FIPS-approved algorithms
|
||||
- `check.crypto.eidas` — eIDAS has overlapping but distinct requirements from FIPS
|
||||
- `check.crypto.hsm` — FIPS 140-2 Level 3+ may require HSM for key storage
|
||||
- `check.compliance.attestation-signing` — signing must use FIPS-validated algorithms in FIPS deployments
|
||||
Reference in New Issue
Block a user