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
2026-03-27 12:28:00 +02:00
parent fbd24e71de
commit c58a236d70
326 changed files with 18500 additions and 463 deletions

View File

@@ -0,0 +1,68 @@
---
checkId: check.logs.directory.writable
plugin: stellaops.doctor.observability
severity: fail
tags: [observability, logs, quick]
---
# Log Directory Writable
## What It Checks
Verifies that the log directory exists and is writable. The check:
- Reads the log path from `Logging:Path` configuration. Falls back to platform defaults: `/var/log/stellaops` on Linux, `%ProgramData%\StellaOps\logs` on Windows.
- Verifies the directory exists.
- Writes a temporary file to test write access, then deletes it.
- Fails if the directory does not exist, is not writable due to permissions, or encounters an I/O error.
## Why It Matters
If the log directory is not writable, application logs are silently lost. Without logs, troubleshooting service failures, debugging policy evaluation issues, and performing security incident investigations becomes impossible. This is a severity-fail check because log loss breaks the auditability guarantee.
## Common Causes
- Log directory not created during installation
- Directory was deleted
- Configuration points to wrong path
- Insufficient permissions or directory owned by different user
- Read-only file system
- Disk full
## How to Fix
### Docker Compose
```yaml
volumes:
- log-data:/var/log/stellaops
```
```bash
docker exec <platform-container> mkdir -p /var/log/stellaops
```
### Bare Metal / systemd
```bash
# Create log directory
sudo mkdir -p /var/log/stellaops
# Set ownership and permissions
sudo chown -R stellaops:stellaops /var/log/stellaops
sudo chmod 755 /var/log/stellaops
```
### Kubernetes / Helm
```yaml
logging:
path: "/var/log/stellaops"
persistence:
enabled: true
size: 10Gi
```
Or use an `emptyDir` volume for ephemeral log storage with a sidecar shipping logs to an external system.
## Verification
```
stella doctor run --check check.logs.directory.writable
```
## Related Checks
- `check.logs.rotation.configured` — verifies log rotation is configured
- `check.storage.diskspace` — verifies sufficient disk space is available