584 lines
19 KiB
Markdown
584 lines
19 KiB
Markdown
# Setup Wizard - Capability Specification
|
|
|
|
This document defines the functional requirements for the Stella Ops Setup Wizard, covering both CLI and UI implementations.
|
|
|
|
## 1. Overview
|
|
|
|
The Setup Wizard provides a guided, step-by-step configuration experience that:
|
|
- Validates infrastructure dependencies (PostgreSQL, Valkey)
|
|
- Runs database migrations
|
|
- Configures required integrations
|
|
- Sets up environments and agents
|
|
- Verifies each step via Doctor checks
|
|
|
|
---
|
|
|
|
## 2. Completion Thresholds
|
|
|
|
### 2.1 Operational (Minimum Required)
|
|
|
|
The system enters "Operational" state when:
|
|
|
|
| Requirement | Description | Doctor Check |
|
|
|-------------|-------------|--------------|
|
|
| Database connected | PostgreSQL is reachable and authenticated | `check.database.connectivity` |
|
|
| Migrations applied | All startup migrations complete, no pending release migrations | `check.database.migrations.applied` |
|
|
| Core services healthy | Gateway, Router, Authority respond to health probes | `check.services.core.healthy` |
|
|
| Admin user exists | At least one admin user with `admin:*` scope | `check.auth.admin.exists` |
|
|
| Crypto profile valid | At least one signing key configured | `check.crypto.profile.valid` |
|
|
|
|
**Gating Behavior:** UI blocks access to operational features until Operational threshold met.
|
|
|
|
### 2.2 Production-Ready (Recommended)
|
|
|
|
The system reaches "Production-Ready" state when:
|
|
|
|
| Requirement | Description | Doctor Check |
|
|
|-------------|-------------|--------------|
|
|
| OIDC/LDAP configured | External identity provider integrated | `check.security.identity.configured` |
|
|
| Vault connected | At least one secrets provider | `check.integration.vault.connected` |
|
|
| SCM integrated | At least one SCM (GitHub/GitLab) | `check.integration.scm.connected` |
|
|
| Notifications configured | At least one notification channel | `check.notify.channel.configured` |
|
|
| Feed sync enabled | Vulnerability feed mirroring active | `check.feeds.sync.enabled` |
|
|
| Environment defined | At least one environment created | `check.orchestrator.environment.exists` |
|
|
| Agent registered | At least one healthy agent | `check.orchestrator.agent.healthy` |
|
|
| TLS hardened | All endpoints using TLS 1.2+ | `check.security.tls.hardened` |
|
|
|
|
---
|
|
|
|
## 3. Step Catalog
|
|
|
|
### 3.1 Core Steps
|
|
|
|
| Step ID | Name | Required | Skippable | Category |
|
|
|---------|------|----------|-----------|----------|
|
|
| `database` | Database Setup | Yes | No | Infrastructure |
|
|
| `valkey` | Valkey/Redis Setup | Yes | No | Infrastructure |
|
|
| `migrations` | Database Migrations | Yes | No | Infrastructure |
|
|
| `admin` | Admin Bootstrap | Yes | No | Security |
|
|
| `crypto` | Crypto Profile | Yes | No | Security |
|
|
|
|
### 3.2 Integration Steps
|
|
|
|
| Step ID | Name | Required | Skippable | Category |
|
|
|---------|------|----------|-----------|----------|
|
|
| `vault` | Secrets Provider | No | Yes | Integration |
|
|
| `settingsstore` | Settings Store | No | Yes | Integration |
|
|
| `scm` | Source Control | No | Yes | Integration |
|
|
| `registry` | Container Registry | No | Yes | Integration |
|
|
| `notifications` | Notification Channels | No | Yes | Integration |
|
|
| `identity` | Identity Provider (OIDC/LDAP) | No | Yes | Security |
|
|
|
|
### 3.3 Orchestration Steps
|
|
|
|
| Step ID | Name | Required | Skippable | Category |
|
|
|---------|------|----------|-----------|----------|
|
|
| `environments` | Environment Definition | No | Yes | Orchestration |
|
|
| `agents` | Agent Registration | No | Yes | Orchestration |
|
|
| `feeds` | Vulnerability Feeds | No | Yes | Data |
|
|
|
|
---
|
|
|
|
## 4. Step Specifications
|
|
|
|
### 4.1 Database Setup (`database`)
|
|
|
|
**Purpose:** Configure PostgreSQL connection and verify accessibility.
|
|
|
|
**Inputs:**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `host` | string | Yes | `localhost` | PostgreSQL host |
|
|
| `port` | number | Yes | `5432` | PostgreSQL port |
|
|
| `database` | string | Yes | `stellaops` | Database name |
|
|
| `username` | string | Yes | - | Database user |
|
|
| `password` | secret | Yes | - | Database password |
|
|
| `sslMode` | enum | No | `prefer` | SSL mode (disable, prefer, require, verify-ca, verify-full) |
|
|
| `poolSize` | number | No | `100` | Connection pool size |
|
|
|
|
**Outputs:**
|
|
- Connection string stored in settings store
|
|
- Connection verified via `SELECT 1`
|
|
- Schema creation permissions validated
|
|
|
|
**Validation:**
|
|
- TCP connectivity to host:port
|
|
- Authentication with credentials
|
|
- `CREATE SCHEMA` permission check
|
|
|
|
**Doctor Checks:**
|
|
- `check.database.connectivity`
|
|
- `check.database.permissions`
|
|
- `check.database.version` (PostgreSQL >= 16)
|
|
|
|
**Persistence:**
|
|
- Environment: `STELLAOPS_POSTGRES_CONNECTION`
|
|
- Config: `Storage:ConnectionString` in Authority options
|
|
- Encrypted storage of password via configured Vault or local keyring
|
|
|
|
---
|
|
|
|
### 4.2 Valkey/Redis Setup (`valkey`)
|
|
|
|
**Purpose:** Configure Valkey/Redis for caching, queues, and session storage.
|
|
|
|
**Inputs:**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `host` | string | Yes | `localhost` | Valkey host |
|
|
| `port` | number | Yes | `6379` | Valkey port |
|
|
| `password` | secret | No | - | Valkey password |
|
|
| `database` | number | No | `0` | Database index (0-15) |
|
|
| `useTls` | boolean | No | `false` | Enable TLS |
|
|
| `abortOnConnectFail` | boolean | No | `false` | Fail fast on connection error |
|
|
|
|
**Outputs:**
|
|
- Connection string stored in settings
|
|
- PING response verified
|
|
|
|
**Validation:**
|
|
- TCP connectivity
|
|
- AUTH if password provided
|
|
- PING response within 5 seconds
|
|
|
|
**Doctor Checks:**
|
|
- `check.services.valkey.connectivity`
|
|
- `check.services.valkey.ping`
|
|
|
|
---
|
|
|
|
### 4.3 Database Migrations (`migrations`)
|
|
|
|
**Purpose:** Apply pending database migrations across all modules.
|
|
|
|
**Inputs:**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `modules` | string[] | No | `["all"]` | Modules to migrate |
|
|
| `dryRun` | boolean | No | `false` | Preview without applying |
|
|
| `force` | boolean | No | `false` | Allow release migrations |
|
|
|
|
**Outputs:**
|
|
- List of applied migrations per module
|
|
- Schema version recorded in `schema_migrations` table
|
|
- Checksum verification results
|
|
|
|
**Validation:**
|
|
- Advisory lock acquisition
|
|
- Checksum match for already-applied migrations
|
|
- No pending release migrations (unless force=true)
|
|
|
|
**Doctor Checks:**
|
|
- `check.database.migrations.applied`
|
|
- `check.database.migrations.checksums`
|
|
- `check.database.schema.version`
|
|
|
|
---
|
|
|
|
### 4.4 Admin Bootstrap (`admin`)
|
|
|
|
**Purpose:** Create initial administrator account.
|
|
|
|
**Inputs:**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `username` | string | Yes | `admin` | Admin username |
|
|
| `email` | string | Yes | - | Admin email |
|
|
| `password` | secret | Yes | - | Admin password |
|
|
| `displayName` | string | No | - | Display name |
|
|
|
|
**Validation:**
|
|
- Password complexity (min 12 chars, mixed case, numbers, symbols)
|
|
- Email format
|
|
- Username uniqueness
|
|
|
|
**Doctor Checks:**
|
|
- `check.auth.admin.exists`
|
|
- `check.auth.password.policy`
|
|
|
|
---
|
|
|
|
### 4.5 Crypto Profile (`crypto`)
|
|
|
|
**Purpose:** Configure cryptographic signing keys for attestations.
|
|
|
|
**Inputs:**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `profileType` | enum | Yes | - | `local`, `kms`, `hsm`, `sigstore` |
|
|
| `keyAlgorithm` | enum | No | `ecdsa-p256` | Key algorithm |
|
|
| `keyId` | string | Conditional | - | KMS/HSM key identifier |
|
|
| `certificatePath` | string | Conditional | - | Path to signing certificate |
|
|
| `privateKeyPath` | string | Conditional | - | Path to private key |
|
|
|
|
**Validation:**
|
|
- Key material accessible
|
|
- Algorithm supported
|
|
- Certificate chain valid (if provided)
|
|
|
|
**Doctor Checks:**
|
|
- `check.crypto.profile.valid`
|
|
- `check.crypto.signing.test`
|
|
|
|
---
|
|
|
|
### 4.6 Vault Integration (`vault`)
|
|
|
|
**Purpose:** Configure secrets management provider.
|
|
|
|
**Multi-Connector Support:** Yes - users can add multiple vault integrations.
|
|
|
|
**Connector Options:**
|
|
|
|
| Connector | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| **HashiCorp Vault** | Yes (if detected) | KV v2 secrets engine |
|
|
| **Azure Key Vault** | Yes (if Azure env) | Azure-native secrets |
|
|
| **AWS Secrets Manager** | Yes (if AWS env) | AWS-native secrets |
|
|
| **File Provider** | Fallback | Local file-based secrets |
|
|
|
|
**Inputs (HashiCorp Vault):**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `address` | string | Yes | - | Vault server URL |
|
|
| `authMethod` | enum | Yes | `token` | token, approle, kubernetes |
|
|
| `mountPoint` | string | No | `secret` | KV mount point |
|
|
| `token` | secret | Conditional | - | Vault token |
|
|
| `roleId` | string | Conditional | - | AppRole role ID |
|
|
| `secretId` | secret | Conditional | - | AppRole secret ID |
|
|
|
|
**Default Selection Logic:**
|
|
1. If `VAULT_ADDR` env var set → HashiCorp Vault
|
|
2. If Azure IMDS available → Azure Key Vault
|
|
3. If AWS metadata available → AWS Secrets Manager
|
|
4. Otherwise → Prompt user
|
|
|
|
**Doctor Checks:**
|
|
- `check.integration.vault.connected`
|
|
- `check.integration.vault.auth`
|
|
- `check.integration.vault.secrets.access`
|
|
|
|
---
|
|
|
|
### 4.7 Settings Store Integration (`settingsstore`)
|
|
|
|
**Purpose:** Configure application settings and feature flag providers.
|
|
|
|
**Multi-Connector Support:** Yes - users can add multiple settings stores for different purposes.
|
|
|
|
**Connector Options:**
|
|
|
|
| Connector | Priority | Write | Watch | Feature Flags | Labels |
|
|
|-----------|----------|-------|-------|---------------|--------|
|
|
| **Consul KV** | P0 | Configurable | Yes | No | No |
|
|
| **etcd** | P0 | Configurable | Yes | No | No |
|
|
| **Azure App Configuration** | P1 | Read-only | Yes | Yes (native) | Yes |
|
|
| **AWS Parameter Store** | P1 | Configurable | No | No | Via path |
|
|
| **AWS AppConfig** | P2 | Read-only | Yes | Yes (native) | Yes |
|
|
| **ZooKeeper** | P2 | Configurable | Yes | No | No |
|
|
| **GCP Runtime Config** | P2 | Read-only | Yes | No | No |
|
|
|
|
**Inputs (Consul KV):**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `address` | string | Yes | - | Consul server URL |
|
|
| `token` | secret | No | - | ACL token |
|
|
| `tokenSecretRef` | string | No | - | Vault path to ACL token |
|
|
| `writeEnabled` | boolean | No | `false` | Enable write operations |
|
|
|
|
**Inputs (etcd):**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `address` | string | Conditional | - | Single endpoint URL |
|
|
| `endpoints` | string[] | Conditional | - | Multiple endpoint URLs |
|
|
| `username` | string | No | - | Authentication username |
|
|
| `password` | secret | No | - | Authentication password |
|
|
| `passwordSecretRef` | string | No | - | Vault path to password |
|
|
| `writeEnabled` | boolean | No | `false` | Enable write operations |
|
|
|
|
**Default Selection Logic:**
|
|
1. If `CONSUL_HTTP_ADDR` env var set -> Consul KV
|
|
2. If `ETCD_ENDPOINTS` env var set -> etcd
|
|
3. If Azure IMDS + App Config connection available -> Azure App Configuration
|
|
4. If AWS metadata + `/stellaops/` path exists -> AWS Parameter Store
|
|
5. Otherwise -> Prompt user
|
|
|
|
**Doctor Checks:**
|
|
- `check.integration.settingsstore.connectivity`
|
|
- `check.integration.settingsstore.auth`
|
|
- `check.integration.settingsstore.read`
|
|
- `check.integration.settingsstore.write` (if write enabled)
|
|
- `check.integration.settingsstore.latency`
|
|
|
|
---
|
|
|
|
### 4.8 SCM Integration (`scm`)
|
|
|
|
**Purpose:** Configure source control management integrations.
|
|
|
|
**Multi-Connector Support:** Yes - users can add GitHub AND GitLab simultaneously.
|
|
|
|
**Connector Options:**
|
|
|
|
| Connector | Description |
|
|
|-----------|-------------|
|
|
| **GitHub App** | GitHub.com or GHES via App installation |
|
|
| **GitLab Server** | GitLab.com or self-hosted |
|
|
| **Bitbucket** | Bitbucket Cloud or Server |
|
|
| **Gitea** | Self-hosted Gitea |
|
|
| **Azure DevOps** | Azure Repos |
|
|
|
|
**Inputs (GitHub App):**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `appId` | string | Yes | - | GitHub App ID |
|
|
| `installationId` | string | Yes | - | Installation ID |
|
|
| `privateKey` | secret | Yes | - | App private key (PEM) |
|
|
| `apiUrl` | string | No | `https://api.github.com` | API endpoint |
|
|
|
|
**Doctor Checks:**
|
|
- `check.integration.scm.github.auth`
|
|
- `check.integration.scm.github.permissions`
|
|
|
|
---
|
|
|
|
### 4.9 Notification Channels (`notifications`)
|
|
|
|
**Purpose:** Configure notification delivery channels.
|
|
|
|
**Multi-Connector Support:** Yes - multiple channels per type allowed.
|
|
|
|
**Channel Options:**
|
|
|
|
| Channel | Description |
|
|
|---------|-------------|
|
|
| **Slack** | Incoming webhook |
|
|
| **Teams** | Incoming webhook |
|
|
| **Email** | SMTP server |
|
|
| **Webhook** | Generic HTTP POST |
|
|
| **PagerDuty** | Incident alerts |
|
|
|
|
**Inputs (Slack):**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `name` | string | Yes | - | Channel display name |
|
|
| `webhookUrl` | secret | Yes | - | Slack incoming webhook URL |
|
|
| `channel` | string | No | - | Default channel override |
|
|
| `username` | string | No | `StellaOps` | Bot username |
|
|
| `iconEmoji` | string | No | `:shield:` | Bot icon |
|
|
|
|
**Doctor Checks:**
|
|
- `check.notify.channel.configured`
|
|
- `check.notify.slack.webhook`
|
|
- `check.notify.delivery.test`
|
|
|
|
---
|
|
|
|
### 4.10 Environment Definition (`environments`)
|
|
|
|
**Purpose:** Define deployment environments (dev, staging, prod).
|
|
|
|
**Inputs:**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `name` | string | Yes | - | Environment slug (lowercase) |
|
|
| `displayName` | string | Yes | - | Display name |
|
|
| `orderIndex` | number | Yes | - | Pipeline position (0=first) |
|
|
| `isProduction` | boolean | No | `false` | Production flag |
|
|
| `requiredApprovals` | number | No | `0` | Approval count |
|
|
| `requireSeparationOfDuties` | boolean | No | `false` | SoD enforcement |
|
|
| `autoPromoteFrom` | string | No | - | Auto-promote source |
|
|
|
|
**Validation:**
|
|
- Production environments require `requiredApprovals >= 1`
|
|
- `autoPromoteFrom` must reference existing environment with lower orderIndex
|
|
- Name must match `^[a-z][a-z0-9-]{1,31}$`
|
|
|
|
**Doctor Checks:**
|
|
- `check.orchestrator.environment.exists`
|
|
- `check.orchestrator.environment.valid`
|
|
|
|
---
|
|
|
|
### 4.11 Agent Registration (`agents`)
|
|
|
|
**Purpose:** Register deployment agents with the orchestrator.
|
|
|
|
**Inputs:**
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `name` | string | Yes | - | Agent name |
|
|
| `capabilities` | string[] | Yes | - | `docker`, `compose`, `ssh`, `winrm` |
|
|
| `labels` | map | No | `{}` | Agent labels for selection |
|
|
|
|
**Outputs:**
|
|
- Registration token (one-time, 24-hour expiry)
|
|
- Agent installation command
|
|
|
|
**Generated Command:**
|
|
```bash
|
|
stella-agent register --token <token> --name <name> --orchestrator-url <url>
|
|
```
|
|
|
|
**Doctor Checks:**
|
|
- `check.orchestrator.agent.registered`
|
|
- `check.orchestrator.agent.healthy`
|
|
- `check.orchestrator.agent.certificate`
|
|
|
|
---
|
|
|
|
## 5. Multi-Connector Model
|
|
|
|
### 5.1 Connector Categories
|
|
|
|
Each integration category supports multiple instances:
|
|
|
|
| Category | Max Instances | Use Case |
|
|
|----------|---------------|----------|
|
|
| **Vault** | 5 | Separate vaults per environment |
|
|
| **Settings Store** | 5 | Config from Azure App Config + feature flags from Consul |
|
|
| **SCM** | 10 | GitHub + GitLab + internal Gitea |
|
|
| **Registry** | 10 | ECR + Harbor + internal registry |
|
|
| **Notifications** | 20 | Slack per team + email + PagerDuty |
|
|
|
|
### 5.2 Default Connector Selection
|
|
|
|
The wizard suggests a default connector based on:
|
|
|
|
1. **Environment Detection:**
|
|
- `VAULT_ADDR` -> HashiCorp Vault
|
|
- `CONSUL_HTTP_ADDR` -> Consul KV
|
|
- `ETCD_ENDPOINTS` -> etcd
|
|
- Azure IMDS -> Azure Key Vault / Azure App Configuration
|
|
- AWS metadata -> AWS Secrets Manager / AWS Parameter Store
|
|
- `GITHUB_TOKEN` -> GitHub
|
|
- `GITLAB_TOKEN` -> GitLab
|
|
|
|
2. **Configuration Files:**
|
|
- Existing `etc/*.yaml` samples
|
|
- Docker Compose environment files
|
|
|
|
3. **Repository Defaults:**
|
|
- Harbor (most commonly used registry)
|
|
- Slack (most common notification)
|
|
|
|
### 5.3 Last Selected Connector Persistence
|
|
|
|
The wizard stores user preferences in the settings store:
|
|
|
|
```json
|
|
{
|
|
"setupWizard": {
|
|
"lastConnectors": {
|
|
"vault": "hashicorp-vault",
|
|
"settingsstore": "consul-kv",
|
|
"scm": "github-app",
|
|
"registry": "harbor",
|
|
"notifications": "slack"
|
|
},
|
|
"completedAt": "2026-01-13T10:30:00Z",
|
|
"skippedSteps": ["identity", "feeds"]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Resume/Re-run Behavior
|
|
|
|
### 6.1 Idempotency Requirements
|
|
|
|
All steps must be safe to re-run:
|
|
|
|
| Step | Re-run Behavior |
|
|
|------|-----------------|
|
|
| `database` | Verify connection; no changes if already configured |
|
|
| `migrations` | Skip already-applied; apply only pending |
|
|
| `admin` | Skip if admin exists; offer password reset |
|
|
| `vault` | Add new integration; don't duplicate |
|
|
| `settingsstore` | Add new integration; don't duplicate |
|
|
| `scm` | Add new integration; don't duplicate |
|
|
|
|
### 6.2 Configuration Pane Access
|
|
|
|
After initial setup, the wizard is available from:
|
|
- **CLI:** `stella setup --reconfigure`
|
|
- **UI:** Settings > Configuration Wizard
|
|
|
|
Pre-populated with:
|
|
- Current configuration values
|
|
- Last selected connector per category
|
|
- Health status from Doctor checks
|
|
|
|
---
|
|
|
|
## 7. Security Posture
|
|
|
|
### 7.1 Secret Storage
|
|
|
|
| Secret Type | Storage Location |
|
|
|-------------|------------------|
|
|
| Database password | Vault (if configured) or local keyring |
|
|
| Valkey password | Vault (if configured) or local keyring |
|
|
| API tokens | Vault integration |
|
|
| Private keys | File system with 0600 permissions |
|
|
|
|
### 7.2 Redaction Rules
|
|
|
|
The wizard must never display:
|
|
- Full passwords
|
|
- API tokens
|
|
- Private key contents
|
|
- Vault tokens
|
|
|
|
Display format for sensitive fields:
|
|
- Masked: `********`
|
|
- Partial: `ghp_****1234` (first 4 + last 4)
|
|
|
|
### 7.3 Audit Trail
|
|
|
|
All wizard actions are logged to:
|
|
- Timeline service with HLC timestamps
|
|
- Authority audit log for admin operations
|
|
- Doctor run history for check results
|
|
|
|
---
|
|
|
|
## 8. Error Handling
|
|
|
|
### 8.1 Validation Errors
|
|
|
|
| Error Type | Behavior |
|
|
|------------|----------|
|
|
| Invalid input | Inline error message; prevent progression |
|
|
| Connection failure | Show error; offer retry with different params |
|
|
| Permission denied | Show required permissions; offer skip (if skippable) |
|
|
| Timeout | Show timeout; offer retry with increased timeout |
|
|
|
|
### 8.2 Partial Completion
|
|
|
|
If wizard exits mid-flow:
|
|
- Completed steps are persisted
|
|
- Resume shows current state
|
|
- Doctor checks identify incomplete setup
|
|
|
|
---
|
|
|
|
## 9. Exit Criteria
|
|
|
|
### 9.1 Successful Completion
|
|
|
|
The wizard completes successfully when:
|
|
- All required steps pass Doctor checks
|
|
- User has explicitly skipped or completed all steps
|
|
- Operational threshold is met
|
|
|
|
### 9.2 Completion Actions
|
|
|
|
On completion:
|
|
1. Run full Doctor diagnostic
|
|
2. Generate setup report (Markdown)
|
|
3. Emit `setup.completed` timeline event
|
|
4. Clear first-run flag
|
|
5. Redirect to dashboard (UI) or exit with success (CLI)
|