stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
7b5bdcf4d3bee4e6f398d0226ba8cd3c2754e07a
git.stella-ops.org/docs/ui/sbom-explorer.md
master 7b5bdcf4d3 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.
2025-10-30 00:09:39 +02:00

11 KiB
Raw Blame History

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).
- Attested badge links to Attestor proof and Rekor record.
- Snapshot badge shows offline import hash.
- 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:
    • ![SBOM catalog view placeholder](../assets/ui/sbom/catalog-placeholder.png)
    • ![Overlay graph placeholder](../assets/ui/sbom/overlay-placeholder.png)
  • 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).