10 KiB
10 KiB
StellaOps Console – Overview
Audience: Console product leads, Docs Guild writers, backend/API partners.
Scope: Information architecture, tenant scoping, global filters, and Aggregation‑Only Contract (AOC) alignment for the unified StellaOps Console that lands with Sprint 23.
The StellaOps Console is the single entry point for operators to explore SBOMs, advisories, policies, runs, and administrative surfaces. This overview explains how the console is organised, how users move between tenants, and how shared filters keep data views consistent across modules while respecting AOC boundaries.
1 · Mission & Principles
- Deterministic navigation. Every route is stable and deep-link friendly. URLs carry enough context (tenant, filter tokens, view modes) to let operators resume work without reapplying filters.
- Tenant isolation first. Any cross-tenant action requires fresh authority, and cross-tenant comparisons are made explicit so users never accidentally mix data sets.
- Aggregation-not-merge UX. Console surfaces advisory and VEX rollups exactly as produced by Concelier and Excititor—no client-side re-weighting or mutation.
- Offline parity. Every view has an offline equivalent powered by Offline Kit bundles or cached data, and exposes the staleness budget prominently.
2 · Information Architecture
2.1 Primary navigation
Console Root
├─ Dashboard # KPIs, alerts, feed age, queue depth
├─ Findings # Aggregated vulns + explanations (Policy Engine)
├─ SBOM Explorer # Catalog, component graph, overlays
├─ Advisories & VEX # Concelier / Excititor aggregation outputs
├─ Runs # Scheduler runs, scan evidence, retry controls
├─ Policies # Editor, simulations, approvals
├─ Downloads # Signed artifacts, Offline Kit parity
├─ Admin # Tenants, roles, tokens, integrations
└─ Help & Tours # Contextual docs, guided walkthroughs
Routes lazy-load feature shells so the UI can grow without increasing first-paint cost. Each feature owns its sub-navigation and exposes a KeyboardShortcuts modal describing the available accelerators.
2.2 Shared surfaces
| Surface | Purpose | Notes |
|---|---|---|
| Top bar | Shows active tenant, environment badge (prod/non-prod), offline status pill, user menu, notifications inbox, and the command palette trigger (⌘/Ctrl K). |
Offline status turns amber when data staleness exceeds configured thresholds. |
| Global filter tray | Expands from the right edge (Shift F). Hosts universal filters (tenant, time window, tags, severity) that apply across compatible routes. |
Filter tray remembers per-tenant presets; stored in IndexedDB (non-sensitive). |
| Context chips | Display active global filters underneath page titles, with one-click removal (⌫). |
Chips include the origin (e.g., Tenant: west-prod). |
| Status ticker | SSE-driven strip that surfaces Concelier/Excititor ingestion deltas, scheduler lag, and attestor queue depth. | Pulls from /console/status proxy (see WEB-CONSOLE-23-002). |
3 · Tenant Model
| Aspect | Detail |
|---|---|
| Tenant sources | The console obtains the tenant list and metadata from Authority /v1/tenants after login. Tenant descriptors include display name, slug, environment tag, and RBAC hints (role mask). |
| Selection workflow | First visit prompts for a default tenant. Afterwards, the tenant picker (⌘/Ctrl T) switches context without full reload, issuing Authorization refresh with the new tenant scope. |
| Token handling | Each tenant change generates a short-lived, DPoP-bound access token (aud=console, tenant=<id>). Tokens live in memory; metadata persists in sessionStorage for reload continuity. |
| Cross-tenant comparisons | Side-by-side dashboards (Dashboard, Findings, SBOM Explorer) allow multi-tenant comparison only via explicit "Add tenant" control. Requests issue parallel API calls with separate tokens; results render in split panes labelled per tenant. |
| Fresh-auth gated actions | Admin and policy approvals call Authority /fresh-auth before executing. UI enforces a 5-minute window; afterwards, actions remain visible but disabled pending re-auth. |
| Audit trail | Tenant switches emit structured logs (action=ui.tenant.switch, tenantId, subject, previousTenant) and appear in Authority audit exports. |
3.1 Offline operation
In offline or sealed environments, the tenant picker only lists tenants bundled within the Offline Kit snapshot. Switching tenants prompts an "offline snapshot" banner showing the snapshot timestamp. Actions that require round-trips to Authority (fresh-auth, token rotation) show guidance to perform the step on an online bastion and import credentials later.
4 · Global Filters & Context Tokens
| Filter | Applies To | Source & Behaviour |
|---|---|---|
| Tenant | All modules | Primary isolation control. Stored in URL (?tenant=) and via x-tenant-id header injected by the web proxy. Changes invalidate cached data stores. |
| Time window | Dashboard, Findings, Advisories & VEX, Runs | Options: 24 h, 7 d, 30 d, custom ISO range. Default aligns with Compliance/Authority reporting window. Shared via query param since=/until=. |
| Severity / Impact | Findings, Advisories & VEX, SBOM Explorer overlays | Multi-select (Critical/High/Medium/Low/Informational, plus Exploited tag). Values map to Policy Engine impact buckets and Concelier KEV flags. |
| Component tags | SBOM Explorer, Findings | Tags drawn from SBOM metadata (component.tags[]). Includes search-as-you-type with scoped suggestions (package type, supplier, license). |
| Source providers | Advisories & VEX | Filter by provider IDs (e.g., NVD, GHSA, vendor VEX). Tied to Aggregation-Only provenance; filtering never alters base precedence. |
| Run status | Runs, Dashboard | States: queued, running, completed, failed, cancelled. Pulled from Scheduler SSE stream; default shows non-terminal states. |
| Policy view | Findings, Policies | Toggles between Active policy, Staged policy, and Simulation snapshots. Selecting Simulation requires prior simulation run; console links to create one if absent. |
Filters emit deterministic tokens placed in the URL hash for copy/paste parity with CLI commands (see /docs/cli-vs-ui-parity.md). The console warns when a filter combination has no effect on the current view and offers to reset to defaults.
4.1 Presets & Saved Views
Users can save a set of global filters as named presets (stored per tenant). Presets show up in the command palette and the dashboard landing cards for quick access (⌘/Ctrl 1..9).
5 · Aggregation-Only Alignment
- Read-only aggregation. Pages that list advisories or VEX claims consume the canonical aggregation endpoints (
/console/advisories,/console/vex). They never merge or reconcile records client-side. Instead, they highlight the source lineage and precedence as supplied by Concelier and Excititor. - Consistency indicators. Each aggregated item displays source badges, precedence order, and a "last merge event hash" so operators can cross-reference Concelier logs. When a source is missing or stale, the UI surfaces a provenance banner linking to the raw document.
- AOC guardrails. Workflow actions (e.g., "request verify", "download evidence bundle") route through Concelier WebService guard endpoints that enforce Aggregation-Only rules. UI strings reinforce that policy decisions happen in Policy Engine, not here.
- Audit alignment. Any cross-navigation from aggregated data into findings or policies preserves the underlying IDs so analysts can track how aggregated data influences policy verdicts without altering the data itself.
- CLI parity. Inline callouts copy the equivalent
stellaCLI commands, ensuring console users can recreate the exact aggregation query offline.
6 · Performance & Telemetry Anchors
- Initial boot target: < 2.5 s
LargestContentfulPainton 4 vCPU air-gapped runner with cached assets. - Route budget: each feature shell must keep first interaction (hydrated data + filters) under 1.5 s once tokens resolve.
- Telemetry: console emits metrics via the
/console/telemetrybatch endpoint—ui_route_render_seconds,ui_filter_apply_total,ui_tenant_switch_total,ui_offline_banner_seconds. Logs carry correlation IDs matching backend responses for unified tracing. - Lighthouse CI runs in the console pipeline (see
DEVOPS-CONSOLE-23-001) and asserts budgets above; failing runs gate releases.
7 · References
/docs/architecture/console.md– component-level diagrams (pending Sprint 23 task)./docs/ui/navigation.md– detailed routes, breadcrumbs, keyboard shortcuts./docs/ui/downloads.md– downloads manifest, parity workflows, offline guidance./docs/ui/sbom-explorer.md– SBOM-specific flows and overlays./docs/ui/advisories-and-vex.md– aggregation UX details./docs/ui/findings.md– explain drawer and filter matrix./docs/security/console-security.md– OIDC, scopes, CSP, evidence handling./docs/cli-vs-ui-parity.md– CLI equivalents and regression automation.
8 · Compliance Checklist
- Tenant picker enforces Authority-issued scopes and logs
ui.tenant.switch. - Global filters update URLs/query tokens for deterministic deep links.
- Aggregation views show provenance badges and merge hash indicators.
- CLI parity callouts aligned with
stellacommands for equivalent queries. - Offline banner tested with Offline Kit snapshot import and documented staleness thresholds.
- Accessibility audit covers global filter tray, tenant picker, and keyboard shortcuts (WCAG 2.2 AA).
- Telemetry and Lighthouse budgets tracked in console CI (
DEVOPS-CONSOLE-23-001).
Last updated: 2025-10-26 (Sprint 23).