stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
55464f84984ae579eca18456874ba5ccac6ccf29
git.stella-ops.org/docs/ui/findings.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

9.6 KiB
Raw Blame History

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:
    • ![Findings grid placeholder](../assets/ui/findings/grid-placeholder.png)
    • ![Explain drawer placeholder](../assets/ui/findings/explain-placeholder.png)
  • 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).