synergy moats product advisory implementations
This commit is contained in:
master
442
docs/doctor/plugins.md
Normal file
442
docs/doctor/plugins.md
Normal file
@@ -0,0 +1,442 @@
|
||||
# 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 |
|
||||
| **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
|
||||
|
||||
---
|
||||
|
||||
## 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-17 (UTC)_
|
||||
Reference in New Issue
Block a user