stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
7600caea632e9e44571bc1661003948a5e1d22fb
git.stella-ops.org/docs/ui/advisories-and-vex.md
root 68da90a11a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Restructure solution layout by module
2025-10-28 15:10:40 +02:00

12 KiB
Raw Blame History

StellaOps Console - Advisories and VEX

Audience: Console UX team, Concelier and Excititor guilds, support and compliance engineers.
Scope: Advisory aggregation UX, VEX consensus display, conflict indicators, raw document viewer, provenance banners, CLI parity, and Aggregation-Only Contract (AOC) guardrails for Sprint 23.

The Advisories and VEX surfaces expose Concelier and Excititor outputs without mutating the underlying data. Operators can review upstream statements, check consensus summaries, inspect conflicts, and hand off evidence to downstream tooling while staying within the Aggregation-Only Contract.

1. Access and prerequisites

  • Routes:
    • /console/advisories (advisory list and detail)
    • /console/vex (VEX consensus and raw claim explorer)
  • Scopes: advisory.read and vex.read (base access), advisory.verify / vex.verify for verification actions, downloads.read for evidence exports.
  • Feature flags: advisoryExplorer.enabled, vexExplorer.enabled, aggregation.conflictIndicators.
  • Dependencies: Concelier WebService (aggregation API + delta metrics), Excititor WebService (consensus API + conflict feeds), Policy Engine explain hints (optional link-outs), Authority tenant enforcement.
  • Offline behaviour: Uses Offline Kit snapshots when gateway is in sealed mode; verify buttons queue until connectivity resumes.

2. Layout overview

+---------------------------------------------------------------------+
| Header: Tenant badge - global filters - status ticker - actions    |
+---------------------------------------------------------------------+
| Left rail: Saved views - provider filters - verification queue     |
+---------------------------------------------------------------------+
| Main split pane                                                    |
|  - Advisories tab (grid + detail drawer)                           |
|  - VEX tab (consensus table + claim drawer)                        |
| Tabs remember last active view per tenant.                         |
+---------------------------------------------------------------------+

The header reuses console-wide context chips (Tenant, Severity, Source, Time) and the status ticker that streams Concelier and Excititor deltas.

3. Advisory aggregation view

Element Description
Grid columns Vulnerability key (CVE/GHSA/vendor), Title, Source set, Last merged, Severity badge, KEV flag, Affected product count, Merge hash.
Source chips Show contributing providers (NVD, Red Hat, Debian, vendor PSIRT). Hover reveals precedence order and timestamps.
Severity Displays the highest severity declared by any source; tooltip lists per-source severities and vectors.
KEV / Exploit status Badge highlights known exploited status from Concelier enrichment; links to KEV reference.
Merge hash Deterministic hash from Concelier merge_event. Clicking copies hash and opens provenance banner.
Filters Vulnerability identifier search, provider multi-select, severity picker, KEV toggle, affected product range slider, time window.
List actions Open detail, Copy CLI (stella advisory show ...), Compare sources, Queue verify.

The grid virtualises up to 15,000 advisories per tenant. Beyond that, the UI engages server-side pagination with cursor hints supplied by Concelier.

4. Advisory detail drawer

Sections within the drawer:

  1. Summary cards (title, published/modified timestamps, advisory merge hash, total sources, exploited flag).
  2. Sources timeline listing each contributing document with signature status, fetched timestamps, precedence rank, and quick links to raw view.
  3. Affected products table (product key, introduced/fixed, range semantics, distro qualifiers, notes). Column toggles allow switching between SemVer and distro notation.
  4. Conflict indicators show when sources disagree on fixed versions, severity, or affected sets. Each conflict row links to an explainer panel that describes the winning value, losing sources, and precedence rule.
  5. References collapsible list (patches, advisories, exploits).
  6. Raw JSON viewer (read-only) using canonical Concelier payload. Users can copy JSON or download via GET /console/advisories/raw/{id}.
  7. CLI parity card with commands:
    • stella advisory show --tenant <tenant> --vuln <id>
    • stella advisory sources --tenant <tenant> --vuln <id>
    • stella advisory export --tenant <tenant> --vuln <id> --format cdx-json

Provenance banner at the top indicates whether all sources are signed, partially signed, or unsigned, referencing AOC guardrails. Unsigned sources trigger a warning and link to the verification checklist.

5. VEX explorer

Feature Description
Consensus table Rows keyed by (vulnId, productKey) with rollup status (affected, not affected, fixed, under investigation), confidence score, provider count, and last evaluation timestamp.
Status badges Colour-coded (red affected, green not affected, blue fixed, amber under investigation). Tooltips show justification and policy revision used.
Provider breakdown Hover or expand to see source list with accepted/ignored flag, status, justification code, signature state, weight.
Filters Product search (PURL), status filter, provider filter, justification codes, confidence threshold slider.
Saved views Prebuilt presets: Vendor consensus, Distro overrides, Conflicts, Pending investigation.

6. VEX detail drawer

Tabs within the drawer:

  • Consensus summary: Restates rollup status, policy revision, confidence benchmarks, and referencing runs.
  • Claims list: Every raw claim from Excititor with provenance, signature result, justification, supersedes chain, evidence snippets. Claims are grouped by provider tier (vendor, distro, ecosystem, CERT).
  • Conflict explainers: For conflicting claims, shows why a claim was ignored (weight, stale timestamp, failing justification gate). Includes inline diff between competing claims.
  • Events: Timeline of claim arrivals and consensus evaluations with correlation IDs, accessible for debugging.
  • Raw JSON: Canonical VexClaim or VexConsensus payloads with copy/download. CLI parity callouts:
    • stella vex consensus show --tenant <tenant> --vuln <id> --product <purl>
    • stella vex claims show --tenant <tenant> --vuln <id> --provider <provider>

7. Raw viewers and provenance

  • Raw viewers display canonical payloads with syntax highlighting and copy-as-JSON support.
  • Provenance banner presents: source URI, document digest, signature status, fetch timestamps, collector version.
  • Users can open raw documents in a modal that includes:
    • sha256 digest with copy button
    • Signature verification summary (passing keys, missing signatures, errors)
    • Download DSSE bundle button when the document is attested
    • Open in logs link that copies search query (correlationId=...) for log aggregation tools.

All raw views are read-only to maintain Aggregation-Only guarantees.

8. Conflict indicators and aggregation-not-merge UX

  • Concelier retains every source; the UI surfaces conflicts rather than merging them.
  • Conflict badges appear in grids and detail views when sources disagree on affected ranges, fixed versions, severity, or exploit flags.
  • Clicking a badge opens the conflict explainer panel (powered by Concelier merge metadata) that lists winning/losing sources, ranks, and reasoning (e.g., "Vendor PSIRT overrides ecosystem advisory").
  • Excititor conflicts highlight discarded claims with reasons (stale, failing justification, low weight). Operators can override weights downstream via Policy Engine if needed.
  • UI copy explicitly reminds users that policy decisions happen elsewhere; these views show aggregated facts only.

9. Verification workflows

  • Run verify buttons call Concelier or Excititor verification endpoints (POST /console/advisories/verify, POST /console/vex/verify) scoped by tenant and source filters.
  • Verification results appear as banners summarising documents checked, signatures verified, and guard violations.
  • Failed verifications show actionable error IDs (ERR_AOC_00x), matching CLI output.
  • Verification history accessible via the status ticker dropdown; entries include operator, scope, and correlation IDs.

10. Exports and automation

  • Advisory tab exposes export actions: Download normalized advisory, Download affected products CSV, Download source bundle (raw documents packaged with manifest).
  • VEX tab supports exports for consensus snapshots, raw claims, and provider deltas.
  • Export manifests include merge hash or consensus digest, tenant ID, timestamp, and signature state.
  • CLI parity snippets accompany each export (e.g., stella advisory export, stella vex export).
  • Automation: copy buttons for webhook subscription (/downloads/hooks/subscribe) and ORAS push commands when using remote registries.

11. Observability and SSE updates

  • Status ticker shows ingest lag (advisory_delta_minutes, vex_delta_minutes), last merge event hash, and verification queue depth.
  • Advisory and VEX grids refresh via SSE channels; updates animate row badges (new source, conflict resolved).
  • Metrics surfaced in drawers: ingestion age, signature pass rate, consensus evaluation duration.
  • Errors display correlation IDs linking to Concelier/Excititor logs.

12. Offline and air-gap behaviour

  • When offline, list views display snapshot badge, staleness timer, and disable real-time verification.
  • Raw downloads reference local snapshot directories and include checksum instructions.
  • Exports queue locally; UI offers Copy to removable media instructions.
  • CLI parity switches to offline commands (--offline, --snapshot).
  • Tenant picker hides tenants not present in the snapshot to avoid partial data views.

13. Screenshot coordination

  • Placeholders:
    • ![Advisory grid placeholder](../assets/ui/advisories/grid-placeholder.png)
    • ![VEX consensus placeholder](../assets/ui/advisories/vex-placeholder.png)
  • Coordinate with Console Guild to capture updated screenshots (dark and light themes) once Sprint 23 build candidate is tagged. Tracking in Slack channel #console-screenshots (entry 2025-10-26).

14. References

  • /docs/ui/console-overview.md - shell, filters, tenant model.
  • /docs/ui/navigation.md - command palette, deep-link schema.
  • /docs/ingestion/aggregation-only-contract.md - AOC guardrails.
  • /docs/architecture/CONCELIER.md - merge rules, provenance.
  • /docs/architecture/EXCITITOR.md - VEX consensus model.
  • /docs/security/console-security.md - scopes, DPoP, CSP.
  • /docs/cli-vs-ui-parity.md - CLI equivalence matrix.

15. Compliance checklist

  • Advisory grid columns, filters, and merge hash behaviour documented.
  • VEX consensus view covers status badges, provider breakdown, and filters.
  • Raw viewer and provenance banners explained with AOC alignment.
  • Conflict indicators and explainers tied to aggregation-not-merge rules.
  • Verification workflow and CLI parity documented.
  • Offline behaviour and automation paths captured.
  • Screenshot placeholders and coordination notes recorded.
  • References validated.

Last updated: 2025-10-26 (Sprint 23).