audit, advisories and doctors/setup work
This commit is contained in:
master
608
docs/setup/setup-wizard-doctor-contract.md
Normal file
608
docs/setup/setup-wizard-doctor-contract.md
Normal file
@@ -0,0 +1,608 @@
|
||||
# Setup Wizard - Doctor Integration Contract
|
||||
|
||||
This document defines how the Setup Wizard integrates with the Doctor diagnostic system to validate each step and provide actionable remediation guidance.
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The Setup Wizard relies on Doctor checks to:
|
||||
1. **Validate** each configuration step
|
||||
2. **Detect** existing configuration (for resume/reconfigure)
|
||||
3. **Generate** runtime-specific fix commands
|
||||
4. **Verify** that fixes were applied correctly
|
||||
|
||||
---
|
||||
|
||||
## 2. Step-to-Check Mapping
|
||||
|
||||
### 2.1 Required Steps
|
||||
|
||||
| Step ID | Doctor Check ID | Severity | Blocks Progression |
|
||||
|---------|-----------------|----------|-------------------|
|
||||
| `database` | `check.database.connectivity` | Critical | Yes |
|
||||
| `database` | `check.database.permissions` | Critical | Yes |
|
||||
| `database` | `check.database.version` | Warning | No |
|
||||
| `valkey` | `check.services.valkey.connectivity` | Critical | Yes |
|
||||
| `valkey` | `check.services.valkey.ping` | Critical | Yes |
|
||||
| `migrations` | `check.database.migrations.applied` | Critical | Yes |
|
||||
| `migrations` | `check.database.migrations.checksums` | Critical | Yes |
|
||||
| `migrations` | `check.database.schema.version` | Info | No |
|
||||
| `admin` | `check.auth.admin.exists` | Critical | Yes |
|
||||
| `admin` | `check.auth.password.policy` | Warning | No |
|
||||
| `crypto` | `check.crypto.profile.valid` | Critical | Yes |
|
||||
| `crypto` | `check.crypto.signing.test` | Warning | No |
|
||||
|
||||
### 2.2 Optional Steps
|
||||
|
||||
| Step ID | Doctor Check ID | Severity | Blocks Progression |
|
||||
|---------|-----------------|----------|-------------------|
|
||||
| `vault` | `check.integration.vault.connected` | Warning | No |
|
||||
| `vault` | `check.integration.vault.auth` | Warning | No |
|
||||
| `vault` | `check.integration.vault.secrets.access` | Info | No |
|
||||
| `scm` | `check.integration.scm.github.auth` | Info | No |
|
||||
| `scm` | `check.integration.scm.github.permissions` | Info | No |
|
||||
| `scm` | `check.integration.scm.gitlab.auth` | Info | No |
|
||||
| `registry` | `check.integration.registry.connected` | Info | No |
|
||||
| `notifications` | `check.notify.channel.configured` | Info | No |
|
||||
| `notifications` | `check.notify.slack.webhook` | Info | No |
|
||||
| `notifications` | `check.notify.email.smtp` | Info | No |
|
||||
| `identity` | `check.security.identity.configured` | Info | No |
|
||||
| `identity` | `check.security.oidc.provider` | Info | No |
|
||||
| `environments` | `check.orchestrator.environment.exists` | Info | No |
|
||||
| `environments` | `check.orchestrator.environment.valid` | Info | No |
|
||||
| `agents` | `check.orchestrator.agent.registered` | Info | No |
|
||||
| `agents` | `check.orchestrator.agent.healthy` | Info | No |
|
||||
| `feeds` | `check.feeds.sync.enabled` | Info | No |
|
||||
|
||||
---
|
||||
|
||||
## 3. Check Output Model
|
||||
|
||||
### 3.1 CheckResult Schema
|
||||
|
||||
```csharp
|
||||
public sealed record CheckResult
|
||||
{
|
||||
public required string CheckId { get; init; }
|
||||
public required CheckStatus Status { get; init; } // Pass, Warn, Fail
|
||||
public required string Message { get; init; }
|
||||
public required TimeSpan Duration { get; init; }
|
||||
public ImmutableDictionary<string, object> Evidence { get; init; }
|
||||
public ImmutableArray<LikelyCause> LikelyCauses { get; init; }
|
||||
public ImmutableArray<RemediationCommand> Remediations { get; init; }
|
||||
public string? VerificationCommand { get; init; }
|
||||
}
|
||||
|
||||
public enum CheckStatus { Pass, Warn, Fail }
|
||||
|
||||
public sealed record LikelyCause
|
||||
{
|
||||
public required int Priority { get; init; } // 1 = most likely
|
||||
public required string Description { get; init; }
|
||||
public string? DocumentationUrl { get; init; }
|
||||
}
|
||||
|
||||
public sealed record RemediationCommand
|
||||
{
|
||||
public required RuntimeEnvironment Runtime { get; init; }
|
||||
public required string Command { get; init; }
|
||||
public required string Description { get; init; }
|
||||
public bool RequiresSudo { get; init; }
|
||||
public bool IsDangerous { get; init; } // Requires confirmation
|
||||
public ImmutableDictionary<string, string> Placeholders { get; init; }
|
||||
}
|
||||
|
||||
public enum RuntimeEnvironment
|
||||
{
|
||||
DockerCompose,
|
||||
Kubernetes,
|
||||
Systemd,
|
||||
WindowsService,
|
||||
Bare,
|
||||
Any
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Evidence Dictionary
|
||||
|
||||
The `Evidence` dictionary contains check-specific data:
|
||||
|
||||
| Check Category | Evidence Keys |
|
||||
|----------------|---------------|
|
||||
| **Database** | `host`, `port`, `database`, `version`, `user`, `sslMode` |
|
||||
| **Valkey** | `host`, `port`, `version`, `usedMemory`, `maxMemory` |
|
||||
| **Migrations** | `pendingCount`, `appliedCount`, `lastMigration`, `failedMigrations` |
|
||||
| **Auth** | `adminCount`, `adminUsername`, `passwordLastChanged` |
|
||||
| **Vault** | `provider`, `version`, `mountPoints`, `authMethod` |
|
||||
| **SCM** | `provider`, `rateLimit`, `remainingCalls`, `organization` |
|
||||
|
||||
---
|
||||
|
||||
## 4. Remediation Command Generation
|
||||
|
||||
### 4.1 Runtime Detection
|
||||
|
||||
The wizard detects the runtime environment via:
|
||||
|
||||
```csharp
|
||||
public interface IRuntimeDetector
|
||||
{
|
||||
RuntimeEnvironment Detect();
|
||||
bool IsDockerAvailable();
|
||||
bool IsKubernetesContext();
|
||||
bool IsSystemdManaged(string serviceName);
|
||||
string GetComposeProjectPath();
|
||||
string GetKubernetesNamespace();
|
||||
}
|
||||
```
|
||||
|
||||
Detection logic:
|
||||
1. Check for `/.dockerenv` file → Docker container
|
||||
2. Check for `KUBERNETES_SERVICE_HOST` → Kubernetes
|
||||
3. Check for `docker compose` command → Docker Compose
|
||||
4. Check for `systemctl` command → systemd
|
||||
5. Check for Windows services → Windows Service
|
||||
6. Default → Bare (manual)
|
||||
|
||||
### 4.2 Command Templates
|
||||
|
||||
#### Database Connection Failure
|
||||
|
||||
```yaml
|
||||
check.database.connectivity:
|
||||
likelyCauses:
|
||||
- priority: 1
|
||||
description: "PostgreSQL is not running"
|
||||
- priority: 2
|
||||
description: "Firewall blocking port 5432"
|
||||
- priority: 3
|
||||
description: "Incorrect host or port"
|
||||
- priority: 4
|
||||
description: "Network connectivity issue"
|
||||
|
||||
remediations:
|
||||
- runtime: DockerCompose
|
||||
description: "Start PostgreSQL container"
|
||||
command: "docker compose -f {{COMPOSE_FILE}} up -d postgres"
|
||||
placeholders:
|
||||
COMPOSE_FILE: "devops/compose/docker-compose.yml"
|
||||
|
||||
- runtime: Kubernetes
|
||||
description: "Check PostgreSQL pod status"
|
||||
command: "kubectl get pods -n {{NAMESPACE}} -l app=postgres"
|
||||
placeholders:
|
||||
NAMESPACE: "stellaops"
|
||||
|
||||
- runtime: Systemd
|
||||
description: "Start PostgreSQL service"
|
||||
command: "sudo systemctl start postgresql"
|
||||
requiresSudo: true
|
||||
|
||||
- runtime: Any
|
||||
description: "Verify PostgreSQL is listening"
|
||||
command: "pg_isready -h {{HOST}} -p {{PORT}}"
|
||||
placeholders:
|
||||
HOST: "localhost"
|
||||
PORT: "5432"
|
||||
|
||||
verificationCommand: "pg_isready -h {{HOST}} -p {{PORT}}"
|
||||
```
|
||||
|
||||
#### Valkey Connection Failure
|
||||
|
||||
```yaml
|
||||
check.services.valkey.connectivity:
|
||||
likelyCauses:
|
||||
- priority: 1
|
||||
description: "Valkey/Redis is not running"
|
||||
- priority: 2
|
||||
description: "Firewall blocking port 6379"
|
||||
- priority: 3
|
||||
description: "Authentication required but not configured"
|
||||
|
||||
remediations:
|
||||
- runtime: DockerCompose
|
||||
description: "Start Valkey container"
|
||||
command: "docker compose -f {{COMPOSE_FILE}} up -d valkey"
|
||||
placeholders:
|
||||
COMPOSE_FILE: "devops/compose/docker-compose.yml"
|
||||
|
||||
- runtime: Kubernetes
|
||||
description: "Check Valkey pod status"
|
||||
command: "kubectl get pods -n {{NAMESPACE}} -l app=valkey"
|
||||
placeholders:
|
||||
NAMESPACE: "stellaops"
|
||||
|
||||
- runtime: Systemd
|
||||
description: "Start Valkey service"
|
||||
command: "sudo systemctl start valkey"
|
||||
requiresSudo: true
|
||||
|
||||
- runtime: Any
|
||||
description: "Test Valkey connection"
|
||||
command: "redis-cli -h {{HOST}} -p {{PORT}} PING"
|
||||
placeholders:
|
||||
HOST: "localhost"
|
||||
PORT: "6379"
|
||||
|
||||
verificationCommand: "redis-cli -h {{HOST}} -p {{PORT}} PING"
|
||||
```
|
||||
|
||||
#### Pending Migrations
|
||||
|
||||
```yaml
|
||||
check.database.migrations.applied:
|
||||
likelyCauses:
|
||||
- priority: 1
|
||||
description: "Pending release migrations require manual execution"
|
||||
- priority: 2
|
||||
description: "Startup migrations not yet applied"
|
||||
|
||||
remediations:
|
||||
- runtime: Any
|
||||
description: "Run pending migrations (dry-run first)"
|
||||
command: "stella migrations-run --module all --dry-run"
|
||||
|
||||
- runtime: Any
|
||||
description: "Apply all pending migrations"
|
||||
command: "stella migrations-run --module all"
|
||||
isDangerous: true
|
||||
|
||||
- runtime: DockerCompose
|
||||
description: "Run migrations in container"
|
||||
command: "docker compose exec api stella migrations-run --module all"
|
||||
|
||||
- runtime: Kubernetes
|
||||
description: "Run migrations job"
|
||||
command: "kubectl apply -f devops/k8s/jobs/migrations.yaml"
|
||||
|
||||
verificationCommand: "stella migrations-run --module all --dry-run"
|
||||
```
|
||||
|
||||
#### Vault Authentication Failure
|
||||
|
||||
```yaml
|
||||
check.integration.vault.auth:
|
||||
likelyCauses:
|
||||
- priority: 1
|
||||
description: "Vault token expired or revoked"
|
||||
- priority: 2
|
||||
description: "AppRole credentials invalid"
|
||||
- priority: 3
|
||||
description: "Kubernetes service account not configured"
|
||||
- priority: 4
|
||||
description: "Vault server unreachable"
|
||||
|
||||
remediations:
|
||||
- runtime: Any
|
||||
description: "Test Vault connectivity"
|
||||
command: "curl -s {{VAULT_ADDR}}/v1/sys/health"
|
||||
placeholders:
|
||||
VAULT_ADDR: "https://vault.example.com:8200"
|
||||
|
||||
- runtime: Any
|
||||
description: "Verify token validity"
|
||||
command: "vault token lookup"
|
||||
|
||||
- runtime: Kubernetes
|
||||
description: "Check Kubernetes auth configuration"
|
||||
command: "kubectl get serviceaccount -n {{NAMESPACE}} stellaops-vault-auth"
|
||||
placeholders:
|
||||
NAMESPACE: "stellaops"
|
||||
|
||||
verificationCommand: "vault token lookup"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Placeholder Resolution
|
||||
|
||||
### 5.1 Placeholder Sources
|
||||
|
||||
Placeholders in commands are resolved from:
|
||||
|
||||
| Source | Priority | Example |
|
||||
|--------|----------|---------|
|
||||
| User input | 1 (highest) | `{{HOST}}` from form field |
|
||||
| Environment | 2 | `{{VAULT_ADDR}}` from env |
|
||||
| Detection | 3 | `{{NAMESPACE}}` from context |
|
||||
| Default | 4 (lowest) | Fallback value |
|
||||
|
||||
### 5.2 Placeholder Syntax
|
||||
|
||||
```
|
||||
{{PLACEHOLDER_NAME}}
|
||||
{{PLACEHOLDER_NAME:-default_value}}
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `{{HOST}}` - Required placeholder
|
||||
- `{{PORT:-5432}}` - Optional with default
|
||||
- `{{COMPOSE_FILE:-docker-compose.yml}}` - File path default
|
||||
|
||||
### 5.3 Secret Redaction
|
||||
|
||||
Commands containing secrets are never displayed with actual values:
|
||||
|
||||
| Placeholder | Display | Actual |
|
||||
|-------------|---------|--------|
|
||||
| `{{PASSWORD}}` | `{{PASSWORD}}` | Never resolved in display |
|
||||
| `{{TOKEN}}` | `{{TOKEN}}` | Never resolved in display |
|
||||
| `{{SECRET_KEY}}` | `{{SECRET_KEY}}` | Never resolved in display |
|
||||
|
||||
The user must copy and manually substitute secrets.
|
||||
|
||||
---
|
||||
|
||||
## 6. Verification Flow
|
||||
|
||||
### 6.1 Post-Fix Verification
|
||||
|
||||
After the user applies a fix, the wizard:
|
||||
|
||||
1. **Wait** - Pause for user confirmation ("I've run this command")
|
||||
2. **Verify** - Run the verification command
|
||||
3. **Re-check** - Run the original Doctor check
|
||||
4. **Report** - Show success or next steps
|
||||
|
||||
### 6.2 Verification Command Execution
|
||||
|
||||
```csharp
|
||||
public interface IVerificationExecutor
|
||||
{
|
||||
Task<VerificationResult> ExecuteAsync(
|
||||
string command,
|
||||
TimeSpan timeout,
|
||||
CancellationToken ct);
|
||||
}
|
||||
|
||||
public sealed record VerificationResult
|
||||
{
|
||||
public required bool Success { get; init; }
|
||||
public required int ExitCode { get; init; }
|
||||
public required string Output { get; init; }
|
||||
public required TimeSpan Duration { get; init; }
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 Re-Check Behavior
|
||||
|
||||
```
|
||||
[FAIL] check.database.connectivity
|
||||
|
||||
Suggested fix applied. Verifying...
|
||||
|
||||
[RUN] pg_isready -h localhost -p 5432
|
||||
localhost:5432 - accepting connections
|
||||
|
||||
Re-running check...
|
||||
|
||||
[PASS] check.database.connectivity
|
||||
PostgreSQL connection successful
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Check Aggregation
|
||||
|
||||
### 7.1 Step Completion Criteria
|
||||
|
||||
A step is complete when:
|
||||
- All **Critical** checks pass
|
||||
- No **Fail** status on any check
|
||||
- User has acknowledged all **Warning** checks
|
||||
|
||||
### 7.2 Aggregated Status
|
||||
|
||||
```csharp
|
||||
public enum StepValidationStatus
|
||||
{
|
||||
NotStarted, // No checks run
|
||||
InProgress, // Checks running
|
||||
Passed, // All critical pass, no failures
|
||||
PassedWithWarns, // All critical pass, some warnings
|
||||
Failed, // Any critical failure
|
||||
Skipped // User explicitly skipped
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 Status Rollup for Thresholds
|
||||
|
||||
```
|
||||
Operational Threshold:
|
||||
[x] check.database.connectivity PASS
|
||||
[x] check.database.permissions PASS
|
||||
[x] check.database.migrations.applied PASS
|
||||
[x] check.services.valkey.connectivity PASS
|
||||
[x] check.auth.admin.exists PASS
|
||||
[x] check.crypto.profile.valid PASS
|
||||
|
||||
Status: OPERATIONAL (6/6 required checks passed)
|
||||
|
||||
Production-Ready Threshold:
|
||||
[x] check.security.identity.configured PASS
|
||||
[x] check.integration.vault.connected PASS
|
||||
[x] check.integration.scm.connected PASS
|
||||
[x] check.notify.channel.configured PASS
|
||||
[ ] check.orchestrator.agent.healthy SKIP
|
||||
[ ] check.feeds.sync.enabled SKIP
|
||||
|
||||
Status: NOT PRODUCTION-READY (4/6 recommended, 2 skipped)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Doctor Engine Integration
|
||||
|
||||
### 8.1 Wizard-Specific Check Context
|
||||
|
||||
The wizard provides context to Doctor checks:
|
||||
|
||||
```csharp
|
||||
public sealed record WizardCheckContext
|
||||
{
|
||||
public required string StepId { get; init; }
|
||||
public required RuntimeEnvironment DetectedRuntime { get; init; }
|
||||
public required ImmutableDictionary<string, string> UserInputs { get; init; }
|
||||
public bool GenerateRemediations { get; init; } = true;
|
||||
public bool IncludePlaceholders { get; init; } = true;
|
||||
}
|
||||
```
|
||||
|
||||
### 8.2 Check Invocation
|
||||
|
||||
```csharp
|
||||
public interface IWizardDoctorClient
|
||||
{
|
||||
Task<ImmutableArray<CheckResult>> RunStepChecksAsync(
|
||||
string stepId,
|
||||
WizardCheckContext context,
|
||||
CancellationToken ct);
|
||||
|
||||
Task<CheckResult> RunSingleCheckAsync(
|
||||
string checkId,
|
||||
WizardCheckContext context,
|
||||
CancellationToken ct);
|
||||
|
||||
Task<VerificationResult> RunVerificationAsync(
|
||||
string command,
|
||||
WizardCheckContext context,
|
||||
CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
### 8.3 Check Timeout
|
||||
|
||||
| Check Category | Default Timeout | Max Timeout |
|
||||
|----------------|-----------------|-------------|
|
||||
| Connectivity | 10 seconds | 30 seconds |
|
||||
| Authentication | 15 seconds | 60 seconds |
|
||||
| Migrations | 60 seconds | 300 seconds |
|
||||
| Full validation | 30 seconds | 120 seconds |
|
||||
|
||||
---
|
||||
|
||||
## 9. Remediation Safety
|
||||
|
||||
### 9.1 Dangerous Commands
|
||||
|
||||
Commands marked `isDangerous: true` require user confirmation:
|
||||
|
||||
```
|
||||
WARNING: This command will modify your database schema.
|
||||
|
||||
Command:
|
||||
stella migrations-run --module all
|
||||
|
||||
This action:
|
||||
- Applies 5 pending migrations
|
||||
- Cannot be automatically rolled back
|
||||
- May take several minutes
|
||||
|
||||
Type 'apply' to confirm: _
|
||||
```
|
||||
|
||||
### 9.2 Sudo Requirements
|
||||
|
||||
Commands requiring `sudo` show a notice:
|
||||
|
||||
```
|
||||
This command requires administrator privileges.
|
||||
|
||||
Command:
|
||||
sudo systemctl start postgresql
|
||||
|
||||
[Copy Command]
|
||||
|
||||
Note: You may be prompted for your password.
|
||||
```
|
||||
|
||||
### 9.3 Secret Substitution Notice
|
||||
|
||||
```
|
||||
This command contains placeholders for sensitive values.
|
||||
|
||||
Command:
|
||||
vault write auth/approle/login role_id={{ROLE_ID}} secret_id={{SECRET_ID}}
|
||||
|
||||
Before running:
|
||||
1. Replace {{ROLE_ID}} with your AppRole Role ID
|
||||
2. Replace {{SECRET_ID}} with your AppRole Secret ID
|
||||
|
||||
[Copy Command]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Check Plugin Requirements
|
||||
|
||||
### 10.1 New Checks for Setup Wizard
|
||||
|
||||
The following checks may need to be added to existing plugins:
|
||||
|
||||
| Plugin | New Check ID | Purpose |
|
||||
|--------|--------------|---------|
|
||||
| Core | `check.auth.admin.exists` | Verify admin user exists |
|
||||
| Core | `check.auth.password.policy` | Verify password complexity |
|
||||
| Core | `check.crypto.signing.test` | Test signing operation |
|
||||
| Database | `check.database.migrations.checksums` | Verify migration integrity |
|
||||
| Integration | `check.integration.vault.secrets.access` | Test secret retrieval |
|
||||
| Integration | `check.orchestrator.environment.valid` | Validate environment config |
|
||||
| Notify | `check.notify.delivery.test` | Test notification delivery |
|
||||
|
||||
### 10.2 Check Implementation Contract
|
||||
|
||||
Each check must implement:
|
||||
|
||||
```csharp
|
||||
public interface ISetupWizardAwareCheck : IDoctorCheck
|
||||
{
|
||||
// Standard check execution
|
||||
Task<CheckResult> ExecuteAsync(CheckContext context, CancellationToken ct);
|
||||
|
||||
// Generate runtime-specific remediations
|
||||
ImmutableArray<RemediationCommand> GetRemediations(
|
||||
CheckResult result,
|
||||
RuntimeEnvironment runtime);
|
||||
|
||||
// Verification command for this check
|
||||
string? GetVerificationCommand(RuntimeEnvironment runtime);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Audit Trail
|
||||
|
||||
### 11.1 Setup Event Logging
|
||||
|
||||
All wizard actions are logged to the Timeline service:
|
||||
|
||||
```csharp
|
||||
public sealed record SetupWizardEvent
|
||||
{
|
||||
public required string EventType { get; init; } // step.started, step.completed, check.failed, etc.
|
||||
public required string StepId { get; init; }
|
||||
public required string? CheckId { get; init; }
|
||||
public required CheckStatus? Status { get; init; }
|
||||
public required DateTimeOffset OccurredAt { get; init; }
|
||||
public required string? UserId { get; init; }
|
||||
public ImmutableDictionary<string, string> Metadata { get; init; }
|
||||
}
|
||||
```
|
||||
|
||||
### 11.2 Event Types
|
||||
|
||||
| Event Type | Description |
|
||||
|------------|-------------|
|
||||
| `setup.started` | Wizard initiated |
|
||||
| `setup.completed` | Wizard finished successfully |
|
||||
| `setup.aborted` | Wizard cancelled |
|
||||
| `step.started` | Step configuration began |
|
||||
| `step.completed` | Step passed all checks |
|
||||
| `step.failed` | Step failed validation |
|
||||
| `step.skipped` | User skipped optional step |
|
||||
| `check.passed` | Individual check passed |
|
||||
| `check.failed` | Individual check failed |
|
||||
| `check.warned` | Individual check warned |
|
||||
| `remediation.copied` | User copied fix command |
|
||||
| `remediation.verified` | Fix verification succeeded |
|
||||
Reference in New Issue
Block a user