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:
94
docs/doctor/articles/security/encryption.md
Normal file
94
docs/doctor/articles/security/encryption.md
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
checkId: check.security.encryption
|
||||
plugin: stellaops.doctor.security
|
||||
severity: warn
|
||||
tags: [security, encryption, cryptography]
|
||||
---
|
||||
# Encryption Keys
|
||||
|
||||
## What It Checks
|
||||
Validates encryption key configuration and algorithms. The check only runs when an encryption configuration section exists (`Encryption`, `DataProtection`, or `Cryptography`). It inspects:
|
||||
|
||||
| Setting | Threshold/Condition | Severity |
|
||||
|---|---|---|
|
||||
| `Algorithm` | Contains DES, 3DES, RC4, MD5, or SHA1 | `fail` — weak algorithm |
|
||||
| `KeySize` | Less than 128 bits | `fail` — key too small |
|
||||
| `KeyRotationDays` | Greater than 365 | `warn` — infrequent rotation |
|
||||
| `DataProtection:KeysPath` | Directory does not exist | `warn` — keys path missing |
|
||||
|
||||
Defaults if not explicitly configured: algorithm is `AES-256`.
|
||||
|
||||
Evidence collected includes: configured algorithm, key size, key rotation period, and data protection keys path.
|
||||
|
||||
## Why It Matters
|
||||
Encryption protects data at rest and data protection keys used by ASP.NET Core for cookie encryption, anti-forgery tokens, and TempData. Weak algorithms (DES, 3DES, RC4) have known vulnerabilities and can be broken with modern hardware. Small key sizes reduce the keyspace, making brute-force attacks feasible. Without key rotation, a compromised key provides indefinite access to all encrypted data.
|
||||
|
||||
## Common Causes
|
||||
- Weak encryption algorithm configured (DES, 3DES, RC4, MD5, SHA1)
|
||||
- Encryption key size too small (less than 128 bits)
|
||||
- Key rotation period greater than 365 days or not configured
|
||||
- Data protection keys directory does not exist on disk
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
Set encryption configuration:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
Encryption__Algorithm: "AES-256"
|
||||
Encryption__KeySize: "256"
|
||||
Encryption__KeyRotationDays: "90"
|
||||
DataProtection__KeysPath: "/app/keys"
|
||||
|
||||
volumes:
|
||||
- stellaops-keys:/app/keys
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
Edit `appsettings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"Encryption": {
|
||||
"Algorithm": "AES-256",
|
||||
"KeySize": 256,
|
||||
"KeyRotationDays": 90
|
||||
},
|
||||
"DataProtection": {
|
||||
"KeysPath": "/var/lib/stellaops/keys"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Create the keys directory:
|
||||
```bash
|
||||
sudo mkdir -p /var/lib/stellaops/keys
|
||||
sudo chown stellaops:stellaops /var/lib/stellaops/keys
|
||||
sudo chmod 700 /var/lib/stellaops/keys
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
Set in Helm values and use a PersistentVolume for key storage:
|
||||
|
||||
```yaml
|
||||
encryption:
|
||||
algorithm: "AES-256"
|
||||
keySize: 256
|
||||
keyRotationDays: 90
|
||||
|
||||
dataProtection:
|
||||
persistentVolume:
|
||||
enabled: true
|
||||
size: "100Mi"
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.security.encryption
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.core.crypto.available` — verifies cryptographic algorithms are available at the OS level
|
||||
- `check.security.secrets` — ensures encryption keys are not stored as plain text in configuration
|
||||
- `check.security.tls.certificate` — validates TLS certificate for encryption in transit
|
||||
Reference in New Issue
Block a user