189 lines
5.7 KiB
Markdown
189 lines
5.7 KiB
Markdown
# Reachability Witnessing
|
|
|
|
## Recommendation
|
|
|
|
Restore witness and proof-of-exposure UX as a deeper part of `Security > Reachability`, not as a standalone product.
|
|
|
|
- Canonical mount: `/security/reachability`
|
|
- Suggested user-facing title: `Reachability`
|
|
- Supporting label inside the shell: `Witnesses & Proof`
|
|
|
|
This capability should strengthen security investigation, release gating, and evidence review through reusable witness detail pages and proof drawers.
|
|
|
|
## Why This Is The Right Shape
|
|
|
|
- `ReachabilityCenterComponent` already owns the top-level reachability posture.
|
|
- `WitnessPageComponent` and `PoEDrawerComponent` are evidence and explanation layers of the same capability.
|
|
- Reachability proof matters in findings, triage, policy/VEX decisions, and release gates, so it must be reusable from multiple contexts.
|
|
- A single shell prevents proof UX from fragmenting across security, evidence, and release flows.
|
|
|
|
## Operator Modes
|
|
|
|
### 1. Coverage Review Mode
|
|
- Used by security operators checking graph coverage, sensor freshness, and fleet posture.
|
|
- Focus: `Coverage` and `Sensor Gaps`.
|
|
|
|
### 2. Investigation Mode
|
|
- Used by analysts validating whether a vulnerable path is reachable and why.
|
|
- Focus: `Witnesses` and `PoE / Exposure`.
|
|
|
|
### 3. Release Context Mode
|
|
- Entered from release gates, policy/VEX decisions, or evidence review.
|
|
- Focus: witness explanation, proof verification, and return-to-release navigation.
|
|
|
|
## Recommended IA
|
|
|
|
### Primary tabs
|
|
- `Coverage`
|
|
- fleet and package coverage, recent graph updates, confidence overview
|
|
- `Witnesses`
|
|
- searchable witness list and full witness detail page
|
|
- `PoE / Exposure`
|
|
- proof-of-exposure artifacts, export, verify, transparency status
|
|
- `Sensor Gaps`
|
|
- missing sensors, stale data, unresolved evidence dependencies
|
|
|
|
### Witness detail sections
|
|
- summary
|
|
- call path and gates
|
|
- confidence and caveats
|
|
- related findings and releases
|
|
- evidence chain and export actions
|
|
|
|
## Page Anatomy
|
|
|
|
### Coverage tab
|
|
- summary cards:
|
|
- analyzed artifacts
|
|
- coverage confidence
|
|
- stale witness count
|
|
- open gaps
|
|
- tables or cards:
|
|
- per-environment coverage
|
|
- hot CVEs lacking proof
|
|
|
|
### Witnesses tab
|
|
- list filters:
|
|
- artifact
|
|
- package
|
|
- CVE
|
|
- verdict
|
|
- confidence
|
|
- environment
|
|
- row preview:
|
|
- witness id
|
|
- subject
|
|
- vulnerability
|
|
- verdict
|
|
- confidence
|
|
- last observed
|
|
- witness detail page:
|
|
- proof summary header
|
|
- path explorer
|
|
- gates and confidence
|
|
- related evidence
|
|
- replay/verify/export actions
|
|
|
|
### PoE / Exposure tab
|
|
- proof list with status chips
|
|
- right drawer for proof detail by default
|
|
- optional permalink route for export and audit deep links
|
|
|
|
### Sensor Gaps tab
|
|
- backlog queues for:
|
|
- missing runtime signals
|
|
- stale graph facts
|
|
- unresolved symbol sources
|
|
- missing environment bindings
|
|
|
|
## Route Contract
|
|
|
|
Keep one canonical route family under security reachability.
|
|
|
|
### Canonical routes
|
|
- `/security/reachability`
|
|
- `/security/reachability/coverage`
|
|
- `/security/reachability/witnesses`
|
|
- `/security/reachability/witnesses/:witnessId`
|
|
- `/security/reachability/poe`
|
|
- `/security/reachability/poe/:artifactId`
|
|
- `/security/reachability/gaps`
|
|
|
|
### Query-param state
|
|
- `tab=coverage|witnesses|poe|gaps`
|
|
- `panel=poe|evidence|related`
|
|
- `returnTo=<encoded route>` for findings, triage, evidence, or releases
|
|
|
|
### Alias rules
|
|
- any future `evidence` or `release` entry points should deep-link here rather than mount duplicate witness pages
|
|
|
|
## What To Merge
|
|
|
|
### Merge into `Coverage`
|
|
- `ReachabilityCenterComponent`
|
|
|
|
### Merge into `Witnesses`
|
|
- `WitnessPageComponent`
|
|
|
|
### Merge into `PoE / Exposure`
|
|
- `PoEDrawerComponent`
|
|
|
|
### Preserve as shared behaviors
|
|
- export DOT and Mermaid actions
|
|
- proof verification actions
|
|
- evidence-chain cards
|
|
|
|
## Single Actions And Supporting Surfaces
|
|
|
|
### Witness detail
|
|
- full page under `Witnesses`
|
|
- preserve permalink and return-to-context behavior
|
|
|
|
### PoE detail
|
|
- default to a right drawer from witness detail, finding detail, triage, or release context
|
|
- allow a standalone route for exports and audit deep links
|
|
|
|
### Export or replay verify
|
|
- keep as actions on witness or PoE detail
|
|
- do not create separate pages per export type
|
|
|
|
### Related finding navigation
|
|
- keep as contextual links in the witness detail sidebar
|
|
|
|
## Cross-Product Entry Points
|
|
|
|
- `Security > Findings`
|
|
- open witness detail for a finding
|
|
- `Triage > Artifact Workspace`
|
|
- open witness or PoE from artifact detail
|
|
- `Evidence > Verify & Replay`
|
|
- open proof verification in the same witness/PoE model
|
|
- `Decisioning Studio` or `Releases`
|
|
- open witness and proof for gate verdict explanation
|
|
|
|
## UI Standards For Implementation
|
|
|
|
- Keep witness detail as the canonical deep-link target.
|
|
- Default proof detail to a drawer to preserve investigation context.
|
|
- Preserve return-to-context links so operators can move back to findings or release flows.
|
|
- Reuse evidence cards and path visualizations across security, evidence, and release entry points.
|
|
- Keep graph and proof loading deterministic and evidence-first.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not create a top-level `Witnessing` product.
|
|
- Do not split coverage, witness, and proof UX across unrelated sidebar branches.
|
|
- Do not leave PoE as a drawer with no canonical parent route.
|
|
|
|
## Source Inputs
|
|
|
|
- `docs/contracts/witness-v1.md`
|
|
- `docs/architecture/EVIDENCE_PIPELINE_ARCHITECTURE.md`
|
|
- `docs/modules/scanner/reachability.md`
|
|
- `docs/modules/ui/architecture-rework.md`
|
|
- `src/Web/StellaOps.Web/src/app/features/reachability/reachability-center.component.ts`
|
|
- `src/Web/StellaOps.Web/src/app/features/reachability/witness-page.component.ts`
|
|
- `src/Web/StellaOps.Web/src/app/features/reachability/poe-drawer.component.ts`
|
|
- `src/Web/StellaOps.Web/src/app/routes/security-risk.routes.ts`
|
|
- `src/Web/StellaOps.Web/src/app/routes/evidence.routes.ts`
|