master
7b5bdcf4d3
- 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.
180 lines
9.4 KiB
Markdown
180 lines
9.4 KiB
Markdown
# 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:
|
|
- ``
|
|
- ``
|
|
- 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/modules/cli/guides/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).*
|
|
|