496 lines
11 KiB
Markdown
496 lines
11 KiB
Markdown
# Doctor Plugins Reference
|
|
|
|
> **Sprint:** SPRINT_20260117_025_Doctor_coverage_expansion
|
|
> **Task:** DOC-EXP-006 - Documentation Updates
|
|
|
|
This document describes the Doctor health check plugins, their checks, and configuration options.
|
|
|
|
## Plugin Overview
|
|
|
|
| Plugin | Directory | Checks | Description |
|
|
|--------|-----------|--------|-------------|
|
|
| **Postgres** | `StellaOps.Doctor.Plugin.Postgres` | 3 | PostgreSQL database health |
|
|
| **Storage** | `StellaOps.Doctor.Plugin.Storage` | 3 | Disk and storage health |
|
|
| **Crypto** | `StellaOps.Doctor.Plugin.Crypto` | 4 | Regional crypto compliance |
|
|
| **Timestamping** | `StellaOps.Doctor.Plugin.Timestamping` | 22 | RFC-3161 and eIDAS timestamp health |
|
|
| **EvidenceLocker** | `StellaOps.Doctor.Plugin.EvidenceLocker` | 4 | Evidence integrity checks |
|
|
| **Attestor** | `StellaOps.Doctor.Plugin.Attestor` | 3+ | Signing and verification |
|
|
| **Auth** | `StellaOps.Doctor.Plugin.Auth` | 3+ | Authentication health |
|
|
| **Policy** | `StellaOps.Doctor.Plugin.Policy` | 3+ | Policy engine health |
|
|
| **Vex** | `StellaOps.Doctor.Plugin.Vex` | 3+ | VEX feed health |
|
|
| **Operations** | `StellaOps.Doctor.Plugin.Operations` | 3+ | General operations |
|
|
|
|
---
|
|
|
|
## PostgreSQL Plugin
|
|
|
|
**Plugin ID:** `stellaops.doctor.postgres`
|
|
**NuGet:** `StellaOps.Doctor.Plugin.Postgres`
|
|
|
|
### Checks
|
|
|
|
#### check.postgres.connectivity
|
|
|
|
Verifies PostgreSQL database connectivity and response time.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Fail |
|
|
| **Tags** | database, postgres, connectivity, core |
|
|
| **Timeout** | 10 seconds |
|
|
|
|
**Thresholds:**
|
|
- Warning: Latency > 100ms
|
|
- Critical: Latency > 500ms
|
|
|
|
**Evidence collected:**
|
|
- Connection string (masked)
|
|
- Server version
|
|
- Server timestamp
|
|
- Latency in milliseconds
|
|
|
|
**Remediation:**
|
|
```bash
|
|
# Check database status
|
|
stella db status
|
|
|
|
# Test connection
|
|
stella db ping
|
|
|
|
# View connection configuration
|
|
stella config get Database:ConnectionString
|
|
```
|
|
|
|
#### check.postgres.migration-status
|
|
|
|
Checks for pending database migrations.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Warning |
|
|
| **Tags** | database, postgres, migrations |
|
|
|
|
**Evidence collected:**
|
|
- Current schema version
|
|
- Pending migrations list
|
|
- Last migration timestamp
|
|
|
|
**Remediation:**
|
|
```bash
|
|
# View migration status
|
|
stella db migrations status
|
|
|
|
# Apply pending migrations
|
|
stella db migrations run
|
|
|
|
# Verify migration state
|
|
stella db migrations verify
|
|
```
|
|
|
|
#### check.postgres.connection-pool
|
|
|
|
Monitors connection pool health and utilization.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Warning |
|
|
| **Tags** | database, postgres, pool, performance |
|
|
|
|
**Thresholds:**
|
|
- Warning: Utilization > 70%
|
|
- Critical: Utilization > 90%
|
|
|
|
**Evidence collected:**
|
|
- Active connections
|
|
- Idle connections
|
|
- Maximum pool size
|
|
- Pool utilization percentage
|
|
|
|
**Remediation:**
|
|
```bash
|
|
# View pool statistics
|
|
stella db pool stats
|
|
|
|
# Increase pool size (if needed)
|
|
stella config set Database:MaxPoolSize 50
|
|
```
|
|
|
|
---
|
|
|
|
## Storage Plugin
|
|
|
|
**Plugin ID:** `stellaops.doctor.storage`
|
|
**NuGet:** `StellaOps.Doctor.Plugin.Storage`
|
|
|
|
### Checks
|
|
|
|
#### check.storage.disk-space
|
|
|
|
Checks available disk space on configured storage paths.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Fail |
|
|
| **Tags** | storage, disk, capacity |
|
|
|
|
**Thresholds:**
|
|
- Warning: Usage > 80%
|
|
- Critical: Usage > 90%
|
|
|
|
**Evidence collected:**
|
|
- Drive/mount path
|
|
- Total space
|
|
- Used space
|
|
- Free space
|
|
- Percentage used
|
|
|
|
**Remediation:**
|
|
```bash
|
|
# List large files
|
|
stella storage analyze --path /var/stella
|
|
|
|
# Clean up old evidence
|
|
stella evidence cleanup --older-than 90d
|
|
|
|
# View storage summary
|
|
stella storage summary
|
|
```
|
|
|
|
#### check.storage.evidence-locker-write
|
|
|
|
Verifies write permissions to the evidence locker directory.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Fail |
|
|
| **Tags** | storage, evidence, permissions |
|
|
|
|
**Evidence collected:**
|
|
- Evidence locker path
|
|
- Write test result
|
|
- Directory permissions
|
|
|
|
**Remediation:**
|
|
```bash
|
|
# Check permissions
|
|
stella evidence locker status
|
|
|
|
# Repair permissions
|
|
stella evidence locker repair --permissions
|
|
|
|
# Verify configuration
|
|
stella config get EvidenceLocker:BasePath
|
|
```
|
|
|
|
#### check.storage.backup-directory
|
|
|
|
Verifies backup directory accessibility (skipped if not configured).
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Warning |
|
|
| **Tags** | storage, backup |
|
|
|
|
**Evidence collected:**
|
|
- Backup directory path
|
|
- Write accessibility
|
|
- Last backup timestamp
|
|
|
|
---
|
|
|
|
## Crypto Plugin
|
|
|
|
**Plugin ID:** `stellaops.doctor.crypto`
|
|
**NuGet:** `StellaOps.Doctor.Plugin.Crypto`
|
|
|
|
### Checks
|
|
|
|
#### check.crypto.fips-compliance
|
|
|
|
Verifies FIPS 140-2/140-3 compliance for US government deployments.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Fail (when FIPS profile active) |
|
|
| **Tags** | crypto, compliance, fips, regional |
|
|
|
|
**Evidence collected:**
|
|
- Active crypto profile
|
|
- FIPS mode enabled status
|
|
- Validated algorithms
|
|
- Non-compliant algorithms detected
|
|
|
|
**Remediation:**
|
|
```bash
|
|
# Check current profile
|
|
stella crypto profile show
|
|
|
|
# Enable FIPS mode
|
|
stella crypto profile set fips
|
|
|
|
# Verify FIPS compliance
|
|
stella crypto verify --standard fips
|
|
```
|
|
|
|
#### check.crypto.eidas-compliance
|
|
|
|
Verifies eIDAS compliance for EU deployments.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Fail (when eIDAS profile active) |
|
|
| **Tags** | crypto, compliance, eidas, regional, eu |
|
|
|
|
**Evidence collected:**
|
|
- Active crypto profile
|
|
- eIDAS algorithm support
|
|
- Qualified signature availability
|
|
|
|
**Remediation:**
|
|
```bash
|
|
# Enable eIDAS profile
|
|
stella crypto profile set eidas
|
|
|
|
# Verify compliance
|
|
stella crypto verify --standard eidas
|
|
```
|
|
|
|
#### check.crypto.gost-availability
|
|
|
|
Verifies GOST algorithm availability for Russian deployments.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Fail (when GOST profile active) |
|
|
| **Tags** | crypto, compliance, gost, regional, russia |
|
|
|
|
**Evidence collected:**
|
|
- GOST provider status
|
|
- Available GOST algorithms
|
|
- Library version
|
|
|
|
#### check.crypto.sm-availability
|
|
|
|
Verifies SM2/SM3/SM4 algorithm availability for Chinese deployments.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Fail (when SM profile active) |
|
|
| **Tags** | crypto, compliance, sm, regional, china |
|
|
|
|
**Evidence collected:**
|
|
- SM crypto provider status
|
|
- Available SM algorithms
|
|
- Library version
|
|
|
|
---
|
|
|
|
## Timestamping Plugin
|
|
|
|
**Plugin ID:** `stellaops.doctor.timestamping`
|
|
**NuGet:** `StellaOps.Doctor.Plugin.Timestamping`
|
|
|
|
### Checks
|
|
|
|
- `check.timestamp.tsa.reachable` - TSA endpoints reachable
|
|
- `check.timestamp.tsa.response-time` - TSA latency thresholds
|
|
- `check.timestamp.tsa.valid-response` - TSA returns valid RFC-3161 response
|
|
- `check.timestamp.tsa.failover-ready` - Backup TSA readiness
|
|
- `check.timestamp.tsa.cert-expiry` - TSA signing cert expiry
|
|
- `check.timestamp.tsa.root-expiry` - TSA root trust expiry
|
|
- `check.timestamp.tsa.chain-valid` - TSA certificate chain validity
|
|
- `check.timestamp.ocsp.responder` - OCSP responder availability
|
|
- `check.timestamp.ocsp.stapling` - OCSP stapling enabled
|
|
- `check.timestamp.crl.distribution` - CRL distribution availability
|
|
- `check.timestamp.revocation.cache-fresh` - OCSP/CRL cache freshness
|
|
- `check.timestamp.evidence.staleness` - Aggregate evidence staleness
|
|
- `check.timestamp.evidence.tst.expiry` - TSTs approaching expiry
|
|
- `check.timestamp.evidence.tst.deprecated-algo` - TSTs using deprecated algorithms
|
|
- `check.timestamp.evidence.tst.missing-stapling` - TSTs missing stapled revocation data
|
|
- `check.timestamp.evidence.retimestamp.pending` - Pending retimestamp workload
|
|
- `check.timestamp.eidas.trustlist.fresh` - EU Trust List freshness
|
|
- `check.timestamp.eidas.qts.qualified` - Qualified TSA providers still qualified
|
|
- `check.timestamp.eidas.qts.status-change` - QTS status changes
|
|
- `check.timestamp.timesync.system` - System time synchronization
|
|
- `check.timestamp.timesync.tsa-skew` - TSA time skew
|
|
- `check.timestamp.timesync.rekor-correlation` - TST vs Rekor time correlation
|
|
|
|
### Configuration
|
|
|
|
```yaml
|
|
Doctor:
|
|
Timestamping:
|
|
TsaEndpoints:
|
|
- name: PrimaryTsa
|
|
url: https://tsa.example.org
|
|
- name: BackupTsa
|
|
url: https://tsa-backup.example.org
|
|
WarnLatencyMs: 5000
|
|
CriticalLatencyMs: 30000
|
|
MinHealthyTsas: 2
|
|
Evidence:
|
|
DeprecatedAlgorithms:
|
|
- SHA1
|
|
```
|
|
|
|
Note: evidence staleness, OCSP stapling, and chain validation checks require data providers to be registered by the host.
|
|
|
|
---
|
|
|
|
## Evidence Locker Plugin
|
|
|
|
**Plugin ID:** `stellaops.doctor.evidencelocker`
|
|
**NuGet:** `StellaOps.Doctor.Plugin.EvidenceLocker`
|
|
|
|
### Checks
|
|
|
|
#### check.evidence.attestation-retrieval
|
|
|
|
Verifies attestation retrieval functionality.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Fail |
|
|
| **Tags** | evidence, attestation, retrieval |
|
|
|
|
**Evidence collected:**
|
|
- Sample attestation ID
|
|
- Retrieval latency
|
|
- Storage backend status
|
|
|
|
**Remediation:**
|
|
```bash
|
|
# Check evidence locker status
|
|
stella evidence locker status
|
|
|
|
# Verify index integrity
|
|
stella evidence index verify
|
|
|
|
# Rebuild index if needed
|
|
stella evidence index rebuild
|
|
```
|
|
|
|
#### check.evidence.provenance-chain
|
|
|
|
Verifies provenance chain integrity.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Fail |
|
|
| **Tags** | evidence, provenance, integrity |
|
|
|
|
**Evidence collected:**
|
|
- Chain depth
|
|
- Verification result
|
|
- Last verified timestamp
|
|
|
|
#### check.evidence.index
|
|
|
|
Verifies evidence index health and consistency.
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Warning |
|
|
| **Tags** | evidence, index, consistency |
|
|
|
|
**Evidence collected:**
|
|
- Index entry count
|
|
- Orphaned entries
|
|
- Missing entries
|
|
|
|
#### check.evidence.merkle-anchor
|
|
|
|
Verifies Merkle tree anchoring (when configured).
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Severity** | Warning |
|
|
| **Tags** | evidence, merkle, anchoring |
|
|
|
|
**Evidence collected:**
|
|
- Anchor status
|
|
- Last anchor timestamp
|
|
- Pending entries
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Enabling/Disabling Plugins
|
|
|
|
In `appsettings.yaml`:
|
|
|
|
```yaml
|
|
Doctor:
|
|
Plugins:
|
|
Postgres:
|
|
Enabled: true
|
|
Storage:
|
|
Enabled: true
|
|
Crypto:
|
|
Enabled: true
|
|
ActiveProfile: international # fips, eidas, gost, sm
|
|
EvidenceLocker:
|
|
Enabled: true
|
|
```
|
|
|
|
### Check-Level Configuration
|
|
|
|
```yaml
|
|
Doctor:
|
|
Checks:
|
|
"check.storage.disk-space":
|
|
WarningThreshold: 75 # Override default 80%
|
|
CriticalThreshold: 85 # Override default 90%
|
|
"check.postgres.connectivity":
|
|
TimeoutSeconds: 15 # Override default 10
|
|
```
|
|
|
|
### Report Storage Configuration
|
|
|
|
```yaml
|
|
Doctor:
|
|
ReportStorage:
|
|
Backend: postgres # inmemory, postgres, filesystem
|
|
RetentionDays: 90
|
|
CompressionEnabled: true
|
|
```
|
|
|
|
---
|
|
|
|
## Running Checks
|
|
|
|
### CLI
|
|
|
|
```bash
|
|
# Run all checks
|
|
stella doctor
|
|
|
|
# Run specific plugin
|
|
stella doctor --plugin postgres
|
|
|
|
# Run specific check
|
|
stella doctor --check check.postgres.connectivity
|
|
|
|
# Output formats
|
|
stella doctor --format table # Default
|
|
stella doctor --format json
|
|
stella doctor --format markdown
|
|
```
|
|
|
|
### API
|
|
|
|
```bash
|
|
# Run all checks
|
|
curl -X POST /api/v1/doctor/run
|
|
|
|
# Run with filters
|
|
curl -X POST /api/v1/doctor/run \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"plugins": ["postgres", "storage"]}'
|
|
```
|
|
|
|
---
|
|
|
|
_Last updated: 2026-01-20 (UTC)_
|