feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes. - Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes. - Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables. - Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
This commit is contained in:
348
docs/ui/admin.md
348
docs/ui/admin.md
@@ -1,174 +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).*
|
||||
|
||||
# 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/modules/authority/architecture.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/modules/cli/guides/authentication.md` (pending) and `/docs/modules/cli/guides/policy.md` for CLI flows.
|
||||
- `/docs/modules/scheduler/operations/worker.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).*
|
||||
|
||||
|
||||
@@ -1,144 +1,144 @@
|
||||
# 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) plus `advisory:read` to view Concelier ingestion metrics/violations.
|
||||
- `vex:read` to see Excititor entries and run VEX verifications.
|
||||
- `aoc:verify` to trigger guard runs from the dashboard action bar.
|
||||
- `advisory:ingest` / `vex:ingest` **not** required; the 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).*
|
||||
# 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](../modules/platform/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) plus `advisory:read` to view Concelier ingestion metrics/violations.
|
||||
- `vex:read` to see Excititor entries and run VEX verifications.
|
||||
- `aoc:verify` to trigger guard runs from the dashboard action bar.
|
||||
- `advisory:ingest` / `vex:ingest` **not** required; the 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](../modules/authority/architecture.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](../modules/platform/architecture-overview.md)
|
||||
- [Concelier architecture](../modules/concelier/architecture.md)
|
||||
- [Excititor architecture](../modules/excititor/architecture.md)
|
||||
- [CLI AOC commands](../modules/cli/guides/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).*
|
||||
|
||||
@@ -1,179 +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).*
|
||||
|
||||
# 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/modules/cli/guides/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).*
|
||||
|
||||
|
||||
@@ -1,192 +1,192 @@
|
||||
# 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 / roles:**
|
||||
- `policy:read` (list and details)
|
||||
- `policy:author` (edit drafts, run lint/compile)
|
||||
- `policy:review`, `policy:approve` (workflow actions)
|
||||
- `policy:operate` (promotions, run orchestration)
|
||||
- `policy:simulate` (run simulations)
|
||||
- `policy:audit` (download audit bundles)
|
||||
- `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:author`, `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:operate`, `policy:simulate` | Approve/promote, trigger runs, view run history. |
|
||||
| **Operator** | `policy:read`, `policy:operate`, `policy:simulate`, `effective:write` | Schedule promotions, monitor runs (no editing). |
|
||||
| **Auditor** | `policy:read`, `policy:audit`, `policy:simulate` | View immutable history, export audit bundles. |
|
||||
| **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).*
|
||||
# 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 / roles:**
|
||||
- `policy:read` (list and details)
|
||||
- `policy:author` (edit drafts, run lint/compile)
|
||||
- `policy:review`, `policy:approve` (workflow actions)
|
||||
- `policy:operate` (promotions, run orchestration)
|
||||
- `policy:simulate` (run simulations)
|
||||
- `policy:audit` (download audit bundles)
|
||||
- `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:author`, `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:operate`, `policy:simulate` | Approve/promote, trigger runs, view run history. |
|
||||
| **Operator** | `policy:read`, `policy:operate`, `policy:simulate`, `effective:write` | Schedule promotions, monitor runs (no editing). |
|
||||
| **Auditor** | `policy:read`, `policy:audit`, `policy:simulate` | View immutable history, export audit bundles. |
|
||||
| **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/modules/cli/guides/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).*
|
||||
|
||||
@@ -1,179 +1,179 @@
|
||||
# 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 / roles:**
|
||||
- `policy:author` (role `policy-author`) to edit drafts, run lint/compile, and execute quick simulations.
|
||||
- `policy:review` (role `policy-reviewer`) to review drafts, leave comments, and request changes.
|
||||
- `policy:approve` (role `policy-approver`) to approve or reject submissions.
|
||||
- `policy:operate` (role `policy-operator`) to trigger batch simulations, promotions, and canary runs.
|
||||
- `policy:audit` (role `policy-auditor`) to access immutable history and audit exports.
|
||||
- `policy:simulate` to run simulations from Console; `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).*
|
||||
# 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 / roles:**
|
||||
- `policy:author` (role `policy-author`) to edit drafts, run lint/compile, and execute quick simulations.
|
||||
- `policy:review` (role `policy-reviewer`) to review drafts, leave comments, and request changes.
|
||||
- `policy:approve` (role `policy-approver`) to approve or reject submissions.
|
||||
- `policy:operate` (role `policy-operator`) to trigger batch simulations, promotions, and canary runs.
|
||||
- `policy:audit` (role `policy-auditor`) to access immutable history and audit exports.
|
||||
- `policy:simulate` to run simulations from Console; `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](../modules/ui/architecture.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).*
|
||||
|
||||
338
docs/ui/runs.md
338
docs/ui/runs.md
@@ -1,169 +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).*
|
||||
# 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/modules/scheduler/operations/worker.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/modules/scheduler/architecture.md` - scheduler architecture and data model.
|
||||
- `/docs/policy/runs.md` - policy run integration.
|
||||
- `/docs/modules/cli/guides/policy.md` and `/docs/modules/cli/guides/policy.md` section 5 for CLI parity (runs commands pending).
|
||||
- `/docs/modules/scheduler/operations/worker.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).*
|
||||
|
||||
@@ -1,195 +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).*
|
||||
# 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/modules/platform/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