stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/policy/ui-integration.md
StellaOps Bot d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
oas-ci / oas-validate (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Policy Simulation / policy-simulate (push) Has been cancelled
Details
devportal-offline / build-offline (push) Has been cancelled
Details
up
2025-11-26 20:23:28 +02:00

2.5 KiB
Raw Permalink Blame History

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