audit, advisories and doctors/setup work

2026-01-13 18:53:39 +02:00
parent 9ca7cb183e
commit d7be6ba34b
811 changed files with 54242 additions and 4056 deletions
--- a/docs/setup/setup-wizard-inventory.md
+++ b/docs/setup/setup-wizard-inventory.md
@@ -0,0 +1,458 @@
+# Setup Wizard - Repository Inventory
+
+This document captures the current state of setup-related components in the Stella Ops codebase, providing evidence for the Setup Wizard design.
+
+## 1. CLI Architecture
+
+### 1.1 Framework & Entry Points
+
+| Component | Path | Description |
+|-----------|------|-------------|
+| **CLI Entry** | `src/Cli/StellaOps.Cli/Program.cs` | Main entry point using System.CommandLine |
+| **Command Factory** | `src/Cli/StellaOps.Cli/Commands/CommandFactory.cs` | Central command registration (53+ command groups) |
+| **Bootstrapper** | `src/Cli/StellaOps.Cli/Configuration/CliBootstrapper.cs` | Configuration loading and DI setup |
+| **Options** | `src/Cli/StellaOps.Cli/Configuration/StellaOpsCliOptions.cs` | CLI configuration POCOs |
+| **Profile Manager** | `src/Cli/StellaOps.Cli/Configuration/CliProfile.cs` | Multi-profile support |
+
+### 1.2 Existing Admin Commands
+
+**File:** `src/Cli/StellaOps.Cli/Commands/Admin/AdminCommandGroup.cs`
+
+Current `stella admin` subcommands:
+- `admin policy export|import|validate|list` - Policy management
+- `admin users list|add|revoke|update` - User management
+- `admin feeds list|status|refresh|history` - Feed management
+- `admin system status|info` - System health and info
+
+### 1.3 Doctor Commands
+
+**File:** `src/Cli/StellaOps.Cli/Commands/DoctorCommandGroup.cs`
+
+```bash
+stella doctor run [--mode quick|normal|full] [--category <cat>] [--format text|json|markdown]
+stella doctor list [--category <cat>] [--verbose]
+stella doctor export --output <path>.zip [--include-logs]
+```
+
+### 1.4 Configuration System
+
+**Priority Resolution (CliBootstrapper.cs):**
+1. Command-line arguments (highest)
+2. Environment variables (`STELLAOPS_*` prefix)
+3. Configuration files (`appsettings.json`, `appsettings.yaml`)
+4. Code defaults (lowest)
+
+**Key Environment Variables:**
+- `STELLAOPS_BACKEND_URL` - Backend API URL
+- `STELLAOPS_AUTHORITY_URL` - Authority service URL
+- `STELLAOPS_POSTGRES_CONNECTION` - Database connection
+- `STELLAOPS_OFFLINE_KITS_DIRECTORY` - Offline kit path
+
+---
+
+## 2. Doctor System (Diagnostic Framework)
+
+### 2.1 Core Engine
+
+| Component | Path |
+|-----------|------|
+| **Engine** | `src/__Libraries/StellaOps.Doctor/Engine/DoctorEngine.cs` |
+| **Registry** | `src/__Libraries/StellaOps.Doctor/Engine/CheckRegistry.cs` |
+| **Executor** | `src/__Libraries/StellaOps.Doctor/Engine/CheckExecutor.cs` |
+| **Models** | `src/__Libraries/StellaOps.Doctor/Models/` |
+
+### 2.2 Plugin System (9 Plugins, 48+ Checks)
+
+| Plugin | Path | Category | Checks |
+|--------|------|----------|--------|
+| **Core** | `StellaOps.Doctor.Plugins.Core` | Core | 9 checks (config, disk, memory, crypto) |
+| **Database** | `StellaOps.Doctor.Plugins.Database` | Database | 8 checks (connectivity, migrations, schema) |
+| **ServiceGraph** | `StellaOps.Doctor.Plugins.ServiceGraph` | ServiceGraph | 6 checks (gateway, Valkey) |
+| **Security** | `StellaOps.Doctor.Plugins.Security` | Security | 9 checks (OIDC, TLS, Vault) |
+| **Integration** | `StellaOps.Doctor.Plugins.Integration` | Integration | 8+ checks (GitHub, GitLab, registries) |
+| **Observability** | `StellaOps.Doctor.Plugins.Observability` | Observability | 4 checks (OTLP, metrics) |
+| **Cryptography** | `StellaOps.Doctor.Plugins.Cryptography` | Cryptography | 8+ checks (FIPS, eIDAS, HSM) |
+| **Docker** | `StellaOps.Doctor.Plugins.Docker` | Docker | 5 checks (daemon, network) |
+| **AI** | `StellaOps.Doctor.Plugins.AI` | AI | 4+ checks (LLM providers) |
+| **Notify** | `StellaOps.Doctor.Plugin.Notify` | Notify | 5 checks (email, Slack, webhooks) |
+
+### 2.3 Doctor Web Service
+
+| Component | Path |
+|-----------|------|
+| **Web Service** | `src/Doctor/StellaOps.Doctor.WebService/` |
+| **Endpoints** | `src/Doctor/StellaOps.Doctor.WebService/Endpoints/DoctorEndpoints.cs` |
+| **Angular UI** | `src/Web/StellaOps.Web/src/app/features/doctor/` |
+
+**REST API:**
+- `POST /api/v1/doctor/run` - Start diagnostic run
+- `GET /api/v1/doctor/run/{runId}` - Get run results
+- `GET /api/v1/doctor/checks` - List available checks
+- `WebSocket /api/v1/doctor/stream` - Real-time streaming
+
+### 2.4 Check ID Convention
+
+```
+check.{category}.{subcategory}.{specific}
+```
+
+Examples:
+- `check.config.required`
+- `check.database.migrations.pending`
+- `check.integration.scm.github.auth`
+- `check.services.valkey.connectivity`
+
+---
+
+## 3. Database & Migrations
+
+### 3.1 Migration Framework
+
+| Component | Path |
+|-----------|------|
+| **Runner** | `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/MigrationRunner.cs` |
+| **Startup Host** | `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/StartupMigrationHost.cs` |
+| **Categories** | `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/MigrationCategory.cs` |
+| **CLI Service** | `src/Cli/StellaOps.Cli/Services/MigrationCommandService.cs` |
+
+### 3.2 Migration Categories
+
+| Category | Prefix | Execution | Purpose |
+|----------|--------|-----------|---------|
+| **Startup** | 001-099 | Automatic at boot | Schema creation (idempotent) |
+| **Release** | 100-199 | Manual CLI | Breaking changes (blocks boot if pending) |
+| **Seed** | S001-S999 | Automatic at boot | Initial data (idempotent) |
+| **Data** | DM001-DM999 | Background jobs | Data migrations |
+
+### 3.3 Schema Isolation (Per-Module)
+
+| Module | Schema | Migration Path |
+|--------|--------|----------------|
+| Authority | `authority` | `src/Authority/__Libraries/StellaOps.Authority.Persistence/Migrations/` |
+| Concelier | `vuln` | `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Migrations/` |
+| Scheduler | `scheduler` | `src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Migrations/` |
+| Notify | `notify` | `src/Notify/__Libraries/StellaOps.Notify.Persistence/Migrations/` |
+| Scanner | `scanner` | `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/` |
+| Attestor | `attestor` | `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/Migrations/` |
+| Policy | `policy` | `src/Policy/__Libraries/StellaOps.Policy.Persistence/Migrations/` |
+| ReleaseOrchestrator | `release` | `src/ReleaseOrchestrator/__Libraries/.../Persistence/Migrations/` |
+
+### 3.4 Existing CLI Commands
+
+```bash
+stella migrations-run --module <Module> --category <Category> [--dry-run] [--force]
+```
+
+---
+
+## 4. Redis/Valkey Infrastructure
+
+### 4.1 Connection Configuration
+
+| Component | Path |
+|-----------|------|
+| **Primary Factory** | `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyConnectionFactory.cs` |
+| **Options** | `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/Options/ValkeyTransportOptions.cs` |
+| **Transport Plugin** | `src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyTransportPlugin.cs` |
+
+### 4.2 Usage Patterns
+
+| Usage | Component | Purpose |
+|-------|-----------|---------|
+| **Message Queues** | `ValkeyMessageQueue` | Redis Streams with consumer groups |
+| **Distributed Cache** | `ValkeyCacheStore` | TTL-based caching |
+| **Rate Limiting** | `ValkeyRateLimitStore` | Token bucket algorithm |
+| **Idempotency** | `ValkeyIdempotencyStore` | Duplicate prevention |
+| **DPoP Nonces** | `RedisDpopNonceStore` | Auth token security |
+
+### 4.3 Health Checks
+
+**File:** `src/__Libraries/StellaOps.Doctor.Plugins.ServiceGraph/Checks/ValkeyConnectivityCheck.cs`
+
+Configuration sources checked:
+- `Valkey:ConnectionString`
+- `Redis:ConnectionString`
+- `ConnectionStrings:Valkey`
+- `ConnectionStrings:Redis`
+
+---
+
+## 5. Integrations System
+
+### 5.1 Core Architecture
+
+| Component | Path |
+|-----------|------|
+| **Web Service** | `src/Integrations/StellaOps.Integrations.WebService/` |
+| **Core Models** | `src/Integrations/__Libraries/StellaOps.Integrations.Core/` |
+| **Contracts** | `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/` |
+| **Persistence** | `src/Integrations/__Libraries/StellaOps.Integrations.Persistence/` |
+
+### 5.2 Integration Types
+
+**File:** `src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationEnums.cs`
+
+| Type | Range | Examples |
+|------|-------|----------|
+| **Registry** | 100-109 | Harbor, ECR, GCR, ACR, Docker Hub, Quay |
+| **SCM** | 200-204 | GitHub App, GitLab Server, Bitbucket, Gitea |
+| **CI/CD** | 300-306 | GitHub Actions, GitLab CI, Jenkins, Argo |
+| **RepoSource** | 400-405 | npm, PyPI, Maven, NuGet, Crates.io |
+| **RuntimeHost** | 500-502 | eBPF Agent, ETW Agent |
+| **FeedMirror** | 600-602 | StellaOps Mirror, NVD, OSV |
+
+### 5.3 Plugin Contract
+
+**File:** `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs`
+
+```csharp
+public interface IIntegrationConnectorPlugin : IAvailabilityPlugin
+{
+    IntegrationType Type { get; }
+    IntegrationProvider Provider { get; }
+    Task<TestConnectionResult> TestConnectionAsync(IntegrationConfig config, CancellationToken ct);
+    Task<HealthCheckResult> CheckHealthAsync(IntegrationConfig config, CancellationToken ct);
+}
+```
+
+### 5.4 Existing Plugins
+
+| Plugin | Path |
+|--------|------|
+| **GitHub App** | `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/` |
+| **Harbor** | `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.Harbor/` |
+| **InMemory** | `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.InMemory/` |
+
+---
+
+## 6. Notification System
+
+### 6.1 Core Components
+
+| Component | Path |
+|-----------|------|
+| **Web Service** | `src/Notify/StellaOps.Notify.WebService/` |
+| **Engine** | `src/Notify/__Libraries/StellaOps.Notify.Engine/` |
+| **Models** | `src/Notify/__Libraries/StellaOps.Notify.Models/` |
+| **Queue** | `src/Notify/__Libraries/StellaOps.Notify.Queue/` |
+
+### 6.2 Channel Types
+
+**File:** `src/Notify/__Libraries/StellaOps.Notify.Models/NotifyChannel.cs`
+
+- **Slack** - Incoming webhooks
+- **Teams** - Incoming webhooks
+- **Email** - SMTP
+- **Webhook** - Generic HTTP POST
+- **PagerDuty** / **OpsGenie** - Incident management
+- **InApp** - In-application inbox
+
+### 6.3 Channel Configuration
+
+```csharp
+public sealed record NotifyChannelConfig
+{
+    public string SecretRef { get; }      // authref:// URI
+    public string? Target { get; }        // Channel/email list
+    public string? Endpoint { get; }      // Webhook URL
+    public ImmutableDictionary<string, string> Properties { get; }
+}
+```
+
+---
+
+## 7. Vault/Secrets System
+
+### 7.1 Vault Connectors
+
+| Connector | Path |
+|-----------|------|
+| **HashiCorp Vault** | `src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/HashiCorpVaultConnector.cs` |
+| **Azure Key Vault** | `src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/AzureKeyVaultConnector.cs` |
+| **AWS Secrets Manager** | `src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/AwsSecretsManagerConnector.cs` |
+
+### 7.2 Secret Resolution
+
+**File:** `src/ReleaseOrchestrator/__Libraries/.../Plugin/Integration/ITenantSecretResolver.cs`
+
+```csharp
+public interface ITenantSecretResolver : ISecretResolver
+{
+    ITenantSecretResolver ForTenant(Guid tenantId);
+    Task<string?> ResolveFromVaultAsync(Guid integrationId, string secretPath, CancellationToken ct);
+}
+```
+
+### 7.3 Credential Provider Schemes
+
+**File:** `src/ReleaseOrchestrator/__Agents/StellaOps.Agent.Core/Credentials/CredentialResolver.cs`
+
+- `env://VAR_NAME` - Environment variable
+- `file:///path/to/secret` - File system
+- `vault://integration-id/path` - Vault lookup
+
+---
+
+## 8. Environment & Agent System
+
+### 8.1 Environment Model
+
+**File:** `src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Environment/Models/Environment.cs`
+
+```csharp
+public sealed record Environment
+{
+    public Guid Id { get; init; }
+    public Guid TenantId { get; init; }
+    public string Name { get; set; }           // "dev", "staging", "prod"
+    public string DisplayName { get; set; }
+    public int OrderIndex { get; init; }       // Pipeline order
+    public bool IsProduction { get; init; }
+    public int RequiredApprovals { get; set; }
+    public bool RequireSeparationOfDuties { get; set; }
+    public Guid? AutoPromoteFrom { get; set; }
+}
+```
+
+### 8.2 Target Model (Deployment Target)
+
+**File:** `src/ReleaseOrchestrator/__Libraries/.../Environment/Models/Target.cs`
+
+| Target Type | Description |
+|-------------|-------------|
+| **DockerHost** | Docker Engine |
+| **ComposeHost** | Docker Compose project |
+| **EcsService** | AWS ECS service |
+| **NomadJob** | HashiCorp Nomad job |
+
+### 8.3 Agent Model
+
+**File:** `src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Agent/Models/Agent.cs`
+
+```csharp
+public sealed record Agent
+{
+    public Guid Id { get; init; }
+    public string Name { get; init; }
+    public AgentStatus Status { get; set; }    // Pending, Active, Inactive, Stale, Revoked
+    public AgentCapability[] Capabilities { get; init; }  // Docker, Compose, Ssh, WinRm
+    public string? CertificateThumbprint { get; set; }    // mTLS
+    public DateTimeOffset? LastHeartbeatAt { get; set; }
+}
+```
+
+### 8.4 Agent Registration
+
+**File:** `src/ReleaseOrchestrator/__Libraries/.../Agent/Registration/RegistrationTokenService.cs`
+
+- One-time tokens with 24-hour expiry
+- mTLS certificate issuance on registration
+- Heartbeat monitoring (30-second intervals, 90-second stale timeout)
+
+---
+
+## 9. Existing Onboarding System
+
+### 9.1 Platform Onboarding Service
+
+**File:** `src/Platform/StellaOps.Platform.WebService/Services/PlatformOnboardingService.cs`
+
+**Default Steps:**
+1. `connect-scanner`
+2. `configure-policy`
+3. `first-scan`
+4. `review-findings`
+5. `invite-team`
+
+**Endpoints:**
+- `GET /api/v1/platform/onboarding/status`
+- `POST /api/v1/platform/onboarding/complete/{step}`
+- `POST /api/v1/platform/onboarding/skip`
+
+### 9.2 Quickstart Documentation
+
+| Document | Path |
+|----------|------|
+| **Quickstart** | `docs/quickstart.md` |
+| **CLI Quickstart** | `docs/CONCELIER_CLI_QUICKSTART.md` |
+| **Install Guide** | `docs/INSTALL_GUIDE.md` |
+| **Developer Onboarding** | `docs/DEVELOPER_ONBOARDING.md` |
+
+---
+
+## 10. UI Architecture
+
+### 10.1 Angular Application
+
+| Component | Path |
+|-----------|------|
+| **Root** | `src/Web/StellaOps.Web/src/app/app.component.ts` |
+| **Routes** | `src/Web/StellaOps.Web/src/app/app.routes.ts` |
+| **Config** | `src/Web/StellaOps.Web/src/app/app.config.ts` |
+
+### 10.2 Existing Settings Pages
+
+| Page | Path |
+|------|------|
+| **AI Preferences** | `src/Web/StellaOps.Web/src/app/features/settings/ai-preferences.component.ts` |
+| **Environment Settings** | `src/Web/StellaOps.Web/src/app/features/release-orchestrator/environments/components/environment-settings/` |
+| **Trivy DB Settings** | `src/Web/StellaOps.Web/src/app/features/trivy-db-settings/` |
+
+### 10.3 Wizard Reference Implementation
+
+**SBOM Source Wizard** (6-step multi-form wizard):
+
+**File:** `src/Web/StellaOps.Web/src/app/features/sbom-sources/components/source-wizard/source-wizard.component.ts`
+
+Features:
+- Signal-based state management
+- Step-by-step validation
+- Connection testing
+- Multi-form with conditional rendering
+- TypeScript 1204 lines
+
+---
+
+## 11. Configuration Samples
+
+| Sample | Path |
+|--------|------|
+| **Concelier** | `etc/concelier.yaml.sample` |
+| **Authority** | `etc/authority.yaml.sample` |
+| **Docker Compose** | `devops/compose/dev.env.example` |
+| **Air-gap** | `devops/compose/airgap.env.example` |
+
+---
+
+## 12. Gaps Identified
+
+### 12.1 Missing Components
+
+| Gap | Description |
+|-----|-------------|
+| **`stella setup` command** | No dedicated interactive setup command exists |
+| **First-run detection** | No blocking wizard on first launch |
+| **Wizard UI entry** | No configuration wizard in Angular UI |
+| **Admin bootstrap** | Admin creation via env vars only, not interactive |
+| **Integration wizard** | No guided multi-connector setup |
+
+### 12.2 Partial Implementations
+
+| Component | Current State | Gap |
+|-----------|---------------|-----|
+| **Onboarding Service** | In-memory, 5-step user flow | No infrastructure setup steps |
+| **Doctor checks** | 48+ checks exist | No wizard integration for fix commands |
+| **Migrations** | Automatic at startup | No interactive verification step |
+| **Integrations** | Plugin architecture exists | No default suggestion logic |
+
+---
+
+## 13. Key Architectural Patterns to Follow
+
+1. **System.CommandLine** for CLI commands
+2. **Signal-based state** in Angular components
+3. **IOptions<T> with validation** for configuration
+4. **Plugin contracts** for extensibility
+5. **Doctor checks** for health validation
+6. **ITenantSecretResolver** for secret access
+7. **HLC timestamps** for audit ordering