# 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)_