d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
# Policy UI Integration for Graph/Vuln
|
||
|
||
Status: Draft (2025-11-26) — aligns with POLICY-ENGINE-30-001..003 and Graph API overlays.
|
||
|
||
## Goals
|
||
- Explain how UI surfaces (Console, Vuln Explorer) consume policy/VEX overlays from Graph.
|
||
- Clarify cache usage, simulator contracts, and explain traces.
|
||
|
||
## Data sources
|
||
- Policy overlays (`policy.overlay.v1`) produced by Policy Engine (POLICY-ENGINE-30-001).
|
||
- VEX overlays (`openvex.v1`) from Concelier/Excititor pipelines.
|
||
- Graph API emits overlays per node (see `docs/api/graph.md`) with deterministic IDs and optional `explainTrace` sampling.
|
||
|
||
## Cache rules
|
||
- UI should respect overlay cache TTL (5–10 minutes). Cache key: tenant + nodeId + overlay kind.
|
||
- On cache miss, fallback to Graph API which will populate cache; avoid fan-out calls per tile.
|
||
- When policy overlay contract version changes, invalidate cache via version tag (e.g., `policy.overlay.v1` → `v2`).
|
||
|
||
## Requests
|
||
- Graph API: `includeOverlays=true` on `/graph/query` or `/graph/paths` to receive overlay payloads inline.
|
||
- Budget: ensure `budget.tiles` leaves room for overlays; UI may need to request higher budgets when overlays are critical to UX.
|
||
- Simulator: when running policy simulator, attach `X-Stella-Simulator: true` header (once enabled) to route to simulator instance; cache should be bypassed for simulator runs.
|
||
|
||
## UI rendering guidance
|
||
- Show policy status badge (e.g., `warn`, `deny`, `allow`) with ruleId and severity.
|
||
- If `explainTrace` present, render as expandable list; only one sampled node per query may include trace.
|
||
- VEX overlays: render status (`not_affected`, `affected`) and justification; show issued timestamp and source.
|
||
- Overlay provenance: display `overlayId`, version, and source engine version if present.
|
||
|
||
## Error handling
|
||
- If Graph returns `GRAPH_BUDGET_EXCEEDED`, prompt user to reduce scope or increase budgets; do not silently drop overlays.
|
||
- On overlay cache miss + upstream failure, surface a non-blocking warning and proceed with node data.
|
||
|
||
## Events & notifications
|
||
- Subscribe to `policy.overlay.updated` (future) or re-poll every 10 minutes to refresh overlays in UI.
|
||
- When VEX status changes, UI should refresh impacted nodes/edges and reflect new status badges.
|
||
|
||
## References
|
||
- Policy overlay contract: `docs/modules/policy/prep/2025-11-22-policy-engine-30-001-prep.md`
|
||
- Graph API overlays: `docs/api/graph.md`, `docs/modules/graph/architecture-index.md`
|
||
- Concelier/Excititor overlays: `docs/modules/excititor/vex_observations.md`
|