Add Policy DSL Validator, Schema Exporter, and Simulation Smoke tools
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implemented PolicyDslValidator with command-line options for strict mode and JSON output. - Created PolicySchemaExporter to generate JSON schemas for policy-related models. - Developed PolicySimulationSmoke tool to validate policy simulations against expected outcomes. - Added project files and necessary dependencies for each tool. - Ensured proper error handling and usage instructions across tools.
This commit is contained in:
195
docs/ui/sbom-explorer.md
Normal file
195
docs/ui/sbom-explorer.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# StellaOps Console - SBOM Explorer
|
||||
|
||||
> **Audience:** Console UX, SBOM Service Guild, enablement teams, customer onboarding.
|
||||
> **Scope:** Catalog listing, component detail, graph overlays, exports, performance hints, and offline behaviour for the SBOM Explorer that ships in Sprint 23.
|
||||
|
||||
The SBOM Explorer lets operators inspect software bills of materials collected by Scanner and normalised by the SBOM Service. It provides tenant-scoped catalogs, usage overlays, provenance-aware graphs, and deterministic export paths that align with CLI workflows.
|
||||
|
||||
---
|
||||
|
||||
## 1. Access and prerequisites
|
||||
|
||||
- **Routes:** `/console/sbom` (catalog) and `/console/sbom/:digest` (detail).
|
||||
- **Scopes:** `sbom.read` (required), `sbom.export` for large export jobs, `findings.read` to open explain drawers, `policy.read` to view overlay metadata.
|
||||
- **Feature flags:** `sbomExplorer.enabled` (default true when SBOM Service v3 API is enabled) and `graph.overlays.enabled` for Cartographer-backed overlays.
|
||||
- **Tenant scoping:** All queries include `tenant` tokens; switching tenants triggers catalog refetch and clears cached overlays.
|
||||
- **Data dependencies:** Requires SBOM Service 3.1+ with Cartographer overlays and Policy Engine explain hints enabled.
|
||||
|
||||
---
|
||||
|
||||
## 2. Layout overview
|
||||
|
||||
```
|
||||
+-----------------------------------------------------------------------+
|
||||
| Header: Tenant badge - global filters - offline indicator - actions |
|
||||
+-----------------------------------------------------------------------+
|
||||
| Left rail: Saved views - pinned tags - export queue status |
|
||||
+-----------------------------------------------------------------------+
|
||||
| Catalog table (virtualised) |
|
||||
| - Columns: Image digest - Source - Scan timestamp - Policy verdict |
|
||||
| - Badges: Delta SBOM, Attested, Offline snapshot |
|
||||
+-----------------------------------------------------------------------+
|
||||
| Detail drawer or full page tabs (Inventory | Usage | Components | |
|
||||
| Overlays | Explain | Exports) |
|
||||
+-----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
The catalog and detail views reuse the shared command palette, context chips, and SSE status ticker described in `/docs/ui/navigation.md`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Catalog view
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Virtual table** | Uses Angular CDK virtual scroll to render up to 10,000 records per tenant without layout jank. Sorting and filtering are client-side for <= 20k rows; the UI upgrades to server-side queries automatically when more records exist. |
|
||||
| **Preset segments** | Quick toggles for `All`, `Recent (7 d)`, `Delta-ready`, `Attested`, and `Offline snapshots`. Each preset maps to saved view tokens for CLI parity. |
|
||||
| **Search** | Global search field supports image digests, repository tags, SBOM IDs, and component PURLs. Search terms propagate to the detail view when opened. |
|
||||
| **Badges** | - `Delta` badge indicates SBOM produced via delta mode (layers reuse).<br>- `Attested` badge links to Attestor proof and Rekor record.<br>- `Snapshot` badge shows offline import hash.<br>- `Policy` badge references last policy verdict summary. |
|
||||
| **Bulk actions** | Multi-select rows to stage export jobs, trigger async explain generation, or copy CLI commands. Actions enforce per-tenant rate limits and show authority scopes in tooltips. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Detail tabs
|
||||
|
||||
### 4.1 Inventory tab
|
||||
|
||||
- Default view summarising all components with columns for package name (PURL), version, supplier, license, size, and counts of referencing layers.
|
||||
- Filters: severity, ecosystem (OS, NPM, PyPI, Maven, Go, NuGet, Rust, containers), usage flag (true/false), package tags.
|
||||
- Sorting: by severity (desc), version (asc), supplier.
|
||||
- Cell tooltips reference Concelier advisories and Policy Engine findings when available.
|
||||
- Total component count, unique suppliers, and critical severity counts appear in the header cards.
|
||||
|
||||
### 4.2 Usage tab
|
||||
|
||||
- Focuses on runtime usage (EntryTrace, runtime sensors, allow lists).
|
||||
- Columns include process names, entry points, and `usedByEntrypoint` flags.
|
||||
- Grouping: by entry point, by package, or by namespace (Kubernetes).
|
||||
- Highlights mismatches between declared dependencies and observed usage for drift detection.
|
||||
|
||||
### 4.3 Components tab
|
||||
|
||||
- Deep dive for a single component selected from Inventory or Usage.
|
||||
- Shows provenance timeline (introduced in layer, modified, removed), file paths, cryptographic hashes, and linked evidence (DSSE, Attestor bundles).
|
||||
- Links to CLI commands: `stella sbom component show <digest> <purl>` and `stella sbom component export`.
|
||||
- Drawer supports multi-component comparison through tabbed interface.
|
||||
|
||||
### 4.4 Overlays tab
|
||||
|
||||
- Displays Cartographer overlays: vulnerability overlays (policy verdicts), runtime overlays (process traces), and vendor advisories.
|
||||
- Each overlay card lists source, generation timestamp, precedence, and staleness relative to tenant SLA.
|
||||
- Toggle overlays on/off to see impact on component status; UI does not mutate canonical SBOM, it only enriches the view.
|
||||
- Graph preview button opens force-directed component graph (limited to <= 500 nodes) with filters for dependency depth and relationship type.
|
||||
- Overlay metadata includes the CLI parity snippet: `stella sbom overlay apply --overlay <id> --digest <digest>`.
|
||||
|
||||
### 4.5 Explain tab
|
||||
|
||||
- Integrates Policy Engine explain drawer.
|
||||
- Shows rule hits, VEX overrides, and evidence per component.
|
||||
- Provides "Open in Findings" link that preserves tenant and filters.
|
||||
|
||||
### 4.6 Exports tab
|
||||
|
||||
- Lists available exports (CycloneDX JSON, CycloneDX Protobuf, SPDX JSON, SPDX Tag-Value, Delta bundle, Evidence bundle).
|
||||
- Each export entry shows size, hash (SHA-256), format version, and generation time.
|
||||
- Download buttons respect RBAC and offline quotas; CLI callouts mirror `stella sbom export`.
|
||||
- "Schedule export" launches async job for large bundles; job status integrates with `/console/downloads`.
|
||||
- Includes copy-to-clipboard path for offline transfers (`/offline-kits/export/<tenant>/<digest>/<format>`).
|
||||
|
||||
---
|
||||
|
||||
## 5. Filters and presets
|
||||
|
||||
| Filter | Applies to | Notes |
|
||||
|--------|------------|-------|
|
||||
| **Severity** | Inventory, Overlays, Explain | Uses Policy Engine severity buckets and KEV flag. |
|
||||
| **Ecosystem** | Inventory, Usage | Multi-select list with search; maps to package type derived from PURL. |
|
||||
| **License** | Inventory | Groups by SPDX identifiers; warns on copyleft obligations. |
|
||||
| **Supplier** | Inventory, Components | Autocomplete backed by SBOM metadata. |
|
||||
| **Tags** | Inventory, Usage | Tags provided by Scanner or user-defined metadata. |
|
||||
| **Component search** | Components, Overlays | Accepts PURL or substring; retains highlight when switching tabs. |
|
||||
| **Snapshot** | Catalog | Filters to SBOMs sourced from Offline Kit or local import. |
|
||||
| **Attested only** | Catalog, Exports | Limits to SBOMs signed by Attestor; displays Rekor badge. |
|
||||
|
||||
Saved views store combinations of these filters and expose command palette shortcuts (`Cmd+1-9 / Ctrl+1-9`).
|
||||
|
||||
---
|
||||
|
||||
## 6. Graph overlays and cartography
|
||||
|
||||
- Graph view is powered by Cartographer projections (tenant-scoped graph snapshots).
|
||||
- Supported overlays:
|
||||
- **Dependency graph** (default) - nodes represent components, edges represent dependencies with direction (introducer -> introduced).
|
||||
- **Runtime call graph** - optional overlay layering process calls on top of dependencies.
|
||||
- **Vulnerability overlay** - colours nodes by highest severity and outlines exploited components.
|
||||
- Controls: depth slider (1-6), include transitive flag, hide dev dependencies toggle, highlight vendor-specified critical paths.
|
||||
- Export options: GraphML, JSON Lines, and screenshot capture (requires `graph.export`).
|
||||
- Performance guardrails: overlays warn when node count exceeds 2,000; user can queue background job to render static graph for download instead.
|
||||
|
||||
---
|
||||
|
||||
## 7. Exports and automation
|
||||
|
||||
- **Instant exports:** Inline downloads for CycloneDX JSON/Protobuf (<= 25 MB) and SPDX JSON (<= 25 MB).
|
||||
- **Async exports:** Larger bundles stream through the download manager with resume support. UI polls `/console/downloads` every 15 seconds while export is in progress.
|
||||
- **CLI parity:** Each export card displays the equivalent CLI command and environment variables (proxy, offline).
|
||||
- **Compliance metadata:** Export manifests include SBOM ID, component count, hash, signature state, and policy verdict summary so auditors can validate offline.
|
||||
- **Automation hooks:** Webhook button copies the `/downloads/hooks/subscribe` call for integration with CI pipelines.
|
||||
|
||||
---
|
||||
|
||||
## 8. Performance tips
|
||||
|
||||
- Virtual scroll keeps initial render under 70 ms for 10k rows; server-side pagination engages beyond that threshold.
|
||||
- Graph overlay rendering uses Web Workers to keep main thread responsive; heavy layouts show "Background layout in progress" banner.
|
||||
- SSE updates (new SBOM ready) refresh header cards and prepend rows without full table redraw.
|
||||
- Prefetching: opening a detail drawer preloads overlays and exports concurrently; these requests cancel automatically if the user navigates away.
|
||||
- Local cache (IndexedDB) stores last viewed SBOM detail for each tenant (up to 20 entries). Cache invalidates when new merge hash is observed.
|
||||
|
||||
---
|
||||
|
||||
## 9. Offline and air-gap behaviour
|
||||
|
||||
- Catalog reads from Offline Kit snapshot if gateway is in sealed mode; offline banner lists snapshot ID and staleness.
|
||||
- Overlays limited to data included in snapshot; missing overlays show guidance to import updated Cartographer package.
|
||||
- Exports queue locally and generate tarballs ready to copy to removable media.
|
||||
- CLI parity callouts switch to offline examples (using `stella sbom export --offline`).
|
||||
- Tenants unavailable in snapshot are hidden from the tenant picker to prevent inconsistent views.
|
||||
|
||||
---
|
||||
|
||||
## 10. Screenshot coordination
|
||||
|
||||
- Placeholder images:
|
||||
- ``
|
||||
- ``
|
||||
- Coordinate with Console Guild to capture updated screenshots (dark and light theme) once Sprint 23 UI stabilises. Track follow-up in Console Guild thread `#console-screenshots` dated 2025-10-26.
|
||||
|
||||
---
|
||||
|
||||
## 11. References
|
||||
|
||||
- `/docs/ui/console-overview.md` - navigation shell, tenant model, filters.
|
||||
- `/docs/ui/navigation.md` - command palette, deep-link schema.
|
||||
- `/docs/ui/downloads.md` - download queue, manifest parity, offline export handling.
|
||||
- `/docs/security/console-security.md` - scopes, DPoP, CSP.
|
||||
- `/docs/cli-vs-ui-parity.md` - CLI equivalence matrix.
|
||||
- `/docs/architecture/console.md` (pending) - component data flows.
|
||||
- `/docs/architecture/overview.md` - high-level module relationships.
|
||||
- `/docs/ingestion/aggregation-only-contract.md` - provenance and guard rails.
|
||||
|
||||
---
|
||||
|
||||
## 12. Compliance checklist
|
||||
|
||||
- [ ] Catalog table and detail tabs documented with columns, filters, and presets.
|
||||
- [ ] Overlay behaviour describes Cartographer integration and CLI parity.
|
||||
- [ ] Export section includes instant vs async workflow and compliance metadata.
|
||||
- [ ] Performance considerations align with UI benchmarks (virtual scroll, workers).
|
||||
- [ ] Offline behaviour captured for catalog, overlays, exports.
|
||||
- [ ] Screenshot placeholders and coordination notes recorded with Console Guild follow-up.
|
||||
- [ ] All referenced docs verified and accessible.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 23).*
|
||||
Reference in New Issue
Block a user