up

docs/ui/sbom-graph-explorer.md

@@ -0,0 +1,47 @@
+# SBOM Graph Explorer
+
+> **Imposed rule:** Saved views and exports must include the overlay + filter set that produced them; do not distribute stripped exports.
+
+The SBOM Graph Explorer lets operators traverse components, dependencies, and reachability overlays with deterministic filters suitable for online and air-gapped consoles.
+
+## Views & overlays
+- **Inventory vs Usage overlays:** toggle to see declared packages (inventory) or runtime-observed packages (usage). Overlays are rendered as chips; colors align with graph legend.
+- **Reachability overlay:** highlights components reachable from entrypoints; respects cached reachability results from Graph API. Disabled when `reachability_source` is stale (>24h) to avoid misleading badges.
+- **Policy overlay:** displays allow/deny/review verdicts from Policy Engine; shows cache epoch and simulator marker when viewing staged policy.
+- **VEX overlay:** marks components covered by active VEX claims (Excititor); conflict states (pending/contested) surface as striped badges.
+
+## Filters
+- **Package facets:** ecosystem, name (supports substring and PURL), version, license, and supplier.
+- **Reachability facets:** entrypoint, call depth, and evidence source (static/runtime/edge bundle).
+- **Risk facets:** severity band, EPSS bucket, KEV flag, exploitability score.
+- **Time facets:** last-seen (usage), last-scan (inventory) to surface staleness.
+- Filters are additive; results are deterministically sorted by component PURL, then version.
+
+## Saved views
+- Saved views capture query, overlays, column set, sort, and tenant. They are stored per tenant and tagged with `graph_cache_epoch` to detect stale caches.
+- Export saved view: downloads NDJSON with `view_id`, `filters`, `overlays`, `results[]`, and SHA-256 manifest. Works offline; includes attestations if available.
+- Restoring a view warns when cache epoch differs; users can refresh overlays before applying.
+
+## Interactions
+- **Graph canvas:** zoom/pan; node tooltip shows PURL, reachability, licenses, and open issues count. Double-click expands neighbors; capped by `ui.graph.maxNodes` to keep performance deterministic.
+- **Table panel:** synchronized with canvas selection; supports column picker and keyboard navigation (arrow keys, Enter to open drawer).
+- **Details drawer:** shows component metadata, provenance (source SBOM digest + Rekor UUID if attested), and outgoing/incoming edges with reachability evidence.
+- **Search bar:** accepts PURL, package name, or CVE; CVE search auto-filters to affected components via vulnerability overlay.
+
+## Accessibility
+- Full keyboard navigation: Tab/Shift+Tab moves between canvas, filters, table, drawer. Canvas focus ring is visible at 3:1 contrast.
+- Screen reader labels include overlay state (e.g., “node: openssl 3.0.12, reachable, vex-contested”).
+- High-contrast mode uses solid fills; motion reduced when `prefers-reduced-motion` is set.
+
+## Air-gap & caching
+- Works with offline Graph API bundles; overlays and filters use cached results when `graph_cache_epoch` matches. Exports include cache epoch to keep audits deterministic.
+- Prefers client-side cache for back/forward navigation; cache invalidates on tenant switch or overlay version change.
+
+## AOC visibility
+- Aggregation-Only Contract surfaces in the header when viewing regulated tenants; UI disables ad-hoc joins and shows “AOC enforced” badge. Exports include `aoc=true` flag.
+
+## Related docs
+- `docs/api/graph.md`
+- `docs/modules/graph/architecture-index.md`
+- `docs/policy/ui-integration.md`
+- `docs/modules/cli/guides/graph-and-vuln.md`

docs/ui/vulnerability-explorer.md

@@ -0,0 +1,51 @@
+# Vulnerability Explorer
+
+> **Imposed rule:** Any exported or shared view must include the data sources and overlays applied (VEX, policy, reachability) to avoid out-of-context remediation decisions.
+
+The Vulnerability Explorer provides deterministic tables and grouping to triage, explain, and act on vulns across SBOM graph data and VEX claims.
+
+## Table anatomy
+- Default columns: CVE/alias, package (PURL), version, severity, exploitability (EPSS/KEV), reachability, VEX status, fix version, policy verdict, last seen.
+- Sorting: primary by severity (desc), secondary by exploitability score, tertiary by PURL; ties broken by CVE.
+- Pagination: server-driven with stable cursors; page size defaults to 50, override via `?limit=`.
+
+## Grouping & pivots
+- Group by **package**, **CVE**, **image**, or **tenant**. Each group shows counts by severity and VEX disposition.
+- “Why am I seeing this?” drawer explains grouping rules and shows upstream data sources for the group.
+- Export follows the active grouping; NDJSON includes `group_key`, `items[]`, and overlay metadata.
+
+## Filters
+- **Severity**: critical/high/medium/low/none.
+- **Exploitability**: KEV flag, EPSS bucket, exploit maturity.
+- **Reachability**: reachable, conditionally reachable, unreachable, unknown.
+- **VEX**: affected, not_affected, under_investigation, disputed, contested.
+- **Fix availability**: has fix, no fix, downgrade available.
+- **Policy verdict**: allow, review, deny, staged verdicts (simulator).
+- **Staleness**: SBOM age, advisory feed age, VEX claim age.
+
+## Why drawer
+- Provides a structured explanation showing: data sources (SBOM digest, overlay epochs), policy inputs, VEX claims contributing to the verdict, and reachability evidence. Includes correlation IDs for API traces.
+- Always shows tenant and `graph_cache_epoch` to keep exports/audits reproducible.
+
+## Fix suggestions
+- Per-row “Fix” chip suggests the nearest patched version and source (vendor vs upstream), plus link to remediation doc if provided by advisory.
+- Bulk fix export produces an actions file: `{purl, vuln, recommended_version, source, rationale}` with SHA-256 manifest.
+- UI warns when fixes rely on contested VEX claims or stale advisories.
+
+## Actions & triage
+- Multi-select with bulk actions: create ticket, generate VEX waiver request, export SBOM diff, or open policy simulator with selected rows.
+- Policy simulator opens with current overlays and generates a simulated verdict for the selection; results can be saved as a “staged policy” view.
+
+## Accessibility
+- Keyboard shortcuts: `g` to toggle grouping, `f` to focus filters, `w` to open Why drawer on selected row, `/` to focus search.
+- Screen reader labels announce VEX and reachability state; focus order matches visual order; table rows support row headers.
+
+## Air-gap posture
+- All exports include overlays and cache epochs; offline bundles can be loaded via `Import view` to replay triage without network.
+- No live CVE enrichment calls from the UI; it relies solely on backend-provided overlays.
+
+## Related docs
+- `docs/ui/sbom-graph-explorer.md`
+- `docs/api/graph.md`
+- `docs/api/vuln.md`
+- `docs/modules/graph/architecture-index.md`