git.stella-ops.org/docs/modules/ui/reachability-witnessing/README.md

Reachability Witnessing

Status: Implemented Owner shell: Security > Reachability Canonical routes: /security/reachability/coverage, /security/reachability/witnesses, /security/reachability/witnesses/:witnessId, /security/reachability/poe, /security/reachability/poe/:artifactId, /security/reachability/gaps

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

Shipped Behavior

Mounted shell

• Coverage remains the default entry and keeps the fleet posture summary.
• Witnesses ships a searchable, filterable list with confidence and verdict filters.
• PoE / Exposure keeps drawer-first inspection and supports direct permalink routes for export and audit use.
• Sensor Gaps stays inside the same shell rather than fragmenting into a separate product.

Witness detail

• Loads the requested witness from the witness API when available.
• Falls back to deterministic reachability fixtures when the backend is unavailable.
• Ships call-path, gate, caveat, evidence-chain, runtime-observation, and related-context sections.
• Supports verify, JSON export, DOT export, Mermaid export, and PoE drill-in actions.

Proof-of-exposure detail

• Opens by default as a contextual drawer from witness or shell entry points.
• Supports direct navigation through /security/reachability/poe/:artifactId.
• Preserves operator context with returnTo when launched from findings, triage, evidence replay, or release detail.

Cross-product handoffs

• Security > Findings links into canonical witness routes instead of owning a second proof view.
• Triage > Artifact Workspace restores the selected finding and tab when returning from reachability.
• Evidence > Verify & Replay links the current request into reachability proof review.
• Releases > Detail links release-gate investigation into reachability without branching to a parallel shell.

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.

Verification Status

• Angular verification: targeted route, witness-detail, handoff, and release-context tests passed on 2026-03-07.
• Playwright verification: witness detail, PoE drawer/permalink, and Verify & Replay handoff passed on 2026-03-07.
• Checked feature note: docs/features/checked/web/reachability-witnessing-ui.md

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