git.stella-ops.org/docs/UI_GUIDE.md

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