stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Update documentation for 75-source catalog and mirror management

Browse Source 
connectors.md: categorized index of all 75 sources across 14 categories
with descriptions, auth requirements, priorities, regions, and status.
FSTEC BDU, NKCKI, and Kaspersky ICS promoted from beta to stable.

architecture.md: updated source families (75 sources, 14 categories),
added mirror domain management API (12 endpoints) to REST APIs section.

mirrors.md: added MirrorExportScheduler docs, multi-value filter support
(sourceCategory/sourceTag shorthands), mirror config UI sections (wizard,
dashboard, catalog integration).

docker.md: added section 7 with mirror env var reference (11 vars),
domain config via env vars, filter shorthand documentation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
master
2026-03-15 14:34:49 +02:00
parent 5291b6934c
commit 254d8b9cfc
5 changed files with 437 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
docs/operations/deployment/docker.md
View File

@@ -1,17 +1,17 @@
# StellaOps Console — Docker Install Recipes
# StellaOps Console -- Docker Install Recipes
> **Audience:** Deployment Guild, Console Guild, platform operators.
> **Scope:** Acquire the `stellaops/web-ui` image, run it with Compose or Helm, mirror it for air‑gapped environments, and keep parity with CLI workflows.
> **Audience:** Deployment Guild, Console Guild, platform operators.
> **Scope:** Acquire the `stellaops/web-ui` image, run it with Compose or Helm, mirror it for air-gapped environments, and keep parity with CLI workflows.
This guide focuses on the new **StellaOps Console** container. Start with the general [Installation Guide](../INSTALL_GUIDE.md) for shared prerequisites (Docker, registry access, TLS) and use the steps below to layer in the console.
---
## 1 · Release artefacts
## 1 - Release artefacts
| Artefact | Source | Verification |
|----------|--------|--------------|
| Console image | `registry.stella-ops.org/stellaops/web-ui@sha256:<digest>` | Listed in `deploy/releases/<channel>.yaml` (`yq '.services[] | select(.name=="web-ui") | .image'`). Signed with Cosign (`cosign verify --key https://stella-ops.org/keys/cosign.pub …`). |
| Console image | `registry.stella-ops.org/stellaops/web-ui@sha256:<digest>` | Listed in `deploy/releases/<channel>.yaml` (`yq '.services[] | select(.name=="web-ui") | .image'`). Signed with Cosign (`cosign verify --key https://stella-ops.org/keys/cosign.pub ...`). |
| Compose bundles | `devops/compose/docker-compose.{dev,stage,prod,airgap}.yaml` | Each profile already includes a `web-ui` service pinned to the release digest. Run `docker compose --env-file <env> -f docker-compose.<profile>.yaml config` to confirm the digest matches the manifest. |
| Helm values | `devops/helm/stellaops/values-*.yaml` (`services.web-ui`) | CI lints the chart; use `helm template` to confirm the rendered Deployment/Service carry the expected digest and env vars. |
| Offline artefact (preview) | Generated via `oras copy registry.stella-ops.org/stellaops/web-ui@sha256:<digest> oci-archive:stellaops-web-ui-<channel>.tar` | Record SHA-256 in the downloads manifest (`DOWNLOADS-CONSOLE-23-001`) and sign with Cosign before shipping in the Offline Kit. |
@@ -20,7 +20,7 @@ This guide focuses on the new **StellaOps Console** container. Start with the ge
---
## 2 · Compose quickstart (connected host)
## 2 - Compose quickstart (connected host)
1. **Prepare workspace**
@@ -29,14 +29,14 @@ This guide focuses on the new **StellaOps Console** container. Start with the ge
cp /path/to/repo/devops/compose/env/dev.env.example .env
```
2. **Add console configuration** – append the following to `.env` (adjust per environment):
2. **Add console configuration** -- append the following to `.env` (adjust per environment):
```bash
CONSOLE_PUBLIC_BASE_URL=https://console.dev.stella-ops.local
CONSOLE_GATEWAY_BASE_URL=https://api.dev.stella-ops.local
AUTHORITY_ISSUER=https://authority.dev.stella-ops.local
AUTHORITY_CLIENT_ID=console-ui
AUTHORITY_SCOPES="ui.read ui.admin orch:operate findings:read advisory:read vex:read aoc:verify"
AUTHORITY_SCOPES="ui.read ui.admin orch:operate findings:read advisory:read vex:read aoc:verify"
AUTHORITY_DPOP_ENABLED=true
```
@@ -81,7 +81,7 @@ AUTHORITY_SCOPES="ui.read ui.admin orch:operate findings:read advisory:read vex:
---
## 3 · Helm deployment (cluster)
## 3 - Helm deployment (cluster)
1. **Create an overlay** (example `console-values.yaml`):
@@ -99,7 +99,7 @@ AUTHORITY_SCOPES="ui.read ui.admin orch:operate findings:read advisory:read vex:
CONSOLE_GATEWAY_BASE_URL: "https://api.dev.stella-ops.local"
AUTHORITY_ISSUER: "https://authority.dev.stella-ops.local"
AUTHORITY_CLIENT_ID: "console-ui"
AUTHORITY_SCOPES: "ui.read ui.admin orch:operate findings:read advisory:read vex:read aoc:verify"
AUTHORITY_SCOPES: "ui.read ui.admin orch:operate findings:read advisory:read vex:read aoc:verify"
AUTHORITY_DPOP_ENABLED: "true"
CONSOLE_FEATURE_FLAGS: "runs,downloads,policies"
CONSOLE_METRICS_ENABLED: "true"
@@ -130,7 +130,7 @@ AUTHORITY_SCOPES: "ui.read ui.admin orch:operate findings:read advisory:read vex
---
## 4 · Offline packaging
## 4 - Offline packaging
1. **Mirror the image to an OCI archive**
@@ -167,11 +167,11 @@ AUTHORITY_SCOPES: "ui.read ui.admin orch:operate findings:read advisory:read vex
mv downloads/manifest.json.tmp downloads/manifest.json
```
Re-run `stella offline kit import downloads/manifest.json` to validate signatures inside the air‑gapped environment.
Re-run `stella offline kit import downloads/manifest.json` to validate signatures inside the air-gapped environment.
---
## 5 · CLI parity
## 5 - CLI parity
Console operations map directly to scriptable workflows:
@@ -186,27 +186,79 @@ Track progress for the CLI commands via `DOCS-CONSOLE-23-014` (CLI vs UI parity
---
## 6 · Compliance checklist
## 6 - Compliance checklist
- [ ] Image digest validated against the current release manifest.
- [ ] Compose/Helm deployments verified with `docker compose config` / `helm template`.
- [ ] Authority issuer, scopes, and DPoP settings documented and applied.
- [ ] Offline archive mirrored, signed, and recorded in the downloads manifest.
- [ ] CLI parity notes linked to the upcoming `docs/cli-vs-ui-parity.md` matrix.
- [ ] References cross-checked with `docs/deploy/console.md` and `docs/security/console-security.md`.
- [ ] Image digest validated against the current release manifest.
- [ ] Compose/Helm deployments verified with `docker compose config` / `helm template`.
- [ ] Authority issuer, scopes, and DPoP settings documented and applied.
- [ ] Offline archive mirrored, signed, and recorded in the downloads manifest.
- [ ] CLI parity notes linked to the upcoming `docs/cli-vs-ui-parity.md` matrix.
- [ ] References cross-checked with `docs/deploy/console.md` and `docs/security/console-security.md`.
- [ ] Health checks documented for connected and air-gapped installs.
---
## 7 · References
## 7 - Mirror distribution configuration
- `deploy/releases/<channel>.yaml` – Release manifest (digests, SBOM metadata).
- `devops/compose/README.md` – Compose profile overview.
- `devops/helm/stellaops/values-*.yaml` – Helm defaults per environment.
- `/docs/deploy/console.md` – Detailed environment variables, CSP, health checks.
- `/docs/security/console-security.md` – Auth flows, scopes, DPoP, monitoring.
- `docs/UI_GUIDE.md` – Console workflows and offline posture.
The Excititor service (advisory VEX export engine) supports mirror distribution for syncing advisory data to downstream environments and air-gapped deployments. Mirror configuration is applied via environment variables or config file sections under `Excititor:Mirror`.
### Environment variables
| Variable | Default | Description |
|----------|---------|-------------|
| `Excititor__Mirror__Enabled` | `true` | Global enable flag for mirror distribution surfaces and bundle generation. |
| `Excititor__Mirror__OutputRoot` | (artifact store default) | Filesystem root where mirror artefacts are written. |
| `Excititor__Mirror__DirectoryName` | `mirror` | Subdirectory under OutputRoot for mirror artifacts. |
| `Excititor__Mirror__TargetRepository` | -- | Human-readable hint for downstream mirrors (e.g., `s3://mirror/excititor`). |
| `Excititor__Mirror__RefreshIntervalMinutes` | `60` | How often the `MirrorExportScheduler` checks for stale bundles and regenerates them. Minimum 1 minute. |
| `Excititor__Mirror__AutoRefreshEnabled` | `true` | Set to `false` to disable the background scheduler. Required for air-gap deployments where bundles are imported rather than generated. |
| `Excititor__Mirror__Signing__Enabled` | `false` | Enable detached JWS signing for mirror bundle payloads. |
| `Excititor__Mirror__Signing__Algorithm` | `ES256` | Signing algorithm identifier. |
| `Excititor__Mirror__Signing__KeyId` | -- | Signing key identifier resolved via the crypto provider registry. Required when signing is enabled. |
| `Excititor__Mirror__Signing__Provider` | -- | Optional provider hint for key resolution. |
| `Excititor__Mirror__Signing__KeyPath` | -- | Optional PEM file path for key seeding. |
### Domain configuration via env vars
Mirror domains can be configured through structured env vars (array indexing):
```bash
Excititor__Mirror__Domains__0__Id=primary
Excititor__Mirror__Domains__0__DisplayName=Primary Mirror
Excititor__Mirror__Domains__0__RequireAuthentication=false
Excititor__Mirror__Domains__0__MaxIndexRequestsPerHour=600
Excititor__Mirror__Domains__0__MaxDownloadRequestsPerHour=1200
Excititor__Mirror__Domains__0__Exports__0__Key=all-advisories
Excititor__Mirror__Domains__0__Exports__0__Format=json
Excititor__Mirror__Domains__0__Exports__0__Filters__sourceCategory=Distribution
```
Alternatively, domains can be managed through the Mirror Domain Management API (`/api/v1/mirror/domains`) or the Console UI wizard (Advisory & VEX Sources > Mirror). Database-configured domains take precedence over env-var domains when both define the same domain ID.
### Filter shorthands for exports
Export filters support category and tag shorthands that resolve to source IDs at export time:
- `sourceCategory=Distribution` -- resolves to all distribution sources (Debian, Ubuntu, Alpine, etc.)
- `sourceCategory=Exploit,Container,Ics` -- comma-separated categories (OR semantics)
- `sourceTag=linux` -- resolves to all sources tagged `linux`
- `sourceVendor=debian,ubuntu,alpine` -- explicit comma-separated source IDs
See `docs/modules/excititor/mirrors.md` for the full mirror architecture documentation.
---
*Last updated: 2025-10-28 (Sprint 23).*
## 8 - References
- `deploy/releases/<channel>.yaml` -- Release manifest (digests, SBOM metadata).
- `devops/compose/README.md` -- Compose profile overview.
- `devops/helm/stellaops/values-*.yaml` -- Helm defaults per environment.
- `/docs/deploy/console.md` -- Detailed environment variables, CSP, health checks.
- `/docs/security/console-security.md` -- Auth flows, scopes, DPoP, monitoring.
- `docs/UI_GUIDE.md` -- Console workflows and offline posture.
- `docs/modules/excititor/mirrors.md` -- Mirror distribution architecture and configuration.
- `docs/modules/concelier/connectors.md` -- Full connector index (75 sources, 14 categories).
---
*Last updated: 2026-03-15 (Sprint 007).*