Add Policy DSL Validator, Schema Exporter, and Simulation Smoke tools
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implemented PolicyDslValidator with command-line options for strict mode and JSON output. - Created PolicySchemaExporter to generate JSON schemas for policy-related models. - Developed PolicySimulationSmoke tool to validate policy simulations against expected outcomes. - Added project files and necessary dependencies for each tool. - Ensured proper error handling and usage instructions across tools.
This commit is contained in:
174
docs/ui/admin.md
Normal file
174
docs/ui/admin.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# StellaOps Console - Admin Workspace
|
||||
|
||||
> **Audience:** Authority Guild, Console admins, support engineers, tenant operators.
|
||||
> **Scope:** Tenant management, role mapping, token lifecycle, integrations, fresh-auth prompts, security guardrails, offline behaviour, and compliance checklist for Sprint 23.
|
||||
|
||||
The Admin workspace centralises Authority-facing controls: tenants, roles, API clients, tokens, and integrations. It surfaces RBAC mappings, token issuance logs, and bootstrap flows with the same offline-first guarantees as the rest of the console.
|
||||
|
||||
---
|
||||
|
||||
## 1. Access and prerequisites
|
||||
|
||||
- **Route:** `/console/admin` with sub-routes for tenants, users, roles, tokens, integrations, audit, and bootstrap.
|
||||
- **Scopes:**
|
||||
- `ui.admin` (base access)
|
||||
- `authority:tenants.read` / `authority:tenants.write`
|
||||
- `authority:roles.read` / `authority:roles.write`
|
||||
- `authority:tokens.read` / `authority:tokens.revoke`
|
||||
- `authority:clients.read` / `authority:clients.write`
|
||||
- `authority:audit.read` (view audit trails)
|
||||
- **Fresh-auth:** Sensitive actions (token revoke, bootstrap key issue, signing key rotation) require fresh-auth challenge.
|
||||
- **Dependencies:** Authority service (`/internal/*` APIs), revocation export, JWKS, licensing posture endpoint, integration config store.
|
||||
|
||||
---
|
||||
|
||||
## 2. Layout overview
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------+
|
||||
| Header: Tenant picker - environment badge - security banner |
|
||||
+--------------------------------------------------------------------+
|
||||
| Tabs: Tenants | Roles & Scopes | Users & Tokens | Integrations | Audit |
|
||||
+--------------------------------------------------------------------+
|
||||
| Sidebar: Quick actions (Invite user, Create client, Export revocations)
|
||||
| Main panel varies per tab |
|
||||
+--------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
The header includes offline status indicator and link to Authority health page.
|
||||
|
||||
---
|
||||
|
||||
## 3. Tenants tab
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Tenant ID** | Lowercase slug used in tokens and client registrations. |
|
||||
| **Display name** | Human-friendly name. |
|
||||
| **Status** | `active`, `suspended`, `pending`. Suspended tenants block token issuance. |
|
||||
| **Isolation mode** | `dedicated`, `shared`, or `sandbox`. Drives RBAC defaults. |
|
||||
| **Default roles** | Roles automatically assigned to new users within the tenant. |
|
||||
| **Offline snapshots** | Latest snapshot timestamp, checksum, operator. |
|
||||
|
||||
Actions:
|
||||
|
||||
- `Create tenant` (requires `authority:tenants.write`). Form captures display name, slug, isolation mode, default roles, bootstrap contact, optional plan metadata.
|
||||
- `Suspend/Resume` toggles token issuance and surfaces audit entry.
|
||||
- `Export tenant bundle` downloads tenant-specific revocation + JWKS package for air-gap distribution.
|
||||
- CLI parity: `stella auth tenant create --tenant <id>`, `stella auth tenant suspend --tenant <id>`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Roles & scopes tab
|
||||
|
||||
- Table lists roles with mapped scopes and audiences.
|
||||
- Inline editor supports adding/removing scopes (with validation).
|
||||
- Scope categories: UI, Scanner, Concelier, Excititor, Policy, Attestor, Notifier, Scheduler, Offline kit.
|
||||
- Visual diff shows impact of changes on linked clients/users before committing.
|
||||
- "Effective permissions" view summarises what each role grants per service.
|
||||
- CLI parity: `stella auth role update --role ui.admin --add-scope authority:tokens.revoke`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Users & tokens tab
|
||||
|
||||
Sections:
|
||||
|
||||
1. **User list** - identity, tenant, roles, last login, MFA status. Actions include reset password (if plugin supports), enforce fresh-auth, disable user.
|
||||
2. **Token inventory** - lists active tokens (access/refresh/device). Columns: token ID, type, subject, audience, issued at, expires, status. Toggle to show revoked tokens.
|
||||
3. **Token details** drawer shows claims, sender constraint (`cnf`), issuance metadata, revocation history.
|
||||
4. **Revoke token** action requires fresh-auth and prompts for reason (incident, user request, compromise).
|
||||
5. **Bulk revoke** (per tenant or role) triggers Authority revocation export to ensure downstream services purge caches.
|
||||
|
||||
Audit entries appear for every user/token change. CLI parity: `stella auth token revoke --token <id>`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Integrations tab
|
||||
|
||||
- **Authority clients** list (service accounts) with grant types, allowed scopes, DPoP/mTLS settings, tenant hints, and rotation status.
|
||||
- **Bootstrap bundles** - downloadable templates for new clients/users; includes configuration YAML and CLI instructions.
|
||||
- **External IdP connectors** (optional) - displays status for SAML/OIDC plugins; includes metadata upload field and test login result.
|
||||
- **Licensing posture** - read-only panel summarising plan tier, entitlement expiry, and contact info (pulled from licensing service).
|
||||
- **Notifications** - optional webhook configuration for token events (on revoke, on failure).
|
||||
- CLI parity: `stella auth client create --client concelier --grant client_credentials --tenant prod`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Audit tab
|
||||
|
||||
- Timeline view of administrative events (user changes, role updates, token revocations, bootstrap actions, key rotations).
|
||||
- Filters: event type, actor, tenant, scope, correlation ID.
|
||||
- Export button downloads CSV/JSON for SOC ingestion.
|
||||
- "Open in logs" copies search query pre-populated with correlation IDs.
|
||||
- CLI parity: `stella auth audit export --from 2025-10-20`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Fresh-auth prompts
|
||||
|
||||
- High-risk actions (revoke all tokens, rotate signing key, create privileged client) trigger modal requiring credential re-entry or hardware key touch.
|
||||
- Fresh-auth window is 5 minutes; countdown displayed.
|
||||
- UI surface indicates when current session is outside fresh-auth window; sensitive buttons disabled until re-auth.
|
||||
- Audit log records fresh-auth events (`authority.fresh_auth.start`, `authority.fresh_auth.success`).
|
||||
- CLI parity: `stella auth fresh-auth` obtains short-lived token for scriptable flows.
|
||||
|
||||
---
|
||||
|
||||
## 9. Security guardrails
|
||||
|
||||
- DPoP enforcement reminders for UI clients; console warns if any client lacks sender constraint.
|
||||
- mTLS enforcement summary for high-value audiences (Signer/Attestor).
|
||||
- Token policy checklists (access token TTL, refresh token policy) with alerts when deviating from defaults.
|
||||
- Revocation bundle export status (timestamp, digest, operator).
|
||||
- Key rotation panel showing current `kid`, last rotation, next scheduled rotation, and manual trigger button (ties into Authority rotate API).
|
||||
- CLI parity: `stella auth signing rotate` for script automation.
|
||||
|
||||
---
|
||||
|
||||
## 10. Offline and air-gap behaviour
|
||||
|
||||
- Offline banner indicates snapshot version; disables direct remote calls.
|
||||
- Tenant/role edits queue change manifests; UI instructs users to apply via CLI (`stella auth apply --bundle <file>`).
|
||||
- Token inventory shows snapshot state; revoke buttons generate scripts for offline Authority host.
|
||||
- Integrations tab offers manual download/upload for client definitions and IdP metadata.
|
||||
- Audit exports default to local storage with checksum output for transfer.
|
||||
|
||||
---
|
||||
|
||||
## 11. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- ``
|
||||
- Capture real screenshots with Authority Guild once Sprint 23 UI is final (tracked in `#console-screenshots`, 2025-10-26 entry). Provide both light and dark theme variants.
|
||||
|
||||
---
|
||||
|
||||
## 12. References
|
||||
|
||||
- `/docs/ARCHITECTURE_AUTHORITY.md` - Authority architecture.
|
||||
- `/docs/11_AUTHORITY.md` - Authority service overview.
|
||||
- `/docs/security/authority-scopes.md` - scope definitions.
|
||||
- `/docs/ui/policies.md` - policy approvals requiring fresh-auth.
|
||||
- `/docs/ui/console-overview.md` - navigation shell.
|
||||
- `/docs/cli/authentication.md` (pending) and `/docs/cli/policy.md` for CLI flows.
|
||||
- `/docs/ops/scheduler-runbook.md` for integration with scheduler token rotation.
|
||||
|
||||
---
|
||||
|
||||
## 13. Compliance checklist
|
||||
|
||||
- [ ] Tenants, roles/scopes, and token management documented with actions and CLI parity.
|
||||
- [ ] Integrations and audit views covered.
|
||||
- [ ] Fresh-auth prompts and guardrails described.
|
||||
- [ ] Security controls (DPoP, mTLS, key rotation, revocations) captured.
|
||||
- [ ] Offline behaviour explained with script guidance.
|
||||
- [ ] Screenshot placeholders and coordination noted.
|
||||
- [ ] References validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
|
||||
199
docs/ui/advisories-and-vex.md
Normal file
199
docs/ui/advisories-and-vex.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# StellaOps Console - Advisories and VEX
|
||||
|
||||
> **Audience:** Console UX team, Concelier and Excititor guilds, support and compliance engineers.
|
||||
> **Scope:** Advisory aggregation UX, VEX consensus display, conflict indicators, raw document viewer, provenance banners, CLI parity, and Aggregation-Only Contract (AOC) guardrails for Sprint 23.
|
||||
|
||||
The Advisories and VEX surfaces expose Concelier and Excititor outputs without mutating the underlying data. Operators can review upstream statements, check consensus summaries, inspect conflicts, and hand off evidence to downstream tooling while staying within the Aggregation-Only Contract.
|
||||
|
||||
---
|
||||
|
||||
## 1. Access and prerequisites
|
||||
|
||||
- **Routes:**
|
||||
- `/console/advisories` (advisory list and detail)
|
||||
- `/console/vex` (VEX consensus and raw claim explorer)
|
||||
- **Scopes:** `advisory.read` and `vex.read` (base access), `advisory.verify` / `vex.verify` for verification actions, `downloads.read` for evidence exports.
|
||||
- **Feature flags:** `advisoryExplorer.enabled`, `vexExplorer.enabled`, `aggregation.conflictIndicators`.
|
||||
- **Dependencies:** Concelier WebService (aggregation API + delta metrics), Excititor WebService (consensus API + conflict feeds), Policy Engine explain hints (optional link-outs), Authority tenant enforcement.
|
||||
- **Offline behaviour:** Uses Offline Kit snapshots when gateway is in sealed mode; verify buttons queue until connectivity resumes.
|
||||
|
||||
---
|
||||
|
||||
## 2. Layout overview
|
||||
|
||||
```
|
||||
+---------------------------------------------------------------------+
|
||||
| Header: Tenant badge - global filters - status ticker - actions |
|
||||
+---------------------------------------------------------------------+
|
||||
| Left rail: Saved views - provider filters - verification queue |
|
||||
+---------------------------------------------------------------------+
|
||||
| Main split pane |
|
||||
| - Advisories tab (grid + detail drawer) |
|
||||
| - VEX tab (consensus table + claim drawer) |
|
||||
| Tabs remember last active view per tenant. |
|
||||
+---------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
The header reuses console-wide context chips (`Tenant`, `Severity`, `Source`, `Time`) and the status ticker that streams Concelier and Excititor deltas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Advisory aggregation view
|
||||
|
||||
| Element | Description |
|
||||
|---------|-------------|
|
||||
| **Grid columns** | Vulnerability key (CVE/GHSA/vendor), Title, Source set, Last merged, Severity badge, KEV flag, Affected product count, Merge hash. |
|
||||
| **Source chips** | Show contributing providers (NVD, Red Hat, Debian, vendor PSIRT). Hover reveals precedence order and timestamps. |
|
||||
| **Severity** | Displays the highest severity declared by any source; tooltip lists per-source severities and vectors. |
|
||||
| **KEV / Exploit status** | Badge highlights known exploited status from Concelier enrichment; links to KEV reference. |
|
||||
| **Merge hash** | Deterministic hash from Concelier `merge_event`. Clicking copies hash and opens provenance banner. |
|
||||
| **Filters** | Vulnerability identifier search, provider multi-select, severity picker, KEV toggle, affected product range slider, time window. |
|
||||
| **List actions** | `Open detail`, `Copy CLI` (`stella advisory show ...`), `Compare sources`, `Queue verify`. |
|
||||
|
||||
The grid virtualises up to 15,000 advisories per tenant. Beyond that, the UI engages server-side pagination with cursor hints supplied by Concelier.
|
||||
|
||||
---
|
||||
|
||||
## 4. Advisory detail drawer
|
||||
|
||||
Sections within the drawer:
|
||||
|
||||
1. **Summary cards** (title, published/modified timestamps, advisory merge hash, total sources, exploited flag).
|
||||
2. **Sources timeline** listing each contributing document with signature status, fetched timestamps, precedence rank, and quick links to raw view.
|
||||
3. **Affected products** table (product key, introduced/fixed, range semantics, distro qualifiers, notes). Column toggles allow switching between SemVer and distro notation.
|
||||
4. **Conflict indicators** show when sources disagree on fixed versions, severity, or affected sets. Each conflict row links to an explainer panel that describes the winning value, losing sources, and precedence rule.
|
||||
5. **References** collapsible list (patches, advisories, exploits).
|
||||
6. **Raw JSON** viewer (read-only) using canonical Concelier payload. Users can copy JSON or download via `GET /console/advisories/raw/{id}`.
|
||||
7. **CLI parity** card with commands:
|
||||
- `stella advisory show --tenant <tenant> --vuln <id>`
|
||||
- `stella advisory sources --tenant <tenant> --vuln <id>`
|
||||
- `stella advisory export --tenant <tenant> --vuln <id> --format cdx-json`
|
||||
|
||||
Provenance banner at the top indicates whether all sources are signed, partially signed, or unsigned, referencing AOC guardrails. Unsigned sources trigger a warning and link to the verification checklist.
|
||||
|
||||
---
|
||||
|
||||
## 5. VEX explorer
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Consensus table** | Rows keyed by `(vulnId, productKey)` with rollup status (affected, not affected, fixed, under investigation), confidence score, provider count, and last evaluation timestamp. |
|
||||
| **Status badges** | Colour-coded (red affected, green not affected, blue fixed, amber under investigation). Tooltips show justification and policy revision used. |
|
||||
| **Provider breakdown** | Hover or expand to see source list with accepted/ignored flag, status, justification code, signature state, weight. |
|
||||
| **Filters** | Product search (PURL), status filter, provider filter, justification codes, confidence threshold slider. |
|
||||
| **Saved views** | Prebuilt presets: `Vendor consensus`, `Distro overrides`, `Conflicts`, `Pending investigation`. |
|
||||
|
||||
---
|
||||
|
||||
## 6. VEX detail drawer
|
||||
|
||||
Tabs within the drawer:
|
||||
|
||||
- **Consensus summary**: Restates rollup status, policy revision, confidence benchmarks, and referencing runs.
|
||||
- **Claims list**: Every raw claim from Excititor with provenance, signature result, justification, supersedes chain, evidence snippets. Claims are grouped by provider tier (vendor, distro, ecosystem, CERT).
|
||||
- **Conflict explainers**: For conflicting claims, shows why a claim was ignored (weight, stale timestamp, failing justification gate). Includes inline diff between competing claims.
|
||||
- **Events**: Timeline of claim arrivals and consensus evaluations with correlation IDs, accessible for debugging.
|
||||
- **Raw JSON**: Canonical `VexClaim` or `VexConsensus` payloads with copy/download. CLI parity callouts:
|
||||
- `stella vex consensus show --tenant <tenant> --vuln <id> --product <purl>`
|
||||
- `stella vex claims show --tenant <tenant> --vuln <id> --provider <provider>`
|
||||
|
||||
---
|
||||
|
||||
## 7. Raw viewers and provenance
|
||||
|
||||
- Raw viewers display canonical payloads with syntax highlighting and copy-as-JSON support.
|
||||
- Provenance banner presents: source URI, document digest, signature status, fetch timestamps, collector version.
|
||||
- Users can open raw documents in a modal that includes:
|
||||
- `sha256` digest with copy button
|
||||
- Signature verification summary (passing keys, missing signatures, errors)
|
||||
- `Download DSSE bundle` button when the document is attested
|
||||
- `Open in logs` link that copies search query (`correlationId=...`) for log aggregation tools.
|
||||
|
||||
All raw views are read-only to maintain Aggregation-Only guarantees.
|
||||
|
||||
---
|
||||
|
||||
## 8. Conflict indicators and aggregation-not-merge UX
|
||||
|
||||
- Concelier retains every source; the UI surfaces conflicts rather than merging them.
|
||||
- Conflict badges appear in grids and detail views when sources disagree on affected ranges, fixed versions, severity, or exploit flags.
|
||||
- Clicking a badge opens the conflict explainer panel (powered by Concelier merge metadata) that lists winning/losing sources, ranks, and reasoning (e.g., "Vendor PSIRT overrides ecosystem advisory").
|
||||
- Excititor conflicts highlight discarded claims with reasons (stale, failing justification, low weight). Operators can override weights downstream via Policy Engine if needed.
|
||||
- UI copy explicitly reminds users that policy decisions happen elsewhere; these views show aggregated facts only.
|
||||
|
||||
---
|
||||
|
||||
## 9. Verification workflows
|
||||
|
||||
- **Run verify** buttons call Concelier or Excititor verification endpoints (`POST /console/advisories/verify`, `POST /console/vex/verify`) scoped by tenant and source filters.
|
||||
- Verification results appear as banners summarising documents checked, signatures verified, and guard violations.
|
||||
- Failed verifications show actionable error IDs (`ERR_AOC_00x`), matching CLI output.
|
||||
- Verification history accessible via the status ticker dropdown; entries include operator, scope, and correlation IDs.
|
||||
|
||||
---
|
||||
|
||||
## 10. Exports and automation
|
||||
|
||||
- Advisory tab exposes export actions: `Download normalized advisory`, `Download affected products CSV`, `Download source bundle` (raw documents packaged with manifest).
|
||||
- VEX tab supports exports for consensus snapshots, raw claims, and provider deltas.
|
||||
- Export manifests include merge hash or consensus digest, tenant ID, timestamp, and signature state.
|
||||
- CLI parity snippets accompany each export (e.g., `stella advisory export`, `stella vex export`).
|
||||
- Automation: copy buttons for webhook subscription (`/downloads/hooks/subscribe`) and ORAS push commands when using remote registries.
|
||||
|
||||
---
|
||||
|
||||
## 11. Observability and SSE updates
|
||||
|
||||
- Status ticker shows ingest lag (`advisory_delta_minutes`, `vex_delta_minutes`), last merge event hash, and verification queue depth.
|
||||
- Advisory and VEX grids refresh via SSE channels; updates animate row badges (new source, conflict resolved).
|
||||
- Metrics surfaced in drawers: ingestion age, signature pass rate, consensus evaluation duration.
|
||||
- Errors display correlation IDs linking to Concelier/Excititor logs.
|
||||
|
||||
---
|
||||
|
||||
## 12. Offline and air-gap behaviour
|
||||
|
||||
- When offline, list views display snapshot badge, staleness timer, and disable real-time verification.
|
||||
- Raw downloads reference local snapshot directories and include checksum instructions.
|
||||
- Exports queue locally; UI offers `Copy to removable media` instructions.
|
||||
- CLI parity switches to offline commands (`--offline`, `--snapshot`).
|
||||
- Tenant picker hides tenants not present in the snapshot to avoid partial data views.
|
||||
|
||||
---
|
||||
|
||||
## 13. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- Coordinate with Console Guild to capture updated screenshots (dark and light themes) once Sprint 23 build candidate is tagged. Tracking in Slack channel `#console-screenshots` (entry 2025-10-26).
|
||||
|
||||
---
|
||||
|
||||
## 14. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - shell, filters, tenant model.
|
||||
- `/docs/ui/navigation.md` - command palette, deep-link schema.
|
||||
- `/docs/ingestion/aggregation-only-contract.md` - AOC guardrails.
|
||||
- `/docs/architecture/CONCELIER.md` - merge rules, provenance.
|
||||
- `/docs/architecture/EXCITITOR.md` - VEX consensus model.
|
||||
- `/docs/security/console-security.md` - scopes, DPoP, CSP.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence matrix.
|
||||
|
||||
---
|
||||
|
||||
## 15. Compliance checklist
|
||||
|
||||
- [ ] Advisory grid columns, filters, and merge hash behaviour documented.
|
||||
- [ ] VEX consensus view covers status badges, provider breakdown, and filters.
|
||||
- [ ] Raw viewer and provenance banners explained with AOC alignment.
|
||||
- [ ] Conflict indicators and explainers tied to aggregation-not-merge rules.
|
||||
- [ ] Verification workflow and CLI parity documented.
|
||||
- [ ] Offline behaviour and automation paths captured.
|
||||
- [ ] Screenshot placeholders and coordination notes recorded.
|
||||
- [ ] References validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
|
||||
130
docs/ui/console-overview.md
Normal file
130
docs/ui/console-overview.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# 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 `stella` CLI commands, ensuring console users can recreate the exact aggregation query offline.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Performance & Telemetry Anchors
|
||||
|
||||
- Initial boot target: **< 2.5 s** `LargestContentfulPaint` on 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/telemetry` batch 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 `stella` commands 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).*
|
||||
143
docs/ui/console.md
Normal file
143
docs/ui/console.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# Console AOC Dashboard
|
||||
|
||||
> **Audience:** Console PMs, UI engineers, Concelier/Excititor operators, SREs monitoring ingestion health.
|
||||
> **Scope:** Layout, RBAC, workflow, and observability for the Aggregation-Only Contract (AOC) dashboard that ships with Sprint 19.
|
||||
|
||||
The Console AOC dashboard gives operators a live view of ingestion guardrails across all configured sources. It surfaces raw Concelier/Excititor health, highlights violations raised by `AOCWriteGuard`, and lets on-call staff trigger verification without leaving the browser. Use it alongside the [Aggregation-Only Contract reference](../ingestion/aggregation-only-contract.md) and the [architecture overview](../architecture/overview.md) when rolling out AOC changes.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Access & prerequisites
|
||||
|
||||
- **Route:** `/console/sources` (dashboard) with contextual drawer routes `/console/sources/:sourceKey` and `/console/sources/:sourceKey/violations/:documentId`.
|
||||
- **Feature flag:** `aocDashboard.enabled` (default `true` once Concelier WebService exposes `/aoc/verify`). Toggle is tenant-scoped to support phased rollout.
|
||||
- **Scopes:**
|
||||
- `ui.read` (base navigation) and `advisory:verify` to view ingestion stats/violations.
|
||||
- `vex:verify` to see Excititor entries and run VEX verifications.
|
||||
- `advisory:write` / `vex:write` **not** required; dashboard uses read-only APIs.
|
||||
- **Tenancy:** All data is filtered by the active tenant selector. Switching tenants re-fetches tiles and drill-down tables with tenant-scoped tokens.
|
||||
- **Back-end contracts:** Requires Concelier/Excititor 19.x (AOC guards enabled) and Authority scopes updated per [Authority service docs](../ARCHITECTURE_AUTHORITY.md#new-aoc-scopes).
|
||||
|
||||
---
|
||||
|
||||
## 2 · Layout overview
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Header: tenant picker • live status pill • Last verify (“2h ago”) │
|
||||
├────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Tile grid (4 per row) │
|
||||
│ ┌───── Concelier sources ─────┐ ┌────── Excititor sources ────────┐ │
|
||||
│ │ Red Hat | Ubuntu | OSV ... │ │ Vendor VEX | CSAF feeds ... │ │
|
||||
├────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Violations & history table │
|
||||
│ • Filters: timeframe, source, ERR_AOC code, severity (warning/block) │
|
||||
│ • Columns: timestamp, source, code, summary, supersedes link, actions │
|
||||
├────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Action bar: Run Verify • Download CSV • Open Concelier raw doc • Help │
|
||||
└────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Tiles summarise the latest ingestion runs. The table and drawers provide drill-down views, and the action bar launches verifier workflows or exports evidence for audits.
|
||||
|
||||
---
|
||||
|
||||
## 3 · Source tiles
|
||||
|
||||
Each tile represents a Concelier or Excititor source and contains the fields below.
|
||||
|
||||
| Field | Description | Thresholds & colours |
|
||||
| ------ | ----------- | -------------------- |
|
||||
| **Status badge** | Aggregated health computed from the latest job. | `Healthy` (green) when last job finished < 30 min ago and `violations24h = 0`; `Warning` (amber) when age ≥ 30 min or ≤ 5 violations; `Critical` (red) on any guard rejection (`ERR_AOC_00x`) or if job age > 2 h. |
|
||||
| **Last ingest** | Timestamp and relative age of last successful append to `advisory_raw`/`vex_raw`. | Clicking opens job detail drawer. |
|
||||
| **Violations (24 h)** | Count of guard failures grouped by `ERR_AOC` code across the last 24 hours. | Shows pill per code (e.g., `ERR_AOC_001 × 2`). |
|
||||
| **Supersedes depth** | Average length of supersedes chain for the source over the last day. | Helps spot runaway revisions. |
|
||||
| **Signature pass rate** | % of documents where signature/checksum verification succeeded. | Derived from `ingestion_signature_verified_total`. |
|
||||
| **Latency P95** | Write latency recorded by ingestion spans / histograms. | Mirrors `ingestion_latency_seconds{quantile=0.95}`. |
|
||||
|
||||
Tile menus expose quick actions:
|
||||
|
||||
- **View history** – jumps to table filtered by the selected source.
|
||||
- **Open metrics** – deep links to Grafana panel seeded with `source=<key>` for `ingestion_write_total` and `aoc_violation_total`.
|
||||
- **Download raw sample** – fetches the most recent document via `GET /advisories/raw/{id}` (or VEX equivalent) for debugging.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Violation drill-down workflow
|
||||
|
||||
1. **Select a tile** or use table filters to focus on a source, timeframe, or `ERR_AOC` code.
|
||||
2. **Inspect the violation row:** summary shows offending field, guard code, and document hash.
|
||||
3. **Open detail drawer:** reveals provenance (source URI, signature info), supersedes chain, and raw JSON (redacted secrets). Drawer also lists linked `effective_finding_*` entries if Policy Engine has already materialised overlays.
|
||||
4. **Remediate / annotate:** operators can add notes (stored as structured annotations) or flag as *acknowledged* (for on-call rotations). Annotations sync to Concelier audit logs.
|
||||
5. **Escalate:** “Create incident” button opens the standard incident template pre-filled with context (requires `ui.incidents` scope).
|
||||
|
||||
The drill-down retains filter state, so back navigation returns to the scoped table without reloading the entire dashboard.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Verification & actions
|
||||
|
||||
- **Run Verify:** calls `POST /aoc/verify` with the chosen `since` window (default 24 h). UI displays summary cards (documents checked, violations found, top codes) and stores reports for 7 days. Results include a downloadable JSON manifest mirroring CLI output.
|
||||
- **Schedule verify:** schedule modal configures automated verification (daily/weekly) and optional email/Notifier hooks.
|
||||
- **Export evidence:** CSV/JSON export buttons include tile metrics, verification summaries, and violation annotations—useful for audits.
|
||||
- **Open in CLI:** copies `stella aoc verify --tenant <tenant> --since <window>` for parity with automation scripts.
|
||||
|
||||
All verify actions are scoped by tenant and recorded in Authority audit logs (`action=aoc.verify.ui`).
|
||||
|
||||
---
|
||||
|
||||
## 6 · Metrics & observability
|
||||
|
||||
The dashboard consumes the same metrics emitted by Concelier/Excititor (documented in the [AOC reference](../ingestion/aggregation-only-contract.md#9-observability-and-diagnostics)):
|
||||
|
||||
- `ingestion_write_total{source,tenant,result}` – populates success/error sparklines beneath each tile.
|
||||
- `aoc_violation_total{source,tenant,code}` – feeds violation pills and trend chart.
|
||||
- `ingestion_signature_verified_total{source,result}` – renders signature pass-rate gauge.
|
||||
- `ingestion_latency_seconds{source,quantile}` – used for latency badges and alert banners.
|
||||
- `advisory_revision_count{source}` – displayed in supersedes depth tooltip.
|
||||
|
||||
The page shows the correlation ID for each violation entry, matching structured logs emitted by Concelier and Excititor, enabling quick log pivoting.
|
||||
|
||||
---
|
||||
|
||||
## 7 · Security & tenancy
|
||||
|
||||
- Tokens are DPoP-bound; every API call includes the UI’s DPoP proof and inherits tenant scoping from Authority.
|
||||
- Violations drawer hides sensitive fields (credentials, private keys) using the same redaction rules as Concelier events.
|
||||
- Run Verify honours rate limits to avoid overloading ingestion services; repeated failures trigger a cool-down banner.
|
||||
- The dashboard never exposes derived severity or policy status—only raw ingestion facts and guard results, preserving AOC separation of duties.
|
||||
|
||||
---
|
||||
|
||||
## 8 · Offline & air-gap behaviour
|
||||
|
||||
- In sealed/offline mode the dashboard switches to **“offline snapshot”** banner, reading from Offline Kit snapshots seeded via `ouk` imports.
|
||||
- Verification requests queue until connectivity resumes; UI provides `Download script` to run `stella aoc verify` on a workstation and upload results later.
|
||||
- Tiles display the timestamp of the last imported snapshot and flag when it exceeds the configured staleness threshold (default 48 h offline).
|
||||
- CSV/JSON exports include checksums so operators can transfer evidence across air gaps securely.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Related references
|
||||
|
||||
- [Aggregation-Only Contract reference](../ingestion/aggregation-only-contract.md)
|
||||
- [Architecture overview](../architecture/overview.md)
|
||||
- [Concelier architecture](../ARCHITECTURE_CONCELIER.md)
|
||||
- [Excititor architecture](../ARCHITECTURE_EXCITITOR.md)
|
||||
- [CLI AOC commands](../cli/cli-reference.md)
|
||||
|
||||
---
|
||||
|
||||
## 10 · Compliance checklist
|
||||
|
||||
- [ ] Dashboard wired to live AOC metrics (`ingestion_*`, `aoc_violation_total`).
|
||||
- [ ] Verify action logs to Authority audit trail with tenant context.
|
||||
- [ ] UI enforces read-only access to raw stores; no mutation endpoints invoked.
|
||||
- [ ] Offline/air-gap mode documented and validated with Offline Kit snapshots.
|
||||
- [ ] Violation exports include provenance and `ERR_AOC_00x` codes.
|
||||
- [ ] Accessibility tested (WCAG 2.2 AA) for tiles, tables, and drawers.
|
||||
- [ ] Screenshot/recording captured for Docs release notes (pending UI capture).
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 19).*
|
||||
212
docs/ui/downloads.md
Normal file
212
docs/ui/downloads.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# StellaOps Console - Downloads Manager
|
||||
|
||||
> **Audience:** DevOps guild, Console engineers, enablement writers, and operators who promote releases or maintain offline mirrors.
|
||||
> **Scope:** `/console/downloads` workspace covering artifact catalog, signed manifest plumbing, export status handling, CLI parity, automation hooks, and offline guidance (Sprint 23).
|
||||
|
||||
The Downloads workspace centralises every artefact required to deploy or validate StellaOps in connected and air-gapped environments. It keeps Console operators aligned with release engineering by surfacing the signed downloads manifest, live export jobs, parity checks against Offline Kit bundles, and automation hooks that mirror the CLI experience.
|
||||
|
||||
---
|
||||
|
||||
## 1 - Access and prerequisites
|
||||
|
||||
- **Route:** `/console/downloads` (list) with detail drawer `/console/downloads/:artifactId`.
|
||||
- **Scopes:** `downloads.read` (baseline) and `downloads.manage` for cancelling or expiring stale exports. Evidence bundles inherit the originating scope (`runs.read`, `findings.read`, etc.).
|
||||
- **Dependencies:** Web gateway `/console/downloads` API (WEB-CONSOLE-23-005), DevOps manifest pipeline (`deploy/downloads/manifest.json`), Offline Kit metadata (`manifest/offline-manifest.json`), and export orchestrator `/console/exports`.
|
||||
- **Feature flags:** `downloads.workspace.enabled`, `downloads.exportQueue`, `downloads.offlineParity`.
|
||||
- **Tenancy:** Artefacts are tenant-agnostic except evidence bundles, which are tagged with originating tenant and require matching Authority scopes.
|
||||
|
||||
---
|
||||
|
||||
## 2 - Workspace layout
|
||||
|
||||
```
|
||||
+---------------------------------------------------------------+
|
||||
| Header: Snapshot timestamp - Manifest signature status |
|
||||
+---------------------------------------------------------------+
|
||||
| Cards: Latest release - Offline kit parity - Export queue |
|
||||
+---------------------------------------------------------------+
|
||||
| Tabs: Artefacts | Exports | Offline Kits | Webhooks |
|
||||
+---------------------------------------------------------------+
|
||||
| Filter bar: Channel - Kind - Architecture - Scope tags |
|
||||
+---------------------------------------------------------------+
|
||||
| Table (virtualised): Artifact | Channel | Digest | Status |
|
||||
| Detail drawer: Metadata | Commands | Provenance | History |
|
||||
+---------------------------------------------------------------+
|
||||
```
|
||||
|
||||
- **Snapshot banner:** shows `manifest.version`, `generatedAt`, and cosign verification state. If verification fails, the banner turns red and links to troubleshooting guidance.
|
||||
- **Quick actions:** Copy manifest URL, download attestation bundle, trigger parity check, open CLI parity doc (`/docs/cli-vs-ui-parity.md`).
|
||||
- **Filters:** allow narrowing by channel (`edge`, `stable`, `airgap`), artefact kind (`container.image`, `helm.chart`, `compose.bundle`, `offline.bundle`, `export.bundle`), architecture (`linux/amd64`, `linux/arm64`), and scope tags (`console`, `scheduler`, `authority`).
|
||||
|
||||
---
|
||||
|
||||
## 3 - Artefact catalogue
|
||||
|
||||
| Category | Artefacts surfaced | Source | Notes |
|
||||
|----------|-------------------|--------|-------|
|
||||
| **Core containers** | `stellaops/web-ui`, `stellaops/web`, `stellaops/concelier`, `stellaops/excititor`, `stellaops/scanner-*`, `stellaops/authority`, `stellaops/attestor`, `stellaops/scheduler-*` | `deploy/downloads/manifest.json` (`artifacts[].kind = "container.image"`) | Digest-only pulls with copy-to-clipboard `docker pull` and `oras copy` commands; badges show arch availability. |
|
||||
| **Helm charts** | `deploy/helm/stellaops-*.tgz` plus values files | Manifest entries where `kind = "helm.chart"` | Commands reference `helm repo add` (online) and `helm install --values` (offline). UI links to values matrix in `/docs/install/helm-prod.md` when available. |
|
||||
| **Compose bundles** | `deploy/compose/docker-compose.*.yaml`, `.env` seeds | `kind = "compose.bundle"` | Inline diff viewer highlights digest changes vs previous snapshot; `docker compose pull` command copies digest pins. |
|
||||
| **Offline kit** | `stella-ops-offline-kit-<ver>-<channel>.tar.gz` + signatures and manifest | Offline Kit metadata (`manifest/offline-manifest.json`) merged into downloads view | Drawer shows bundle size, signed manifest digest, cosign verification command (mirrors `/docs/24_OFFLINE_KIT.md`). |
|
||||
| **Evidence exports** | Completed jobs from `/console/exports` (findings delta, policy explain, run evidence) | Export orchestrator job queue | Entries expire after retention window; UI exposes `stella runs export` and `stella findings export` parity buttons. |
|
||||
| **Webhooks & parity** | `/downloads/hooks/subscribe` configs, CI parity reports | Manifest extras (`kind = "webhook.config"`, `kind = "parity.report"`) | Operators can download webhook payload templates and review the latest CLI parity check report generated by docs CI. |
|
||||
|
||||
---
|
||||
|
||||
## 4 - Manifest structure
|
||||
|
||||
The DevOps pipeline publishes a deterministic manifest at `deploy/downloads/manifest.json`, signed with the release Cosign key (`DOWNLOADS-CONSOLE-23-001`). The Console fetches it on workspace load and caches it with `If-None-Match` headers to avoid redundant pulls. The manifest schema:
|
||||
|
||||
- **`version`** - monotonically increasing integer tied to pipeline run.
|
||||
- **`generatedAt`** - ISO-8601 UTC timestamp.
|
||||
- **`signature`** - URL to detached Cosign signature (`manifest.json.sig`).
|
||||
- **`artifacts[]`** - ordered list keyed by `id`.
|
||||
|
||||
Each artefact contains:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `id` | Stable identifier (`<type>:<name>:<version>`). |
|
||||
| `kind` | One of `container.image`, `helm.chart`, `compose.bundle`, `offline.bundle`, `export.bundle`, `webhook.config`, `parity.report`. |
|
||||
| `channel` | `edge`, `stable`, or `airgap`. |
|
||||
| `version` | Semantic or calendar version (for containers, matches release manifest). |
|
||||
| `architectures` | Array of supported platforms (empty for arch-agnostic artefacts). |
|
||||
| `digest` | SHA-256 for immutable artefacts; Compose bundles include file hash. |
|
||||
| `sizeBytes` | File size (optional for export bundles that stream). |
|
||||
| `downloadUrl` | HTTPS endpoint (registry, object store, or mirror). |
|
||||
| `signatureUrl` | Detached signature (Cosign, DSSE, or attestation) if available. |
|
||||
| `sbomUrl` | Optional SBOM pointer (CycloneDX JSON). |
|
||||
| `attestationUrl` | Optional in-toto/SLSA attestation. |
|
||||
| `docs` | Array of documentation links (e.g., `/docs/install/docker.md`). |
|
||||
| `tags` | Free-form tags (e.g., `["console","ui","offline"]`). |
|
||||
|
||||
### 4.1 Example excerpt
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 42,
|
||||
"generatedAt": "2025-10-27T04:00:00Z",
|
||||
"signature": "https://downloads.stella-ops.org/manifest/manifest.json.sig",
|
||||
"artifacts": [
|
||||
{
|
||||
"id": "container.image:web-ui:2025.10.0-edge",
|
||||
"kind": "container.image",
|
||||
"channel": "edge",
|
||||
"version": "2025.10.0-edge",
|
||||
"architectures": ["linux/amd64", "linux/arm64"],
|
||||
"digest": "sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
|
||||
"sizeBytes": 187563210,
|
||||
"downloadUrl": "https://registry.stella-ops.org/v2/stellaops/web-ui/manifests/sha256:38b225fa7767a5b94ebae4dae8696044126aac429415e93de514d5dd95748dcf",
|
||||
"signatureUrl": "https://downloads.stella-ops.org/signatures/web-ui-2025.10.0-edge.cosign.sig",
|
||||
"sbomUrl": "https://downloads.stella-ops.org/sbom/web-ui-2025.10.0-edge.cdx.json",
|
||||
"attestationUrl": "https://downloads.stella-ops.org/attestations/web-ui-2025.10.0-edge.intoto.jsonl",
|
||||
"docs": ["/docs/install/docker.md", "/docs/security/console-security.md"],
|
||||
"tags": ["console", "ui"]
|
||||
},
|
||||
{
|
||||
"id": "offline.bundle:ouk:2025.10.0-edge",
|
||||
"kind": "offline.bundle",
|
||||
"channel": "edge",
|
||||
"version": "2025.10.0-edge",
|
||||
"digest": "sha256:4f7d2f7a8d0cf4b5f3af689f6c74cd213f4c1b3a1d76d24f6f9f3d9075e51f90",
|
||||
"downloadUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz",
|
||||
"signatureUrl": "https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig",
|
||||
"sbomUrl": "https://downloads.stella-ops.org/offline/offline-manifest-2025.10.0-edge.json",
|
||||
"docs": ["/docs/24_OFFLINE_KIT.md"],
|
||||
"tags": ["offline", "airgap"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Console caches the manifest hash and surfaces differences when a new version lands, helping operators confirm digests drift only when expected.
|
||||
|
||||
---
|
||||
|
||||
## 5 - Download workflows and statuses
|
||||
|
||||
| Status | Applies to | Behaviour |
|
||||
|--------|------------|-----------|
|
||||
| **Ready** | Immutable artefacts (images, Helm/Compose bundles, offline kit) | Commands available immediately. Digest, size, and last verification timestamp display in the table. |
|
||||
| **Pending export** | Async exports queued via `/console/exports` | Shows job owner, scope, and estimated completion time. UI polls every 15 s and updates progress bar. |
|
||||
| **Processing** | Long-running export (evidence bundle, large SBOM) | Drawer shows current stage (`collecting`, `compressing`, `signing`). Operators can cancel if they own the request and hold `downloads.manage`. |
|
||||
| **Delivered** | Completed export within retention window | Provides download links, resume token, and parity snippet for CLI. |
|
||||
| **Expired** | Export past retention or manually expired | Row grays out; clicking opens housekeeping guidance with CLI command to regenerate (`stella runs export --run <id>`). |
|
||||
|
||||
Exports inherit retention defaults defined in policy (`downloads.retentionDays`, min 3, max 30). Operators can override per tenant if they have the appropriate scope.
|
||||
|
||||
---
|
||||
|
||||
## 6 - CLI parity and copy-to-clipboard
|
||||
|
||||
- **Digest pulls:** Each container entry exposes `docker pull <image>@<digest>` and `oras copy <image>@<digest> --to-dir ./downloads` buttons. Commands include architecture hints for multi-platform images.
|
||||
- **Helm/Compose:** Buttons output `helm pull` / `helm install` with the manifest URL and `docker compose --env-file` commands referencing the downloaded bundle.
|
||||
- **Offline kit:** Copy buttons produce the full verification sequence:
|
||||
|
||||
```bash
|
||||
curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz
|
||||
curl -LO https://downloads.stella-ops.org/offline/stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig
|
||||
cosign verify-blob \
|
||||
--key https://stella-ops.org/keys/cosign.pub \
|
||||
--signature stella-ops-offline-kit-2025.10.0-edge.tar.gz.sig \
|
||||
stella-ops-offline-kit-2025.10.0-edge.tar.gz
|
||||
```
|
||||
|
||||
- **Exports:** Drawer lists CLI equivalents (for example, `stella findings export --run <id>`). When the CLI supports resume tokens, the command includes `--resume-token` from the manifest entry.
|
||||
- **Automation:** Webhook tab copies `curl` snippets to subscribe to `/downloads/hooks/subscribe?topic=<artifact>` and includes payload schema for integration tests.
|
||||
|
||||
Parity buttons write commands to the clipboard and display a toast confirming scope hints (for example, `Requires downloads.read + tenant scope`). Accessibility shortcuts (`Shift+D`) trigger the primary copy action for keyboard users.
|
||||
|
||||
---
|
||||
|
||||
## 7 - Offline and air-gap workflow
|
||||
|
||||
- **Manifest sync:** Offline users download `manifest/offline-manifest.json` plus detached JWS and import it via `stella offline kit import`. Console highlights if the offline manifest predates the online manifest by more than 7 days.
|
||||
- **Artefact staging:** The workspace enumerates removable media instructions (export to `./staging/<channel>/`) and warns when artefacts exceed configured media size thresholds.
|
||||
- **Mirrors:** Buttons copy `oras copy` commands that mirror images to an internal registry (`registry.<tenant>.internal`). Operators can toggle `--insecure-policy` if the destination uses custom trust roots.
|
||||
- **Parity checks:** `downloads.offlineParity` flag surfaces the latest parity report verifying that Offline Kit contents match the downloads manifest digests. If diff detected, UI raises a banner linking to remediation steps.
|
||||
- **Audit logging:** Every download command triggered from the UI emits `ui.download.commandCopied` with artifact ID, digest, and tenant. Logs feed the evidence locker so air-gap imports can demonstrate provenance.
|
||||
|
||||
---
|
||||
|
||||
## 8 - Observability and quotas
|
||||
|
||||
| Signal | Source | Description |
|
||||
|--------|--------|-------------|
|
||||
| `ui_download_manifest_refresh_seconds` | Console metrics | Measures time to fetch and verify manifest. Targets < 3 s. |
|
||||
| `ui_download_export_queue_depth` | `/console/downloads` API | Number of pending exports (per tenant). Surfaces as card and Grafana panel. |
|
||||
| `ui_download_command_copied_total` | Console logs | Count of copy actions by artifact type, used to gauge CLI parity adoption. |
|
||||
| `downloads.export.duration` | Export orchestrator | Duration histograms for bundle generation; alerts if P95 > 60 s. |
|
||||
| `downloads.quota.remaining` | Authority quota service | Anonymous users limited to 33 exports/day, verified users 333/day. Banner turns amber at 90 % usage as per platform policy. |
|
||||
|
||||
Telemetry entries include correlation IDs that match backend manifest refresh logs and export job records to keep troubleshooting deterministic.
|
||||
|
||||
---
|
||||
|
||||
## 9 - References
|
||||
|
||||
- `/docs/ui/console-overview.md` - primary shell, tenant controls, SSE ticker.
|
||||
- `/docs/ui/navigation.md` - route ownership and keyboard shortcuts.
|
||||
- `/docs/ui/sbom-explorer.md` - export flows feeding the downloads queue.
|
||||
- `/docs/ui/runs.md` - evidence bundle integration.
|
||||
- `/docs/24_OFFLINE_KIT.md` - offline kit packaging and verification.
|
||||
- `/docs/security/console-security.md` - scopes, CSP, and download token handling (pending).
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence checks (pending).
|
||||
- `deploy/releases/*.yaml` - source of container digests mirrored into the manifest.
|
||||
|
||||
---
|
||||
|
||||
## 10 - Compliance checklist
|
||||
|
||||
- [ ] Manifest schema documented (fields, signature, caching) and sample kept current.
|
||||
- [ ] Artefact categories mapped to manifest entries and parity workflows.
|
||||
- [ ] Download statuses, retention, and cancellation rules explained.
|
||||
- [ ] CLI copy-to-clipboard commands mirror console actions with scope hints.
|
||||
- [ ] Offline/air-gap parity workflow, mirror commands, and audit logging captured.
|
||||
- [ ] Observability metrics and quota signalling documented.
|
||||
- [ ] References cross-linked to adjacent docs (navigation, exports, offline kit).
|
||||
- [ ] Accessibility shortcuts and copy-to-clipboard behaviour noted with compliance reminder.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 23).*
|
||||
179
docs/ui/findings.md
Normal file
179
docs/ui/findings.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# StellaOps Console - Findings
|
||||
|
||||
> **Audience:** Policy Guild, Console UX team, security analysts, customer enablement.
|
||||
> **Scope:** Findings list UX, filters, saved views, explain drawer, exports, CLI parity, real-time updates, and offline considerations for Sprint 23.
|
||||
|
||||
The Findings workspace visualises materialised policy verdicts produced by the Policy Engine. It lets analysts triage affected components, inspect explain traces, compare policy views, and export evidence while respecting Aggregation-Only guardrails.
|
||||
|
||||
---
|
||||
|
||||
## 1. Access and prerequisites
|
||||
|
||||
- **Route:** `/console/findings` with optional panel parameters (e.g., `/console/findings?panel=explain&finding=<id>`).
|
||||
- **Scopes:** `findings.read` (list), `policy:runs` (view run metadata), `policy:simulate` (stage simulations), `downloads.read` (export bundles).
|
||||
- **Prerequisites:** Policy Engine v2 (`policy_run` and `effective_finding_*` endpoints), Concelier/Excititor feeds for provenance, SBOM Service for component metadata.
|
||||
- **Feature flags:** `findings.explain.enabled`, `findings.savedViews.enabled`, `findings.simulationDiff.enabled`.
|
||||
- **Tenancy:** All queries include tenant context; cross-tenant comparisons require explicit admin scope and render split-pane view.
|
||||
|
||||
---
|
||||
|
||||
## 2. Layout overview
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------------+
|
||||
| Header: Tenant badge - policy selector - global filters - actions |
|
||||
+-------------------------------------------------------------------+
|
||||
| Top row cards: Affected assets - Critical count - KEV count |
|
||||
+-------------------------------------------------------------------+
|
||||
| Findings grid (virtualised) |
|
||||
| Columns: Status | Severity | Component | Policy | Source | Age |
|
||||
| Row badges: KEV, Quieted, Override, Simulation only |
|
||||
+-------------------------------------------------------------------+
|
||||
| Right drawer / full view tabs: Summary | Explain | Evidence | Run |
|
||||
+-------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
The policy selector includes Active, Staged, and Simulation snapshots. Switching snapshots triggers diff banners to highlight changes.
|
||||
|
||||
---
|
||||
|
||||
## 3. Filters and saved views
|
||||
|
||||
| Filter | Description | Notes |
|
||||
|--------|-------------|-------|
|
||||
| **Status** | `affected`, `at_risk`, `quieted`, `fixed`, `not_applicable`, `mitigated`. | Status definitions align with Policy Engine taxonomy. |
|
||||
| **Severity** | Critical, High, Medium, Low, Informational, Untriaged. | Derived from policy scoring; UI displays numeric score tooltip. |
|
||||
| **KEV** | Toggle to show only Known Exploited Vulnerabilities. | Pulls from Concelier enrichment. |
|
||||
| **Policy** | Active, Staged, Simulation snapshots. | Simulation requires recent run; otherwise greyed out. |
|
||||
| **Component** | PURL or substring search. | Autocomplete draws from current tenant findings. |
|
||||
| **SBOM** | Filter by image digest or SBOM ID. | Includes quick links to SBOM Explorer. |
|
||||
| **Tag** | Team or environment tags emitted by Policy Engine (`tags[]`). | Supports multi-select. |
|
||||
| **Run window** | `Last 24h`, `Last 7d`, `Custom range`. | Applies to run timestamp. |
|
||||
| **Explain hints** | Filter by explain artefact (rule ID, justification, VEX provider). | Uses server-side filter parameters. |
|
||||
|
||||
Saved views persist filter combinations per tenant and policy. Users can mark views as shared; shared views appear in the left rail with owner and last updated timestamp. Keyboard shortcuts align with global presets (`Cmd+1-9 / Ctrl+1-9`).
|
||||
|
||||
---
|
||||
|
||||
## 4. Findings grid
|
||||
|
||||
| Column | Details |
|
||||
|--------|---------|
|
||||
| **Status** | Badge with tooltip describing resolution path (e.g., "Affected - blocked by policy rule R-105"). Quieted findings show a muted badge with expiry. |
|
||||
| **Severity** | Numeric score and label. Hover reveals scoring formula and evidence sources. |
|
||||
| **Component** | PURL plus human-friendly name. Includes SBOM badge linking to SBOM Explorer detail. |
|
||||
| **Policy** | Policy name + revision digest; clicking opens policy diff in new tab. |
|
||||
| **Source signals** | Icons for VEX, Advisory, Runtime overlays. Hover shows counts and last updated timestamps. |
|
||||
| **Age** | Time since finding was last evaluated; colour-coded when exceeding SLA. |
|
||||
|
||||
Row indicators:
|
||||
|
||||
- **KEV** badge when Concelier marks the vulnerability as exploited.
|
||||
- **Override** badge when policy override or exemption applied.
|
||||
- **Simulation only** badge when viewing simulation snapshot; warns that finding is not yet active.
|
||||
- **Determinism alert** icon if latest run reported a determinism mismatch (links to run detail).
|
||||
|
||||
Bulk actions (multi-select):
|
||||
|
||||
- `Open explains` (launch explain drawer for up to 10 findings).
|
||||
- `Export CSV/JSON`.
|
||||
- `Copy CLI` commands for batch explains (`stella findings explain --batch file`).
|
||||
- `Create ticket` (integrates with integrations configured under Admin).
|
||||
|
||||
---
|
||||
|
||||
## 5. Explain drawer
|
||||
|
||||
Tabs inside the explain drawer:
|
||||
|
||||
1. **Summary** - status, severity, policy decision, rule ID, last evaluated timestamp, SBOM link, run ID.
|
||||
2. **Rule chain** - ordered list of policy rules triggered; each entry shows rule ID, name, action (block/warn/quiet), score contribution, and condition snippet.
|
||||
3. **Evidence** - references to Concelier advisories, Excititor consensus, runtime signals, and overrides. Evidence entries link to their respective explorers.
|
||||
4. **VEX impact** - table of VEX claims considered; displays provider, status, justification, acceptance (accepted/ignored), weight.
|
||||
5. **History** - timeline of state transitions (affected -> quieted -> mitigated) with timestamps and operators (if override applied).
|
||||
6. **Raw trace** - canonical JSON trace from Policy Engine (read-only). CLI parity snippet:
|
||||
- `stella findings explain --policy <id> --finding <key> --format json`.
|
||||
|
||||
Explain drawer includes copy-to-clipboard buttons for rule chain and evidence JSON to support audit workflows. When sealed mode is active, a banner highlights which evidence was sourced from cached data.
|
||||
|
||||
---
|
||||
|
||||
## 6. Simulations and comparisons
|
||||
|
||||
- Simulation toggle lets analysts compare Active vs Staged/Sandbox policies.
|
||||
- Diff banner summarises added, removed, and changed findings.
|
||||
- Side-by-side view shows baseline vs simulation verdicts with change badges (`added`, `removed`, `severity up`, `severity down`).
|
||||
- CLI parity callout: `stella policy simulate --policy <id> --sbom <sbomId> --format diff`.
|
||||
- Simulation results persist for 7 days; stale simulations prompt re-run recommendation.
|
||||
|
||||
---
|
||||
|
||||
## 7. Exports and automation
|
||||
|
||||
- Immediate exports: CSV, JSON, Markdown summary for selected findings.
|
||||
- Scheduled exports: asynchronous job to generate full tenant report (JSON + CSV) with manifest digests.
|
||||
- Explain bundle export packages traces for a set of findings; includes manifest and hash for offline review.
|
||||
- CLI parity:
|
||||
- `stella findings ls --policy <id> --format json --output findings.json`
|
||||
- `stella findings export --policy <id> --format csv --output findings.csv`
|
||||
- `stella findings explain --batch batch.txt --output explains/`
|
||||
- Automation: webhook copy button for `/downloads/hooks/subscribe?topic=findings.report.ready`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Real-time updates and observability
|
||||
|
||||
- SSE channel `/console/findings/stream` pushes new findings, status changes, and quieted expirations; UI animates affected rows.
|
||||
- Header cards show metrics: `findings_critical_total`, `findings_quieted_total`, `findings_kev_total`.
|
||||
- Run ticker lists latest policy runs with status, duration, determinism hash.
|
||||
- Error banners include correlation IDs linking to Policy Engine run logs.
|
||||
- Metrics drill-down links to dashboards (OpenTelemetry, Prometheus).
|
||||
|
||||
---
|
||||
|
||||
## 9. Offline and air-gap behaviour
|
||||
|
||||
- Offline banner indicates snapshot ID and timestamp used for findings.
|
||||
- Explain drawer notes when evidence references offline bundles; suggests importing updated advisories/VEX to refresh results.
|
||||
- Exports default to local storage paths; UI provides manual transfer instructions.
|
||||
- CLI examples switch to include `--sealed` or `--offline` flags.
|
||||
- Tenant selector hides tenants without corresponding offline findings data to avoid partial views.
|
||||
|
||||
---
|
||||
|
||||
## 10. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- Coordinate with Console Guild (Slack `#console-screenshots`, entry 2025-10-26) to capture updated light and dark theme shots before release.
|
||||
|
||||
---
|
||||
|
||||
## 11. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - shell, filters, tenant model.
|
||||
- `/docs/ui/navigation.md` - route list, deep-link schema.
|
||||
- `/docs/ui/advisories-and-vex.md` - advisory and VEX context feeding findings.
|
||||
- `/docs/ui/policies.md` (pending) - editor and policy lifecycle.
|
||||
- `/docs/policy/overview.md` - Policy Engine outputs.
|
||||
- `/docs/policy/runs.md` - run orchestration.
|
||||
- `/docs/cli/policy.md` - CLI parity for findings commands.
|
||||
|
||||
---
|
||||
|
||||
## 12. Compliance checklist
|
||||
|
||||
- [ ] Filters and saved view behaviour documented with CLI alignment.
|
||||
- [ ] Findings grid columns, badges, and bulk actions captured.
|
||||
- [ ] Explain drawer walkthrough includes rule chain, evidence, and raw trace.
|
||||
- [ ] Simulation diff behaviour and CLI callouts described.
|
||||
- [ ] Exports (immediate and scheduled) plus webhook integration covered.
|
||||
- [ ] Real-time updates, metrics, and error correlation documented.
|
||||
- [ ] Offline behaviour and screenshot coordination noted.
|
||||
- [ ] References validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
|
||||
163
docs/ui/navigation.md
Normal file
163
docs/ui/navigation.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# StellaOps Console - Navigation
|
||||
|
||||
> **Audience:** Console UX writers, UI engineers, QA, and enablement teams.
|
||||
> **Scope:** Primary route map, layout conventions, keyboard shortcuts, deep-link patterns, and tenant context switching for the StellaOps Console (Sprint 23).
|
||||
|
||||
The navigation framework keeps Console workflows predictable across tenants and deployment modes. This guide explains how the global shell, feature routes, and context tokens cooperate so operators can jump between findings, SBOMs, advisories, policies, and runs without losing scope.
|
||||
|
||||
---
|
||||
|
||||
## 1. Information Architecture
|
||||
|
||||
### 1.1 Primary routes
|
||||
|
||||
| Route pattern | Module owner | Purpose | Required scopes (minimum) | Core services |
|
||||
|---------------|--------------|---------|---------------------------|---------------|
|
||||
| `/console/dashboard` | Web gateway | Landing KPIs, feed age, queue depth, alerts | `ui.read` | Web, Scheduler WebService, Concelier WebService, Excititor WebService |
|
||||
| `/console/findings` | Policy Engine | Aggregated findings, explain drawer, export | `findings.read` | Policy Engine, Concelier WebService, SBOM Service |
|
||||
| `/console/sbom` | SBOM Service | Catalog view, component graph, overlays | `sbom.read` | SBOM Service, Policy Engine (overlays) |
|
||||
| `/console/advisories` | Concelier | Advisory aggregation with provenance banners | `advisory.read` | Concelier WebService |
|
||||
| `/console/vex` | Excititor | VEX aggregation, consensus, conflicts | `vex.read` | Excititor WebService |
|
||||
| `/console/runs` | Scheduler | Run list, live progress, evidence downloads | `runs.read` | Scheduler WebService, Policy Engine, Scanner WebService |
|
||||
| `/console/policies` | Policy Engine | Editor, simulations, approvals | `policy.read` (read) / `policy.write` (edit) | Policy Engine, Authority |
|
||||
| `/console/downloads` | DevOps | Signed artifacts, Offline Kit parity checklist | `downloads.read` | DevOps manifest API, Offline Kit |
|
||||
| `/console/admin` | Authority | Tenants, roles, tokens, integrations | `ui.admin` (plus scoped `authority:*`) | Authority |
|
||||
| `/console/help` | Docs Guild | Guides, tours, release notes | `ui.read` | Docs static assets |
|
||||
|
||||
### 1.2 Secondary navigation elements
|
||||
|
||||
- **Left rail:** highlights the active top-level route, exposes quick metrics, and shows pinned saved views. Keyboard focus cycles through rail entries with `Tab`/`Shift+Tab`.
|
||||
- **Breadcrumb bar:** renders `Home / Module / Detail` format. Detail crumbs include IDs and titles for shareable context (for example, `Findings / High Severity / CVE-2025-1234`).
|
||||
- **Action shelf:** right-aligned controls for context actions (export, verify, retry). Buttons disable automatically if the current subject lacks the requisite scope.
|
||||
|
||||
---
|
||||
|
||||
## 2. Command Palette and Search
|
||||
|
||||
- **Trigger:** `Ctrl/Cmd + K`. Palette opens in place, keeps focus, and announces results via ARIA live region.
|
||||
- **Capabilities:** jump to routes, saved views, tenants, recent entities (findings, SBOMs, advisories), and command actions (for example, "Start verification", "Open explain drawer").
|
||||
- **Result tokens:** palette entries carry metadata (`type`, `tenant`, `filters`). Selecting an item updates the URL and applies stored filters without a full reload.
|
||||
- **Offline fallback:** in sealed/offline mode, palette restricts actions to cached routes and saved views; remote-only items show a grayed-out badge.
|
||||
|
||||
---
|
||||
|
||||
## 3. Global Filters and Context Chips
|
||||
|
||||
| Control | Shortcut | Persistence | Notes |
|
||||
|---------|----------|-------------|-------|
|
||||
| **Tenant picker** | `Ctrl/Cmd + T` | SessionStorage + URL `tenant` query | Issues fresh Authority token, invalidates caches, emits `ui.tenant.switch` log. |
|
||||
| **Filter tray** | `Shift + F` | IndexedDB (per tenant) + URL query (`since`, `severity`, `tags`, `source`, `status`, `policyView`) | Applies instantly to compatible routes; incompatible filters show a reset suggestion. |
|
||||
| **Component search** | `/` when filters closed | URL `component` query | Context-aware; scopes results to current tenant and module. |
|
||||
| **Time window** | `Ctrl/Cmd + Shift + 1-4` | URL `since`/`until`, palette preset | Mapped to preset windows: 24 h, 7 d, 30 d, custom. |
|
||||
|
||||
Context chips appear beneath page titles summarising active filters (for example, `Tenant: west-prod`, `Severity: Critical+High`, `Time: Last 7 days`). Removing a chip updates the tray and URL atomically.
|
||||
|
||||
---
|
||||
|
||||
## 4. Keyboard Shortcut Matrix
|
||||
|
||||
| Scope | Shortcut (Mac / Windows) | Action | Notes |
|
||||
|-------|--------------------------|--------|-------|
|
||||
| Global | `Cmd+K / Ctrl+K` | Open command palette | Accessible from any route except modal dialogs. |
|
||||
| Global | `Cmd+T / Ctrl+T` | Open tenant switcher | Requires `ui.read`. Confirm selection with `Enter`; `Esc` cancels without switching. |
|
||||
| Global | `Shift+F` | Toggle global filter tray | Focus lands on first filter control. |
|
||||
| Global | `Cmd+1-9 / Ctrl+1-9` | Load saved view preset | Each preset bound per tenant; non-assigned keys show tooltip. |
|
||||
| Global | `?` | Show keyboard reference overlay | Overlay lists context-specific shortcuts; closes with `Esc`. |
|
||||
| Findings module | `Cmd+/ / Ctrl+/` | Focus explain search | Works when explain drawer is open. |
|
||||
| SBOM module | `Cmd+G / Ctrl+G` | Toggle graph overlays | Persists per session. |
|
||||
| Advisories & VEX | `Cmd+Opt+F / Ctrl+Alt+F` | Focus provider filter | Highlights provider chip strip. |
|
||||
| Runs module | `Cmd+R / Ctrl+R` | Refresh SSE snapshot | Schedules soft refresh (no hard reload). |
|
||||
| Policies module | `Cmd+S / Ctrl+S` | Save draft (if edit rights) | Mirrors Policy Editor behaviour. |
|
||||
|
||||
Shortcut handling follows WCAG 2.2 best practices: all accelerators are remappable via Settings -> Accessibility -> Keyboard shortcuts, and the overlay documents platform differences.
|
||||
|
||||
---
|
||||
|
||||
## 5. Deep-Link Patterns
|
||||
|
||||
### 5.1 URL schema
|
||||
|
||||
Console URLs adopt the format:
|
||||
|
||||
```
|
||||
/console/<route>[/:id][/:tab]?tenant=<slug>&since=<iso>&severity=<list>&view=<token>&panel=<drawer>&component=<purl>
|
||||
```
|
||||
|
||||
- **`tenant`** is mandatory and matches Authority slugs (e.g., `acme-prod`).
|
||||
- **`since` / `until`** use ISO-8601 timestamps (UTC). Preset ranges set only `since`; UI computes `until` on load.
|
||||
- **`severity`** accepts comma-separated policy buckets (e.g., `critical,high,kev`).
|
||||
- **`view`** stores module-specific state (e.g., `sbomView=usage`, `findingsPreset=threat-hunting`).
|
||||
- **`panel`** selects drawers or tabs (`panel=explain`, `panel=timeline`).
|
||||
|
||||
### 5.2 Copyable links
|
||||
|
||||
- Share links from the action shelf or context chips; both copy canonical URLs with all active filters.
|
||||
- CLI parity: inline callouts provide `stella` commands derived from the URL parameters to ensure console/CLI equivalence.
|
||||
- Offline note: links copied in sealed mode include the snapshot ID (`snapshot=<hash>`) so recipients know which offline data set to load.
|
||||
|
||||
### 5.3 Examples
|
||||
|
||||
- **`since` / `until`** use ISO-8601 timestamps (UTC). Preset ranges set only `since`; UI computes `until` on load.
|
||||
- **`severity`** accepts comma-separated policy buckets (e.g., `critical,high,kev`).
|
||||
- **`view`** stores module-specific state (e.g., `sbomView=usage`, `findingsPreset=threat-hunting`).
|
||||
- **`panel`** selects drawers or tabs (`panel=explain`, `panel=timeline`).
|
||||
- **`component`** encodes package selection using percent-encoded PURL syntax.
|
||||
- **`snapshot`** appears when copying links offline to reference Offline Kit build hash.
|
||||
@@
|
||||
| Use case | Example URL | Description |
|
||||
|----------|-------------|-------------|
|
||||
| Findings triage | `/console/findings?v=table&severity=critical,high&tenant=west-prod&since=2025-10-20T00:00:00Z` | Opens the findings table limited to critical/high for west-prod, last 7 days. |
|
||||
| SBOM component focus | `/console/sbom/sha256:abcd?tenant=west-prod&component=pkg:npm/react@18.3.0&view=usage` | Deep-links to a specific image digest and highlights an NPM package in Usage view. |
|
||||
| Advisory explain | `/console/advisories?tenant=west-prod&source=nvd&panel=detail&documentId=CVE-2025-1234` | Opens advisory list filtered to NVD and expands CVE detail drawer. |
|
||||
| Run monitor | `/console/runs/42?tenant=west-prod&panel=progress` | Focuses run ID 42 with progress drawer active (SSE stream attached). |
|
||||
|
||||
---
|
||||
|
||||
## 6. Tenant Switching Lifecycle
|
||||
|
||||
1. **Initiate:** User triggers `Ctrl/Cmd + T` or clicks the tenant badge. Switcher modal lists authorised tenants and recent selections.
|
||||
2. **Preview:** Selecting a tenant shows summary (environment, last snapshot, role coverage). The modal flags tenants missing required scopes for the current route.
|
||||
3. **Confirm:** On confirmation, the UI requests a new DPoP-bound access token from Authority (`aud=console`, `tenant=<id>`).
|
||||
4. **Invalidate caches:** Stores keyed by tenant purge automatically; modules emit `tenantChanged` events so in-flight SSE streams reconnect with new headers.
|
||||
5. **Restore state:** Global filters reapply where valid. Incompatible filters (for example, a saved view unavailable in the new tenant) prompt users to pick a fallback.
|
||||
6. **Audit and telemetry:** `ui.tenant.switch` log writes subject, from/to tenant, correlation ID. Metric `ui_tenant_switch_total` increments for observability dashboards.
|
||||
7. **Offline behaviour:** If the target tenant is absent from the offline snapshot, switcher displays guidance to import updated Offline Kit data before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## 7. Breadcrumbs, Tabs, and Focus Management
|
||||
|
||||
- Breadcrumb titles update synchronously with route data loads. When fragments change (for example, selecting a finding), the breadcrumb text updates without pushing a new history entry to keep back/forward predictable.
|
||||
- Detail views rely on accessible tabs (`role="tablist"`) with keyboard support (`ArrowLeft/Right`). Tab selection updates the URL `tab` parameter for deep linking.
|
||||
- Focus management:
|
||||
- Route changes send focus to the primary heading (`h1`) using the live region announcer.
|
||||
- Opening drawers or modals traps focus until closed; ESC returns focus to the triggering element.
|
||||
- Keyboard-only navigation is validated via automated Playwright accessibility checks as part of `DEVOPS-CONSOLE-23-001`.
|
||||
|
||||
---
|
||||
|
||||
## 8. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - structural overview, tenant model, global filters.
|
||||
- `/docs/ui/sbom-explorer.md` - SBOM-specific navigation and graphs (pending).
|
||||
- `/docs/ui/advisories-and-vex.md` - aggregation UX details (pending).
|
||||
- `/docs/ui/findings.md` - findings filters and explain drawer (pending).
|
||||
- `/docs/security/console-security.md` - Authority, scopes, CSP.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence matrix.
|
||||
- `/docs/accessibility.md` - keyboard remapping, WCAG validation checklists.
|
||||
|
||||
---
|
||||
|
||||
## 9. Compliance Checklist
|
||||
|
||||
- [ ] Route table matches Console build (paths, scopes, owners verified with Console Guild).
|
||||
- [ ] Keyboard shortcut matrix reflects implemented accelerators and accessibility overlay.
|
||||
- [ ] Deep-link examples tested for copy/share parity and CLI alignment.
|
||||
- [ ] Tenant switching flow documents cache invalidation and audit logging.
|
||||
- [ ] Filter tray, command palette, and presets cross-referenced with accessibility guidance.
|
||||
- [ ] Offline/air-gap notes included for palette, tenant switcher, and deep-link metadata.
|
||||
- [ ] Links to dependent docs (`/docs/ui/*`, `/docs/security/*`) validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
191
docs/ui/policies.md
Normal file
191
docs/ui/policies.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# StellaOps Console - Policies Workspace
|
||||
|
||||
> **Audience:** Policy Guild, Console UX, product ops, review leads.
|
||||
> **Scope:** Policy workspace navigation, editor surfaces, simulation, approvals, RBAC, observability, offline behaviour, and CLI parity for Sprint 23.
|
||||
|
||||
The Policies workspace centralises authoring, simulation, review, and promotion for `stella-dsl@1` packs. It builds on the Policy Editor (`docs/ui/policy-editor.md`) and adds list views, governance workflows, and integrations with runs and findings.
|
||||
|
||||
---
|
||||
|
||||
## 1. Access and prerequisites
|
||||
|
||||
- **Routes:**
|
||||
- `/console/policies` (list)
|
||||
- `/console/policies/:policyId` (details)
|
||||
- `/console/policies/:policyId/:revision` (editor, approvals, runs)
|
||||
- **Scopes:**
|
||||
- `policy:read` (list and details)
|
||||
- `policy:write` (edit drafts, run lint/compile)
|
||||
- `policy:submit`, `policy:review`, `policy:approve` (workflow actions)
|
||||
- `policy:runs` (view run history)
|
||||
- `policy:simulate` (run simulations)
|
||||
- `effective:write` (promotion visibility only; actual write remains server-side)
|
||||
- **Feature flags:** `policy.studio.enabled`, `policy.simulation.diff`, `policy.runCharts.enabled`, `policy.offline.bundleUpload`.
|
||||
- **Dependencies:** Policy Engine v2 APIs (`/policies`, `/policy/runs`, `/policy/simulations`), Policy Studio Monaco assets, Authority fresh-auth flows for critical operations.
|
||||
|
||||
---
|
||||
|
||||
## 2. List and detail views
|
||||
|
||||
### 2.1 Policy list
|
||||
|
||||
| Column | Description |
|
||||
|--------|-------------|
|
||||
| **Policy** | Human-readable name plus policy ID (e.g., `P-7`). |
|
||||
| **State** | `Active`, `Draft`, `Staged`, `Simulation`, `Archived`. Badge colours align with Policy Engine status. |
|
||||
| **Revision** | Latest revision digest (short SHA). |
|
||||
| **Owner** | Primary maintainer or owning team tag. |
|
||||
| **Last change** | Timestamp and actor of last update (edit, submit, approve). |
|
||||
| **Pending approvals** | Count of outstanding approval requests (with tooltip listing reviewers). |
|
||||
|
||||
Row actions: `Open`, `Duplicate`, `Export pack`, `Run simulation`, `Compare revisions`.
|
||||
|
||||
Filters: owning team, state, tag, pending approvals, contains staged changes, last change window, simulation warnings (determinism, failed run).
|
||||
|
||||
### 2.2 Policy detail header
|
||||
|
||||
- Summary cards: current state, digest, active revision, staged revision (if any), simulation status, last production run (timestamp, duration, determinism hash).
|
||||
- Action bar: `Edit draft`, `Run simulation`, `Submit for review`, `Promote`, `Export pack`, `View findings`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Editor shell
|
||||
|
||||
The editor view reuses the structure documented in `/docs/ui/policy-editor.md` and adds:
|
||||
|
||||
- **Context banner** showing tenant, policy ID, revision digest, and simulation badge if editing sandbox copy.
|
||||
- **Lint and compile status** displayed inline with time since last run.
|
||||
- **Checklist sidebar** summarising required steps (lint pass, simulation run, deterministic CI, security review). Each item links to evidence (e.g., latest simulation diff).
|
||||
- **Monaco integration** with policy-specific snippets, schema hover, code actions (`Insert allowlist`, `Add justification`).
|
||||
- **Draft autosave** every 30 seconds with conflict detection (merges disabled; last write wins with warning).
|
||||
|
||||
---
|
||||
|
||||
## 4. Simulation workflows
|
||||
|
||||
- Simulation modal accepts SBOM filter (golden set, specific SBOM IDs, tenant-wide) and options for VEX weighting overrides.
|
||||
- Simulations run asynchronously; progress shown in run ticker with status updates.
|
||||
- Diff view summarises totals: affected findings added/removed, severity up/down counts, quieted changes.
|
||||
- Side-by-side diff (Active vs Simulation) accessible directly from policy detail.
|
||||
- Export options: JSON diff, Markdown summary, CLI snippet `stella policy simulate --policy <id> --sbom <sbomId>`.
|
||||
- Simulation results cached per draft revision. Cache invalidates when draft changes or SBOM snapshot updates.
|
||||
- Simulation compliance card requires at least one up-to-date simulation before submission.
|
||||
|
||||
---
|
||||
|
||||
## 5. Review and approval
|
||||
|
||||
- **Review requests:** Authors tag reviewers; review sidebar lists pending reviewers, due dates, and escalation contact.
|
||||
- **Comments:** Threaded comments support markdown, mentions, and attachments (redacted before persistence). Comment resolution required before approval.
|
||||
- **Approval checklist:**
|
||||
- Lint/compile success
|
||||
- Simulation fresh (within configured SLA)
|
||||
- Determinism verification passed
|
||||
- Security review (if flagged)
|
||||
- Offline bundle prepared (optional)
|
||||
- **Fresh-auth:** Approve/promote buttons require fresh authentication; modal prompts for credentials and enforces short-lived token (<5 minutes).
|
||||
- **Approval audit:** Approval events recorded with correlation ID, digests, reviewer note, effective date, and optional ticket link.
|
||||
|
||||
---
|
||||
|
||||
## 6. Promotion and rollout
|
||||
|
||||
- Promotion dialog summarises staged changes, target tenants, release windows, and run plan (full vs incremental).
|
||||
- Operators can schedule promotion or apply immediately.
|
||||
- Promotion triggers Policy Engine to materialise new revision; console reflects status and shows run progress.
|
||||
- CLI parity: `stella policy promote --policy <id> --revision <rev> --run-mode full`.
|
||||
- Rollback guidance accessible from action bar (`Open rollback instructions`) linking to CLI command and documentation.
|
||||
|
||||
---
|
||||
|
||||
## 7. Runs and observability
|
||||
|
||||
- Runs tab displays table of recent runs with columns: run ID, type (`full`, `incremental`, `simulation`), duration, determinism hash, findings delta counts, triggered by.
|
||||
- Charts: findings trend, quieted findings trend, rule hit heatmap (top rules vs recent runs).
|
||||
- Clicking a run opens run detail drawer showing inputs (policy digest, SBOM batch hash, advisory snapshot hash), output summary, and explain bundle download.
|
||||
- Error runs display red badge; detail drawer includes correlation ID and link to Policy Engine logs.
|
||||
- SSE updates stream run status changes to keep UI real-time.
|
||||
|
||||
---
|
||||
|
||||
## 8. RBAC and governance
|
||||
|
||||
| Role | Scopes | Capabilities |
|
||||
|------|--------|--------------|
|
||||
| **Author** | `policy:read`, `policy:write`, `policy:simulate` | Create drafts, run lint/simulations, comment. |
|
||||
| **Reviewer** | `policy:read`, `policy:review`, `policy:simulate` | Leave review comments, request changes. |
|
||||
| **Approver** | `policy:read`, `policy:approve`, `policy:runs`, `policy:simulate` | Approve/promote, trigger runs, view run history. |
|
||||
| **Operator** | `policy:read`, `policy:runs`, `policy:simulate`, `effective:write` | Schedule promotions, monitor runs (no editing). |
|
||||
| **Admin** | Above plus Authority admin scopes | Manage roles, configure escalation chains. |
|
||||
|
||||
UI disables controls not allowed by current scope and surfaces tooltip with required scope names. Audit log captures denied attempts (`policy.ui.action_denied`).
|
||||
|
||||
---
|
||||
|
||||
## 9. Exports and offline bundles
|
||||
|
||||
- `Export pack` button downloads policy pack (zip) with metadata, digest manifest, and README.
|
||||
- Offline bundle uploader allows importing reviewed packs; UI verifies signatures and digests before applying.
|
||||
- Explain bundle export collects latest run explain traces for audit.
|
||||
- CLI parity:
|
||||
- `stella policy export --policy <id> --revision <rev>`
|
||||
- `stella policy bundle import --file <bundle>`
|
||||
- `stella policy bundle export --policy <id> --revision <rev>`
|
||||
- Offline mode displays banner and disables direct promotion; provides script instructions for offline runner.
|
||||
|
||||
---
|
||||
|
||||
## 10. Observability and alerts
|
||||
|
||||
- Metrics cards show `policy_run_seconds`, `policy_rules_fired_total`, `policy_determinism_failures_total`.
|
||||
- Alert banners surfaced for determinism failures, simulation stale warnings, approval SLA breaches.
|
||||
- Links to dashboards (Grafana) pre-filtered with policy ID.
|
||||
- Telemetry panel lists last emitted events (policy.promoted, policy.simulation.completed).
|
||||
|
||||
---
|
||||
|
||||
## 11. Offline and air-gap considerations
|
||||
|
||||
- In sealed mode, editor warns about cached enrichment data; simulation run button adds tooltip explaining degraded evidence.
|
||||
- Promotions queue and require manual CLI execution on authorised host; UI provides downloadable job manifest.
|
||||
- Run charts switch to snapshot data; SSE streams disabled, replaced by manual refresh button.
|
||||
- Export/download buttons label file paths for removable media transfer.
|
||||
|
||||
---
|
||||
|
||||
## 12. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- ``
|
||||
- Coordinate with Console Guild via `#console-screenshots` (entry 2025-10-26) to replace placeholders once UI captures are ready (light and dark themes).
|
||||
|
||||
---
|
||||
|
||||
## 13. References
|
||||
|
||||
- `/docs/ui/policy-editor.md` - detailed editor mechanics.
|
||||
- `/docs/ui/findings.md` - downstream findings view and explain drawer.
|
||||
- `/docs/policy/overview.md` and `/docs/policy/runs.md` - Policy Engine contracts.
|
||||
- `/docs/security/authority-scopes.md` - scope definitions.
|
||||
- `/docs/cli/policy.md` - CLI commands for policy management.
|
||||
- `/docs/ui/console-overview.md` - navigation shell and filters.
|
||||
|
||||
---
|
||||
|
||||
## 14. Compliance checklist
|
||||
|
||||
- [ ] Policy list and detail workflow documented (columns, filters, actions).
|
||||
- [ ] Editor shell extends Policy Studio guidance with checklists and lint/simulation integration.
|
||||
- [ ] Simulation flow, diff presentation, and CLI parity captured.
|
||||
- [ ] Review, approval, and promotion workflows detailed with scope gating.
|
||||
- [ ] Runs dashboard, metrics, and SSE behaviour described.
|
||||
- [ ] Exports and offline bundle handling included.
|
||||
- [ ] Offline/air-gap behaviour and screenshot coordination recorded.
|
||||
- [ ] References validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
|
||||
178
docs/ui/policy-editor.md
Normal file
178
docs/ui/policy-editor.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# Policy Editor Workspace
|
||||
|
||||
> **Audience:** Product/UX, UI engineers, policy authors/reviewers using the Console.
|
||||
> **Scope:** Layout, features, RBAC, a11y, simulation workflow, approvals, run dashboards, and offline considerations for the Policy Engine v2 editor (“Policy Studio”).
|
||||
|
||||
The Policy Editor is the primary Console workspace for composing, simulating, and approving `stella-dsl@1` policies. It combines Monaco-based editing, diff visualisations, and governance tools so authors and reviewers can collaborate without leaving the browser.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Access & Prerequisites
|
||||
|
||||
- **Routes:** `/console/policy` (list) → `/console/policy/:policyId/:version?`.
|
||||
- **Scopes:**
|
||||
- `policy:write` to edit drafts, run lint/compile, attach simulations.
|
||||
- `policy:submit` / `policy:review` / `policy:approve` for workflow actions.
|
||||
- `policy:run` to trigger runs, `policy:runs` to inspect history.
|
||||
- `findings:read` to open explain drawers.
|
||||
- **Feature flags:** `policyStudio.enabled` (defaults true once Policy Engine v2 API available).
|
||||
- **Browser support:** Evergreen Chrome, Edge, Firefox, Safari (last two versions). Uses WASM OPA sandbox; ensure COOP/COEP enabled per [UI architecture](../ARCHITECTURE_UI.md).
|
||||
|
||||
---
|
||||
|
||||
## 2 · Workspace Layout
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Header: Policy selector • tenant switch • last activation banner │
|
||||
├────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Sidebar (left) │ Main content (right) │
|
||||
│ - Revision list │ ┌───────────── Editor tabs ───────────────┐ │
|
||||
│ - Checklist status │ │ DSL │ Simulation │ Approvals │ ... │ │
|
||||
│ - Pending reviews │ └─────────────────────────────────────────┘ │
|
||||
│ - Run backlog │ │
|
||||
│ │ Editor pane / Simulation diff / Run viewer │
|
||||
└────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- **Sidebar:** Revision timeline (draft, submitted, approved), compliance checklist cards, outstanding review requests, run backlog (incremental queue depth and SLA).
|
||||
- **Editor tabs:**
|
||||
- *DSL* (primary Monaco editor)
|
||||
- *Simulation* (pre/post diff charts)
|
||||
- *Approvals* (comments, audit log)
|
||||
- *Runs* (heatmap dashboards)
|
||||
- *Explain Explorer* (optional drawer for findings)
|
||||
- **Right rail:** context cards for VEX providers, policy metadata, quick links to CLI/API docs.
|
||||
|
||||
> Placeholder screenshot: `` (add after UI team captures latest build).
|
||||
|
||||
---
|
||||
|
||||
## 3 · Editing Experience
|
||||
|
||||
- Monaco editor configured for `stella-dsl@1`:
|
||||
- Syntax highlighting, IntelliSense for rule/action names, snippets for common patterns.
|
||||
- Inline diagnostics sourced from `/policies/{id}/lint` and `/compile`.
|
||||
- Code actions (“Fix indentation”, “Insert requireVex block”).
|
||||
- Mini-map disabled by default to reduce contrast noise; toggle available.
|
||||
- **Keyboard shortcuts (accessible via `?`):**
|
||||
- `Ctrl/Cmd + S` – Save draft (uploads to API if changed).
|
||||
- `Ctrl/Cmd + Shift + Enter` – Run lint + compile.
|
||||
- `Ctrl/Cmd + Shift + D` – Open diff view vs baseline.
|
||||
- `Alt + Shift + F` – Format document (canonical ordering).
|
||||
- **Schema tooltips:** Hover on `profile`, `rule`, `action` to view documentation (sourced from DSL doc).
|
||||
- **Offline warnings:** When `sealed` mode detected, banner reminds authors to validate with offline bundle.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Simulation & Diff Panel
|
||||
|
||||
- Triggered via “Run simulation” (toolbar) or automatically after compile.
|
||||
- Displays:
|
||||
- **Summary cards:** total findings added/removed/unchanged; severity up/down counts.
|
||||
- **Rule hit table:** top rules contributing to diffs with percentage change.
|
||||
- **Component list:** virtualised table linking to explain drawer; supports filters (severity, status, VEX outcome).
|
||||
- **Visualisations:** stacked bar chart (severity deltas), sparkline for incremental backlog impact.
|
||||
- Supports run presets:
|
||||
- `Golden SBOM set` (default)
|
||||
- Custom SBOM selection (via multi-select and search)
|
||||
- Import sample JSON from CLI (`Upload diff`).
|
||||
- Diff export options:
|
||||
- `Download JSON` (same schema as CLI output)
|
||||
- `Copy as Markdown` for review comments
|
||||
- Simulation results persist per draft version; history accessible via timeline.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Review & Approval Workflow
|
||||
|
||||
- **Commenting:** Line-level comments anchored to DSL lines; global comments supported. Uses rich text (Markdown subset) with mention support (`@group/sec-reviewers`).
|
||||
- **Resolution:** Approvers/reviewers can mark comment resolved; history preserved in timeline.
|
||||
- **Approval pane:**
|
||||
- Checklist (lint, simulation, determinism CI) with status indicators; links to evidence.
|
||||
- Reviewer checklist (quorum, blocking comments).
|
||||
- Approval button only enabled when checklist satisfied.
|
||||
- **Audit log:** Chronological view of submit/review/approve/archive events with actor, timestamp, note, attachments.
|
||||
- **RBAC feedback:** When user lacks permission, actions are disabled with tooltip referencing required scope(s).
|
||||
- **Notifications:** Integration with Notifier—subscribe/unsubscribe from review reminders within panel.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Runs & Observability
|
||||
|
||||
- **Run tab** consumes `/policy/runs` data:
|
||||
- Heatmap of rule hits per run (rows = runs, columns = top rules).
|
||||
- VEX override counter, suppressions, quieted findings metrics.
|
||||
- Incremental backlog widget (queue depth vs SLA).
|
||||
- Export CSV/JSON button.
|
||||
- **Replay/Download:** For each run, actions to download sealed replay bundle or open CLI command snippet.
|
||||
- **Alert banners:**
|
||||
- Determinism mismatch (red)
|
||||
- SLA breach (amber)
|
||||
- Pending replay (info)
|
||||
|
||||
---
|
||||
|
||||
## 7 · Explain & Findings Integration
|
||||
|
||||
- Inline “Open in Findings” button for any diff entry; opens side drawer with explain trace (same schema as `/findings/*/explain`).
|
||||
- Drawer includes:
|
||||
- Rule sequence with badges (block/warn/quiet).
|
||||
- VEX evidence and justification codes.
|
||||
- Links to advisories (Concelier) and SBOM components.
|
||||
- Copy-to-clipboard (JSON) and “Share permalink” features (permalinks encode tenant, policy version, component).
|
||||
|
||||
---
|
||||
|
||||
## 8 · Accessibility & i18n
|
||||
|
||||
- WCAG 2.2 AA:
|
||||
- Focus order follows logical workflow; skip link available.
|
||||
- All actionable icons paired with text or `aria-label`.
|
||||
- Simulation charts include table equivalents for screen readers.
|
||||
- Keyboard support:
|
||||
- `Alt+1/2/3/4` to switch tabs.
|
||||
- `Shift+?` toggles help overlay (with key map).
|
||||
- Internationalisation:
|
||||
- Translations sourced from `/locales/{lang}.json`.
|
||||
- Date/time displayed using user locale via `Intl.DateTimeFormat`.
|
||||
- Theming:
|
||||
- Light/dark CSS tokens; Monaco theme syncs with overall theme.
|
||||
- High-contrast mode toggled via user preferences.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Offline & Air-Gap Behaviour
|
||||
|
||||
- When console operates in sealed enclave:
|
||||
- Editor displays “Sealed mode” banner with import timestamp.
|
||||
- Simulation uses cached SBOM/advisory/VEX data only; results flagged accordingly.
|
||||
- “Export bundle” button packages draft + simulations for transfer.
|
||||
- Approvals require local Authority; UI blocks actions if `policy:approve` scope absent due to offline token limitations.
|
||||
- Run tab surfaces bundle staleness warnings (`policy_runs.inputs.env.sealed=true`).
|
||||
|
||||
---
|
||||
|
||||
## 10 · Telemetry & Testing Hooks
|
||||
|
||||
- User actions (simulate, submit, approve, activate) emit telemetry (`ui.policy.action` spans) with anonymised metadata.
|
||||
- Console surfaces correlation IDs for lint/compile errors to ease support triage.
|
||||
- Cypress/Playwright fixtures available under `ui/policy-editor/examples/`; docs should note to re-record after significant UI changes.
|
||||
|
||||
---
|
||||
|
||||
## 11 · Compliance Checklist
|
||||
|
||||
- [ ] **Lint integration:** Editor surfaces diagnostics from API compile endpoint; errors link to DSL documentation.
|
||||
- [ ] **Simulation parity:** Diff panel mirrors CLI schema; export button tested.
|
||||
- [ ] **Workflow RBAC:** Buttons enable/disable correctly per scope (`policy:write/submit/review/approve`).
|
||||
- [ ] **A11y verified:** Keyboard navigation, focus management, colour contrast (light/dark) pass automated Axe checks.
|
||||
- [ ] **Offline safeguards:** Sealed-mode banner and bundle export flows present; no network calls trigger in sealed mode.
|
||||
- [ ] **Telemetry wired:** Action spans and error logs include policyId, version, traceId.
|
||||
- [ ] **Docs cross-links:** Links to DSL, lifecycle, runs, API, CLI guides validated.
|
||||
- [ ] **Screenshot placeholders updated:** Replace TODO images with latest UI captures before GA.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 20).*
|
||||
|
||||
169
docs/ui/runs.md
Normal file
169
docs/ui/runs.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# StellaOps Console - Runs Workspace
|
||||
|
||||
> **Audience:** Scheduler Guild, Console UX, operators, support engineers.
|
||||
> **Scope:** Runs dashboard, live progress, queue management, diffs, retries, evidence downloads, observability, troubleshooting, and offline behaviour (Sprint 23).
|
||||
|
||||
The Runs workspace surfaces Scheduler activity across tenants: upcoming schedules, active runs, progress, deltas, and evidence bundles. It helps operators monitor backlog, drill into run segments, and recover from failures without leaving the console.
|
||||
|
||||
---
|
||||
|
||||
## 1. Access and prerequisites
|
||||
|
||||
- **Route:** `/console/runs` (list) with detail drawer `/console/runs/:runId`. SSE stream at `/console/runs/:runId/stream`.
|
||||
- **Scopes:** `runs.read` (baseline), `runs.manage` (cancel/retry), `policy:runs` (view policy deltas), `downloads.read` (evidence bundles).
|
||||
- **Dependencies:** Scheduler WebService (`/runs`, `/schedules`, `/preview`), Scheduler Worker event feeds, Policy Engine run summaries, Scanner WebService evidence endpoints.
|
||||
- **Feature flags:** `runs.dashboard.enabled`, `runs.sse.enabled`, `runs.retry.enabled`, `runs.evidenceBundles`.
|
||||
- **Tenancy:** Tenant selector filters list; cross-tenant admins can pin multiple tenants side-by-side (split view).
|
||||
|
||||
---
|
||||
|
||||
## 2. Layout overview
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------------+
|
||||
| Header: Tenant badge - schedule selector - backlog metrics |
|
||||
+-------------------------------------------------------------------+
|
||||
| Cards: Active runs - Queue depth - New findings - KEV deltas |
|
||||
+-------------------------------------------------------------------+
|
||||
| Tabs: Active | Completed | Scheduled | Failures |
|
||||
+-------------------------------------------------------------------+
|
||||
| Runs table (virtualised) |
|
||||
| Columns: Run ID | Trigger | State | Progress | Duration | Deltas |
|
||||
+-------------------------------------------------------------------+
|
||||
| Detail drawer: Summary | Segments | Deltas | Evidence | Logs |
|
||||
+-------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
The header integrates the status ticker to show ingestion deltas and planner heartbeat.
|
||||
|
||||
---
|
||||
|
||||
## 3. Runs table
|
||||
|
||||
| Column | Description |
|
||||
|--------|-------------|
|
||||
| **Run ID** | Deterministic identifier (`run:<tenant>:<timestamp>:<nonce>`). Clicking opens detail drawer. |
|
||||
| **Trigger** | `cron`, `manual`, `feedser`, `vexer`, `policy`, `content-refresh`. Tooltip lists schedule and initiator. |
|
||||
| **State** | Badges: `planning`, `queued`, `running`, `completed`, `cancelled`, `error`. Errors include error code (e.g., `ERR_RUN_005`). |
|
||||
| **Progress** | Percentage + processed/total candidates. SSE updates increment in real time. |
|
||||
| **Duration** | Elapsed time (auto-updating). Completed runs show total duration; running runs show timer. |
|
||||
| **Deltas** | Count of findings deltas (`+critical`, `+high`, `-quieted`, etc.). Tooltip expands severity breakdown. |
|
||||
|
||||
Row badges include `KEV first`, `Content refresh`, `Policy promotion follow-up`, and `Retry`. Selecting multiple rows enables bulk downloads and exports.
|
||||
|
||||
Filters: trigger type, state, schedule, severity impact (critical/high), policy revision, timeframe, planner shard, error code.
|
||||
|
||||
---
|
||||
|
||||
## 4. Detail drawer
|
||||
|
||||
Sections:
|
||||
|
||||
1. **Summary** - run metadata (tenant, trigger, linked schedule, planner shard count, started/finished timestamps, correlation ID).
|
||||
2. **Progress** - segmented progress bar (planner, queue, execution, post-processing). Real-time updates via SSE; includes throughput (targets per minute).
|
||||
3. **Segments** - table of run segments with state, target count, executor, retry count. Operators can retry failed segments individually (requires `runs.manage`).
|
||||
4. **Deltas** - summary of findings changes (new findings, resolved findings, severity shifts, KEV additions). Links to Findings view filtered by run ID.
|
||||
5. **Evidence** - links to evidence bundles (JSON manifest, DSSE attestation), policy run records, and explain bundles. Download buttons use `/console/exports` orchestration.
|
||||
6. **Logs** - last 50 structured log entries with severity, message, correlation ID; scroll-to-live for streaming logs. `Open in logs` copies query for external log tooling.
|
||||
|
||||
---
|
||||
|
||||
## 5. Queue and schedule management
|
||||
|
||||
- Schedule side panel lists upcoming jobs with cron expressions, time zones, and enable toggles.
|
||||
- Queue depth chart shows current backlog per tenant and schedule (planner backlog, executor backlog).
|
||||
- "Preview impact" button opens modal for manual run planning (purls or vuln IDs) and shows impacted image count before launch. CLI parity: `stella runs preview --tenant <id> --file keys.json`.
|
||||
- Manual run form allows selecting mode (`analysis-only`, `content-refresh`), scope, and optional policy snapshot.
|
||||
- Pausing a schedule requires confirmation; UI displays earliest next run after resume.
|
||||
|
||||
---
|
||||
|
||||
## 6. Live updates and SSE stream
|
||||
|
||||
- SSE endpoint `/console/runs/{id}/stream` streams JSON events (`stateChanged`, `segmentProgress`, `deltaSummary`, `log`). UI reconnects with exponential backoff and heartbeat.
|
||||
- Global ticker shows planner heartbeat age; banner warns after 90 seconds of silence.
|
||||
- Offline mode disables SSE and falls back to polling every 30 seconds.
|
||||
|
||||
---
|
||||
|
||||
## 7. Retry and remediation
|
||||
|
||||
- Failed segments show retry button; UI displays reason and cooldown timers. Retry actions are scope-gated and logged.
|
||||
- Full run retry resets segments while preserving original run metadata; new run ID references previous run in `retryOf` field.
|
||||
- "Escalate to support" button opens incident template pre-filled with run context and correlation IDs.
|
||||
- Troubleshooting quick links:
|
||||
- `ERR_RUN_001` (planner lock)
|
||||
- `ERR_RUN_005` (Scanner timeout)
|
||||
- `ERR_RUN_009` (impact index stale)
|
||||
Each link points to corresponding runbook sections (`docs/ops/scheduler-runbook.md`).
|
||||
- CLI parity: `stella runs retry --run <id>`, `stella runs cancel --run <id>`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Evidence downloads
|
||||
|
||||
- Evidence tab aggregates:
|
||||
- Policy run summary (`/policy/runs/{id}`)
|
||||
- Findings delta CSV (`/downloads/findings/{runId}.csv`)
|
||||
- Scanner evidence bundle (compressed JSON with manifest)
|
||||
- Downloads show size, hash, signature status.
|
||||
- "Bundle for offline" packages all evidence into single tarball with manifest/digest; UI notes CLI parity (`stella runs export --run <id> --bundle`).
|
||||
- Completed bundles stored in Downloads workspace for reuse (links provided).
|
||||
|
||||
---
|
||||
|
||||
## 9. Observability
|
||||
|
||||
- Metrics cards: `scheduler_queue_depth`, `scheduler_runs_active`, `scheduler_runs_error_total`, `scheduler_runs_duration_seconds`.
|
||||
- Trend charts: queue depth (last 24h), runs per trigger, average duration, determinism score.
|
||||
- Alert banners: planner lag > SLA, queue depth > threshold, repeated error codes.
|
||||
- Telemetry panel lists latest events (e.g., `scheduler.run.started`, `scheduler.run.completed`, `scheduler.run.failed`).
|
||||
|
||||
---
|
||||
|
||||
## 10. Offline and air-gap behaviour
|
||||
|
||||
- Offline banner highlights snapshot timestamp and indicates SSE disabled.
|
||||
- Manual run form switches to generate CLI script for offline execution (`stella runs submit --bundle <file>`).
|
||||
- Evidence download buttons output local paths; UI reminds to copy to removable media.
|
||||
- Queue charts use snapshot data; manual refresh button loads latest records from Offline Kit.
|
||||
- Tenants absent from snapshot hidden to avoid partial data.
|
||||
|
||||
---
|
||||
|
||||
## 11. Screenshot coordination
|
||||
|
||||
- Placeholders:
|
||||
- ``
|
||||
- ``
|
||||
- Coordinate with Scheduler Guild for updated screenshots after Sprint 23 UI stabilises (tracked in `#console-screenshots`, entry 2025-10-26).
|
||||
|
||||
---
|
||||
|
||||
## 12. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - shell, SSE ticker.
|
||||
- `/docs/ui/navigation.md` - route map and deep links.
|
||||
- `/docs/ui/findings.md` - findings filtered by run.
|
||||
- `/docs/ui/downloads.md` - download manager, export retention, CLI parity.
|
||||
- `/docs/ARCHITECTURE_SCHEDULER.md` - scheduler architecture and data model.
|
||||
- `/docs/policy/runs.md` - policy run integration.
|
||||
- `/docs/cli/policy.md` and `/docs/cli/policy.md` section 5 for CLI parity (runs commands pending).
|
||||
- `/docs/ops/scheduler-runbook.md` - troubleshooting.
|
||||
|
||||
---
|
||||
|
||||
## 13. Compliance checklist
|
||||
|
||||
- [ ] Runs table columns, filters, and states described.
|
||||
- [ ] Detail drawer sections documented (segments, deltas, evidence, logs).
|
||||
- [ ] Queue management, manual run, and preview coverage included.
|
||||
- [ ] SSE and live update behaviour detailed.
|
||||
- [ ] Retry, remediation, and runbook references provided.
|
||||
- [ ] Evidence downloads and bundle workflows documented with CLI parity.
|
||||
- [ ] Offline behaviour and screenshot coordination recorded.
|
||||
- [ ] References validated.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
195
docs/ui/sbom-explorer.md
Normal file
195
docs/ui/sbom-explorer.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# StellaOps Console - SBOM Explorer
|
||||
|
||||
> **Audience:** Console UX, SBOM Service Guild, enablement teams, customer onboarding.
|
||||
> **Scope:** Catalog listing, component detail, graph overlays, exports, performance hints, and offline behaviour for the SBOM Explorer that ships in Sprint 23.
|
||||
|
||||
The SBOM Explorer lets operators inspect software bills of materials collected by Scanner and normalised by the SBOM Service. It provides tenant-scoped catalogs, usage overlays, provenance-aware graphs, and deterministic export paths that align with CLI workflows.
|
||||
|
||||
---
|
||||
|
||||
## 1. Access and prerequisites
|
||||
|
||||
- **Routes:** `/console/sbom` (catalog) and `/console/sbom/:digest` (detail).
|
||||
- **Scopes:** `sbom.read` (required), `sbom.export` for large export jobs, `findings.read` to open explain drawers, `policy.read` to view overlay metadata.
|
||||
- **Feature flags:** `sbomExplorer.enabled` (default true when SBOM Service v3 API is enabled) and `graph.overlays.enabled` for Cartographer-backed overlays.
|
||||
- **Tenant scoping:** All queries include `tenant` tokens; switching tenants triggers catalog refetch and clears cached overlays.
|
||||
- **Data dependencies:** Requires SBOM Service 3.1+ with Cartographer overlays and Policy Engine explain hints enabled.
|
||||
|
||||
---
|
||||
|
||||
## 2. Layout overview
|
||||
|
||||
```
|
||||
+-----------------------------------------------------------------------+
|
||||
| Header: Tenant badge - global filters - offline indicator - actions |
|
||||
+-----------------------------------------------------------------------+
|
||||
| Left rail: Saved views - pinned tags - export queue status |
|
||||
+-----------------------------------------------------------------------+
|
||||
| Catalog table (virtualised) |
|
||||
| - Columns: Image digest - Source - Scan timestamp - Policy verdict |
|
||||
| - Badges: Delta SBOM, Attested, Offline snapshot |
|
||||
+-----------------------------------------------------------------------+
|
||||
| Detail drawer or full page tabs (Inventory | Usage | Components | |
|
||||
| Overlays | Explain | Exports) |
|
||||
+-----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
The catalog and detail views reuse the shared command palette, context chips, and SSE status ticker described in `/docs/ui/navigation.md`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Catalog view
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Virtual table** | Uses Angular CDK virtual scroll to render up to 10,000 records per tenant without layout jank. Sorting and filtering are client-side for <= 20k rows; the UI upgrades to server-side queries automatically when more records exist. |
|
||||
| **Preset segments** | Quick toggles for `All`, `Recent (7 d)`, `Delta-ready`, `Attested`, and `Offline snapshots`. Each preset maps to saved view tokens for CLI parity. |
|
||||
| **Search** | Global search field supports image digests, repository tags, SBOM IDs, and component PURLs. Search terms propagate to the detail view when opened. |
|
||||
| **Badges** | - `Delta` badge indicates SBOM produced via delta mode (layers reuse).<br>- `Attested` badge links to Attestor proof and Rekor record.<br>- `Snapshot` badge shows offline import hash.<br>- `Policy` badge references last policy verdict summary. |
|
||||
| **Bulk actions** | Multi-select rows to stage export jobs, trigger async explain generation, or copy CLI commands. Actions enforce per-tenant rate limits and show authority scopes in tooltips. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Detail tabs
|
||||
|
||||
### 4.1 Inventory tab
|
||||
|
||||
- Default view summarising all components with columns for package name (PURL), version, supplier, license, size, and counts of referencing layers.
|
||||
- Filters: severity, ecosystem (OS, NPM, PyPI, Maven, Go, NuGet, Rust, containers), usage flag (true/false), package tags.
|
||||
- Sorting: by severity (desc), version (asc), supplier.
|
||||
- Cell tooltips reference Concelier advisories and Policy Engine findings when available.
|
||||
- Total component count, unique suppliers, and critical severity counts appear in the header cards.
|
||||
|
||||
### 4.2 Usage tab
|
||||
|
||||
- Focuses on runtime usage (EntryTrace, runtime sensors, allow lists).
|
||||
- Columns include process names, entry points, and `usedByEntrypoint` flags.
|
||||
- Grouping: by entry point, by package, or by namespace (Kubernetes).
|
||||
- Highlights mismatches between declared dependencies and observed usage for drift detection.
|
||||
|
||||
### 4.3 Components tab
|
||||
|
||||
- Deep dive for a single component selected from Inventory or Usage.
|
||||
- Shows provenance timeline (introduced in layer, modified, removed), file paths, cryptographic hashes, and linked evidence (DSSE, Attestor bundles).
|
||||
- Links to CLI commands: `stella sbom component show <digest> <purl>` and `stella sbom component export`.
|
||||
- Drawer supports multi-component comparison through tabbed interface.
|
||||
|
||||
### 4.4 Overlays tab
|
||||
|
||||
- Displays Cartographer overlays: vulnerability overlays (policy verdicts), runtime overlays (process traces), and vendor advisories.
|
||||
- Each overlay card lists source, generation timestamp, precedence, and staleness relative to tenant SLA.
|
||||
- Toggle overlays on/off to see impact on component status; UI does not mutate canonical SBOM, it only enriches the view.
|
||||
- Graph preview button opens force-directed component graph (limited to <= 500 nodes) with filters for dependency depth and relationship type.
|
||||
- Overlay metadata includes the CLI parity snippet: `stella sbom overlay apply --overlay <id> --digest <digest>`.
|
||||
|
||||
### 4.5 Explain tab
|
||||
|
||||
- Integrates Policy Engine explain drawer.
|
||||
- Shows rule hits, VEX overrides, and evidence per component.
|
||||
- Provides "Open in Findings" link that preserves tenant and filters.
|
||||
|
||||
### 4.6 Exports tab
|
||||
|
||||
- Lists available exports (CycloneDX JSON, CycloneDX Protobuf, SPDX JSON, SPDX Tag-Value, Delta bundle, Evidence bundle).
|
||||
- Each export entry shows size, hash (SHA-256), format version, and generation time.
|
||||
- Download buttons respect RBAC and offline quotas; CLI callouts mirror `stella sbom export`.
|
||||
- "Schedule export" launches async job for large bundles; job status integrates with `/console/downloads`.
|
||||
- Includes copy-to-clipboard path for offline transfers (`/offline-kits/export/<tenant>/<digest>/<format>`).
|
||||
|
||||
---
|
||||
|
||||
## 5. Filters and presets
|
||||
|
||||
| Filter | Applies to | Notes |
|
||||
|--------|------------|-------|
|
||||
| **Severity** | Inventory, Overlays, Explain | Uses Policy Engine severity buckets and KEV flag. |
|
||||
| **Ecosystem** | Inventory, Usage | Multi-select list with search; maps to package type derived from PURL. |
|
||||
| **License** | Inventory | Groups by SPDX identifiers; warns on copyleft obligations. |
|
||||
| **Supplier** | Inventory, Components | Autocomplete backed by SBOM metadata. |
|
||||
| **Tags** | Inventory, Usage | Tags provided by Scanner or user-defined metadata. |
|
||||
| **Component search** | Components, Overlays | Accepts PURL or substring; retains highlight when switching tabs. |
|
||||
| **Snapshot** | Catalog | Filters to SBOMs sourced from Offline Kit or local import. |
|
||||
| **Attested only** | Catalog, Exports | Limits to SBOMs signed by Attestor; displays Rekor badge. |
|
||||
|
||||
Saved views store combinations of these filters and expose command palette shortcuts (`Cmd+1-9 / Ctrl+1-9`).
|
||||
|
||||
---
|
||||
|
||||
## 6. Graph overlays and cartography
|
||||
|
||||
- Graph view is powered by Cartographer projections (tenant-scoped graph snapshots).
|
||||
- Supported overlays:
|
||||
- **Dependency graph** (default) - nodes represent components, edges represent dependencies with direction (introducer -> introduced).
|
||||
- **Runtime call graph** - optional overlay layering process calls on top of dependencies.
|
||||
- **Vulnerability overlay** - colours nodes by highest severity and outlines exploited components.
|
||||
- Controls: depth slider (1-6), include transitive flag, hide dev dependencies toggle, highlight vendor-specified critical paths.
|
||||
- Export options: GraphML, JSON Lines, and screenshot capture (requires `graph.export`).
|
||||
- Performance guardrails: overlays warn when node count exceeds 2,000; user can queue background job to render static graph for download instead.
|
||||
|
||||
---
|
||||
|
||||
## 7. Exports and automation
|
||||
|
||||
- **Instant exports:** Inline downloads for CycloneDX JSON/Protobuf (<= 25 MB) and SPDX JSON (<= 25 MB).
|
||||
- **Async exports:** Larger bundles stream through the download manager with resume support. UI polls `/console/downloads` every 15 seconds while export is in progress.
|
||||
- **CLI parity:** Each export card displays the equivalent CLI command and environment variables (proxy, offline).
|
||||
- **Compliance metadata:** Export manifests include SBOM ID, component count, hash, signature state, and policy verdict summary so auditors can validate offline.
|
||||
- **Automation hooks:** Webhook button copies the `/downloads/hooks/subscribe` call for integration with CI pipelines.
|
||||
|
||||
---
|
||||
|
||||
## 8. Performance tips
|
||||
|
||||
- Virtual scroll keeps initial render under 70 ms for 10k rows; server-side pagination engages beyond that threshold.
|
||||
- Graph overlay rendering uses Web Workers to keep main thread responsive; heavy layouts show "Background layout in progress" banner.
|
||||
- SSE updates (new SBOM ready) refresh header cards and prepend rows without full table redraw.
|
||||
- Prefetching: opening a detail drawer preloads overlays and exports concurrently; these requests cancel automatically if the user navigates away.
|
||||
- Local cache (IndexedDB) stores last viewed SBOM detail for each tenant (up to 20 entries). Cache invalidates when new merge hash is observed.
|
||||
|
||||
---
|
||||
|
||||
## 9. Offline and air-gap behaviour
|
||||
|
||||
- Catalog reads from Offline Kit snapshot if gateway is in sealed mode; offline banner lists snapshot ID and staleness.
|
||||
- Overlays limited to data included in snapshot; missing overlays show guidance to import updated Cartographer package.
|
||||
- Exports queue locally and generate tarballs ready to copy to removable media.
|
||||
- CLI parity callouts switch to offline examples (using `stella sbom export --offline`).
|
||||
- Tenants unavailable in snapshot are hidden from the tenant picker to prevent inconsistent views.
|
||||
|
||||
---
|
||||
|
||||
## 10. Screenshot coordination
|
||||
|
||||
- Placeholder images:
|
||||
- ``
|
||||
- ``
|
||||
- Coordinate with Console Guild to capture updated screenshots (dark and light theme) once Sprint 23 UI stabilises. Track follow-up in Console Guild thread `#console-screenshots` dated 2025-10-26.
|
||||
|
||||
---
|
||||
|
||||
## 11. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - navigation shell, tenant model, filters.
|
||||
- `/docs/ui/navigation.md` - command palette, deep-link schema.
|
||||
- `/docs/ui/downloads.md` - download queue, manifest parity, offline export handling.
|
||||
- `/docs/security/console-security.md` - scopes, DPoP, CSP.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence matrix.
|
||||
- `/docs/architecture/console.md` (pending) - component data flows.
|
||||
- `/docs/architecture/overview.md` - high-level module relationships.
|
||||
- `/docs/ingestion/aggregation-only-contract.md` - provenance and guard rails.
|
||||
|
||||
---
|
||||
|
||||
## 12. Compliance checklist
|
||||
|
||||
- [ ] Catalog table and detail tabs documented with columns, filters, and presets.
|
||||
- [ ] Overlay behaviour describes Cartographer integration and CLI parity.
|
||||
- [ ] Export section includes instant vs async workflow and compliance metadata.
|
||||
- [ ] Performance considerations align with UI benchmarks (virtual scroll, workers).
|
||||
- [ ] Offline behaviour captured for catalog, overlays, exports.
|
||||
- [ ] Screenshot placeholders and coordination notes recorded with Console Guild follow-up.
|
||||
- [ ] All referenced docs verified and accessible.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
Reference in New Issue
Block a user