180 lines
8.2 KiB
Markdown
Executable File
180 lines
8.2 KiB
Markdown
Executable File
# Console (Web UI) Guide
|
|
|
|
The StellaOps Console is the operator-facing web UI. It is built for fast triage and auditability: decisions link back to concrete evidence, and workflows continue to work in air-gapped deployments via Offline Kit snapshots.
|
|
|
|
This is a usage guide (what the Console does and how to operate it). For UI implementation architecture, see `docs/modules/ui/architecture.md`.
|
|
|
|
## Scope
|
|
|
|
- Console workspaces and what each is for
|
|
- Common operator workflows (triage, evidence review, exports)
|
|
- Offline/air-gap posture and what to expect in the UI
|
|
- Links to deeper module documentation
|
|
|
|
Out of scope: API shapes, schema details, and UI component implementation.
|
|
|
|
## Core Concepts
|
|
|
|
- **Tenant context:** most views are tenant-scoped; switching tenants changes what evidence you see and what actions you can take.
|
|
- **Evidence-linked decisions:** verdicts (ship/block/needs-exception) should link to the SBOM facts, advisory/VEX observations, reachability proofs, and policy explanations that justify them.
|
|
- **Effective VEX:** the platform computes an effective status using issuer trust and policy rules, without rewriting upstream VEX (see `docs/VEX_CONSENSUS_GUIDE.md`).
|
|
- **Snapshots and staleness:** offline sites operate on snapshots; the Console should surface snapshot identity and freshness rather than hide it.
|
|
|
|
## Workspaces (Navigation)
|
|
|
|
The Console is organized into workspaces. Names vary slightly by build, but the intent is stable:
|
|
|
|
- **Dashboard:** fleet status, feed/VEX age, queue depth, and policy posture.
|
|
- **Scans / SBOM:** scan history and scan detail; SBOM viewing and export.
|
|
- **Findings / Triage:** the vulnerability triage surface (case view + evidence rail).
|
|
- **Advisories & VEX:** provider status, conflicts, provenance, and issuer trust.
|
|
- **Policies:** policy packs, previews, promotion workflow, and waiver/exception flows.
|
|
- **Runs / Scheduler:** background jobs, re-evaluation, and reachability/delta work.
|
|
- **Downloads / Offline:** Offline Kit and signed artifact distribution and mirroring.
|
|
- **Admin:** tenants, roles/scopes, clients, quotas, and operational settings.
|
|
|
|
## Common Operator Workflows
|
|
|
|
### Triage a Finding
|
|
|
|
1. Open **Findings** and filter to the tenant/environment you care about.
|
|
2. Open a finding to review:
|
|
- Verdict + "why" summary
|
|
- Effective VEX status and issuer provenance
|
|
- Reachability/impact signals (when available)
|
|
- Policy explanation trace and the gate that produced the verdict
|
|
3. Record a triage action (assign/comment/ack/mute/exception request) with justification.
|
|
4. Export an evidence bundle when review, escalation, or offline verification is required.
|
|
|
|
See `docs/VULNERABILITY_EXPLORER_GUIDE.md` for the conceptual model and determinism requirements.
|
|
|
|
### Review VEX Conflicts and Issuer Trust
|
|
|
|
- Use **Advisories & VEX** to see which providers contributed statements, whether signatures verified, and where conflicts exist.
|
|
- The Console should not silently hide conflicts; it should show what disagrees and why, and how policy resolved it.
|
|
|
|
See `docs/VEX_CONSENSUS_GUIDE.md` for the underlying concepts.
|
|
|
|
### Export and Verify Evidence Bundles
|
|
|
|
- Exports are intended to be portable and verifiable (audits, incident response, air-gap review).
|
|
- Expect deterministic ordering, UTC timestamps, and hash manifests.
|
|
|
|
See `docs/OFFLINE_KIT.md` for packaging and offline verification workflows.
|
|
|
|
### Export Evidence Cards (v1.1)
|
|
|
|
Evidence Cards are single-file exports containing SBOM excerpt, DSSE envelope, and optional Rekor receipt for offline verification.
|
|
|
|
**To export an Evidence Card:**
|
|
|
|
1. Open an evidence pack from **Findings** or **Runs** workspace.
|
|
2. Click the **Export** dropdown in the pack viewer header.
|
|
3. Select **Evidence Card** for full export or **Evidence Card (Compact)** for a smaller file without full SBOM.
|
|
4. The browser downloads a `.evidence-card.json` file.
|
|
|
|
**Evidence Card contents:**
|
|
|
|
- `cardId`: Unique card identifier
|
|
- `version`: Schema version (e.g., "1.0.0")
|
|
- `packId`: Source evidence pack ID
|
|
- `subject`: Finding/CVE/component metadata
|
|
- `envelope`: DSSE signature envelope (when signed)
|
|
- `sbomExcerpt`: Relevant SBOM component data (full export only)
|
|
- `rekorReceipt`: Sigstore Rekor transparency log receipt (when available)
|
|
- `contentDigest`: SHA-256 digest for verification
|
|
|
|
**Content types:**
|
|
|
|
- Full: `application/vnd.stellaops.evidence-card+json`
|
|
- Compact: `application/vnd.stellaops.evidence-card-compact+json`
|
|
|
|
See `docs/api/evidence-decision-api.openapi.yaml` for the complete schema.
|
|
|
|
## Offline / Air-Gap Expectations
|
|
|
|
- The Console must operate against Offline Kit snapshots (no external lookups required).
|
|
- The UI should surface snapshot identity and staleness budgets (feeds, VEX, policy versions).
|
|
- Upload/import workflows for Offline Kit bundles should be auditable (who imported what, when).
|
|
|
|
## Setup Wizard
|
|
|
|
The Setup Wizard provides a guided interface for initial platform configuration and reconfiguration. It communicates with the Platform backend via `/api/v1/setup/*` endpoints.
|
|
|
|
### Wizard Features
|
|
|
|
- **Session-based workflow:** Sessions track progress across steps, enabling resume after interruption.
|
|
- **Step validation:** Each step includes Doctor checks that validate configuration before proceeding.
|
|
- **Dry-run mode:** Preview configuration changes before applying them.
|
|
- **Error handling:** Problem+JSON errors are mapped to user-friendly messages with suggested fixes.
|
|
- **Data freshness:** Stale data banners show when cached information may be outdated.
|
|
- **Retry support:** Failed operations can be retried with backoff and attempt tracking.
|
|
|
|
### Wizard Steps
|
|
|
|
The wizard guides operators through these configuration areas:
|
|
|
|
| Step | Category | Required | Description |
|
|
|------|----------|----------|-------------|
|
|
| Database | Infrastructure | Yes | PostgreSQL connection and migrations |
|
|
| Cache | Infrastructure | Yes | Valkey/Redis connection |
|
|
| Vault | Security | No | HashiCorp Vault, Azure Key Vault, or AWS Secrets Manager |
|
|
| Settings Store | Configuration | No | Consul, etcd, or PostgreSQL-backed configuration |
|
|
| Registry | Integration | No | Container registry connections |
|
|
| Telemetry | Observability | No | OTLP endpoint configuration |
|
|
|
|
### Using the Wizard
|
|
|
|
1. Access the Setup Wizard from **Admin > Configuration Wizard** or during first-run.
|
|
2. Complete required steps (Database, Cache) before optional integrations.
|
|
3. Use **Test Connection** to validate credentials before applying.
|
|
4. Review validation checks (Doctor diagnostics) for each step.
|
|
5. Use dry-run mode to preview changes before committing.
|
|
6. After completion, restart services to apply the configuration.
|
|
|
|
### Reconfiguration
|
|
|
|
To modify existing configuration:
|
|
- Use `stella setup --reconfigure` (CLI) or **Admin > Configuration Wizard** (UI).
|
|
- Individual steps can be reconfigured without re-running the entire wizard.
|
|
|
|
See `docs/setup/setup-wizard-ux.md` for detailed UX specifications and CLI parity.
|
|
|
|
## Security and Access
|
|
|
|
- Authentication is typically OIDC/OAuth2 via Authority; scopes/roles govern write actions.
|
|
- Treat tokens as sensitive; avoid copying secrets into notes/tickets.
|
|
- For CSP, scopes, and DPoP posture, see `docs/security/console-security.md`.
|
|
|
|
## Observability and Accessibility
|
|
|
|
- UI telemetry and metrics guidance: `docs/modules/telemetry/guides/ui-telemetry.md`.
|
|
- Accessibility baseline and keyboard model: `docs/accessibility.md`.
|
|
|
|
## Deploy and Install References
|
|
|
|
- Deployment configuration and health checks: `docs/deploy/console.md`.
|
|
- Container install recipes: `docs/operations/console-docker-install.md`.
|
|
|
|
## Detailed References
|
|
|
|
Operator-facing deep dives (Console):
|
|
|
|
- `docs/modules/ui/operations/airgap-console.md`
|
|
- `docs/modules/ui/operations/admin-tenants.md`
|
|
- `docs/modules/ui/operations/forensics.md`
|
|
- `docs/modules/ui/operations/observability-guide.md`
|
|
|
|
UX and interaction contracts:
|
|
|
|
- `docs/modules/ui/guides/ux/TRIAGE_UX_GUIDE.md`
|
|
|
|
## Related Docs
|
|
|
|
- `docs/VEX_CONSENSUS_GUIDE.md`
|
|
- `docs/VULNERABILITY_EXPLORER_GUIDE.md`
|
|
- `docs/OFFLINE_KIT.md`
|
|
- `docs/cli-vs-ui-parity.md`
|
|
- `docs/technical/architecture/console-admin-rbac.md`
|
|
- `docs/technical/architecture/console-branding.md`
|