stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
55464f84984ae579eca18456874ba5ccac6ccf29
git.stella-ops.org/docs/ui/policies.md
root 68da90a11a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Restructure solution layout by module
2025-10-28 15:10:40 +02:00

10 KiB
Raw Blame History

StellaOps Console - Policies Workspace

Audience: Policy Guild, Console UX, product ops, review leads.
Scope: Policy workspace navigation, editor surfaces, simulation, approvals, RBAC, observability, offline behaviour, and CLI parity for Sprint 23.

The Policies workspace centralises authoring, simulation, review, and promotion for stella-dsl@1 packs. It builds on the Policy Editor (docs/ui/policy-editor.md) and adds list views, governance workflows, and integrations with runs and findings.

1. Access and prerequisites

  • Routes:
    • /console/policies (list)
    • /console/policies/:policyId (details)
    • /console/policies/:policyId/:revision (editor, approvals, runs)
  • Scopes / roles:
    • policy:read (list and details)
    • policy:author (edit drafts, run lint/compile)
    • policy:review, policy:approve (workflow actions)
    • policy:operate (promotions, run orchestration)
    • policy:simulate (run simulations)
    • policy:audit (download audit bundles)
    • effective:write (promotion visibility only; actual write remains server-side)
  • Feature flags: policy.studio.enabled, policy.simulation.diff, policy.runCharts.enabled, policy.offline.bundleUpload.
  • Dependencies: Policy Engine v2 APIs (/policies, /policy/runs, /policy/simulations), Policy Studio Monaco assets, Authority fresh-auth flows for critical operations.

2. List and detail views

2.1 Policy list

Column Description
Policy Human-readable name plus policy ID (e.g., P-7).
State Active, Draft, Staged, Simulation, Archived. Badge colours align with Policy Engine status.
Revision Latest revision digest (short SHA).
Owner Primary maintainer or owning team tag.
Last change Timestamp and actor of last update (edit, submit, approve).
Pending approvals Count of outstanding approval requests (with tooltip listing reviewers).

Row actions: Open, Duplicate, Export pack, Run simulation, Compare revisions.

Filters: owning team, state, tag, pending approvals, contains staged changes, last change window, simulation warnings (determinism, failed run).

2.2 Policy detail header

  • Summary cards: current state, digest, active revision, staged revision (if any), simulation status, last production run (timestamp, duration, determinism hash).
  • Action bar: Edit draft, Run simulation, Submit for review, Promote, Export pack, View findings.

3. Editor shell

The editor view reuses the structure documented in /docs/ui/policy-editor.md and adds:

  • Context banner showing tenant, policy ID, revision digest, and simulation badge if editing sandbox copy.
  • Lint and compile status displayed inline with time since last run.
  • Checklist sidebar summarising required steps (lint pass, simulation run, deterministic CI, security review). Each item links to evidence (e.g., latest simulation diff).
  • Monaco integration with policy-specific snippets, schema hover, code actions (Insert allowlist, Add justification).
  • Draft autosave every 30 seconds with conflict detection (merges disabled; last write wins with warning).

4. Simulation workflows

  • Simulation modal accepts SBOM filter (golden set, specific SBOM IDs, tenant-wide) and options for VEX weighting overrides.
  • Simulations run asynchronously; progress shown in run ticker with status updates.
  • Diff view summarises totals: affected findings added/removed, severity up/down counts, quieted changes.
  • Side-by-side diff (Active vs Simulation) accessible directly from policy detail.
  • Export options: JSON diff, Markdown summary, CLI snippet stella policy simulate --policy <id> --sbom <sbomId>.
  • Simulation results cached per draft revision. Cache invalidates when draft changes or SBOM snapshot updates.
  • Simulation compliance card requires at least one up-to-date simulation before submission.

5. Review and approval

  • Review requests: Authors tag reviewers; review sidebar lists pending reviewers, due dates, and escalation contact.
  • Comments: Threaded comments support markdown, mentions, and attachments (redacted before persistence). Comment resolution required before approval.
  • Approval checklist:
    • Lint/compile success
    • Simulation fresh (within configured SLA)
    • Determinism verification passed
    • Security review (if flagged)
    • Offline bundle prepared (optional)
  • Fresh-auth: Approve/promote buttons require fresh authentication; modal prompts for credentials and enforces short-lived token (<5 minutes).
  • Approval audit: Approval events recorded with correlation ID, digests, reviewer note, effective date, and optional ticket link.

6. Promotion and rollout

  • Promotion dialog summarises staged changes, target tenants, release windows, and run plan (full vs incremental).
  • Operators can schedule promotion or apply immediately.
  • Promotion triggers Policy Engine to materialise new revision; console reflects status and shows run progress.
  • CLI parity: stella policy promote --policy <id> --revision <rev> --run-mode full.
  • Rollback guidance accessible from action bar (Open rollback instructions) linking to CLI command and documentation.

7. Runs and observability

  • Runs tab displays table of recent runs with columns: run ID, type (full, incremental, simulation), duration, determinism hash, findings delta counts, triggered by.
  • Charts: findings trend, quieted findings trend, rule hit heatmap (top rules vs recent runs).
  • Clicking a run opens run detail drawer showing inputs (policy digest, SBOM batch hash, advisory snapshot hash), output summary, and explain bundle download.
  • Error runs display red badge; detail drawer includes correlation ID and link to Policy Engine logs.
  • SSE updates stream run status changes to keep UI real-time.

8. RBAC and governance

Role Scopes Capabilities
Author policy:read, policy:author, policy:simulate Create drafts, run lint/simulations, comment.
Reviewer policy:read, policy:review, policy:simulate Leave review comments, request changes.
Approver policy:read, policy:approve, policy:operate, policy:simulate Approve/promote, trigger runs, view run history.
Operator policy:read, policy:operate, policy:simulate, effective:write Schedule promotions, monitor runs (no editing).
Auditor policy:read, policy:audit, policy:simulate View immutable history, export audit bundles.
Admin Above plus Authority admin scopes Manage roles, configure escalation chains.

UI disables controls not allowed by current scope and surfaces tooltip with required scope names. Audit log captures denied attempts (policy.ui.action_denied).

9. Exports and offline bundles

  • Export pack button downloads policy pack (zip) with metadata, digest manifest, and README.
  • Offline bundle uploader allows importing reviewed packs; UI verifies signatures and digests before applying.
  • Explain bundle export collects latest run explain traces for audit.
  • CLI parity:
    • stella policy export --policy <id> --revision <rev>
    • stella policy bundle import --file <bundle>
    • stella policy bundle export --policy <id> --revision <rev>
  • Offline mode displays banner and disables direct promotion; provides script instructions for offline runner.

10. Observability and alerts

  • Metrics cards show policy_run_seconds, policy_rules_fired_total, policy_determinism_failures_total.
  • Alert banners surfaced for determinism failures, simulation stale warnings, approval SLA breaches.
  • Links to dashboards (Grafana) pre-filtered with policy ID.
  • Telemetry panel lists last emitted events (policy.promoted, policy.simulation.completed).

11. Offline and air-gap considerations

  • In sealed mode, editor warns about cached enrichment data; simulation run button adds tooltip explaining degraded evidence.
  • Promotions queue and require manual CLI execution on authorised host; UI provides downloadable job manifest.
  • Run charts switch to snapshot data; SSE streams disabled, replaced by manual refresh button.
  • Export/download buttons label file paths for removable media transfer.

12. Screenshot coordination

  • Placeholders:
    • ![Policy list placeholder](../assets/ui/policies/list-placeholder.png)
    • ![Policy approval placeholder](../assets/ui/policies/approval-placeholder.png)
    • ![Simulation diff placeholder](../assets/ui/policies/simulation-placeholder.png)
  • Coordinate with Console Guild via #console-screenshots (entry 2025-10-26) to replace placeholders once UI captures are ready (light and dark themes).

13. References

  • /docs/ui/policy-editor.md - detailed editor mechanics.
  • /docs/ui/findings.md - downstream findings view and explain drawer.
  • /docs/policy/overview.md and /docs/policy/runs.md - Policy Engine contracts.
  • /docs/security/authority-scopes.md - scope definitions.
  • /docs/cli/policy.md - CLI commands for policy management.
  • /docs/ui/console-overview.md - navigation shell and filters.

14. Compliance checklist

  • Policy list and detail workflow documented (columns, filters, actions).
  • Editor shell extends Policy Studio guidance with checklists and lint/simulation integration.
  • Simulation flow, diff presentation, and CLI parity captured.
  • Review, approval, and promotion workflows detailed with scope gating.
  • Runs dashboard, metrics, and SSE behaviour described.
  • Exports and offline bundle handling included.
  • Offline/air-gap behaviour and screenshot coordination recorded.
  • References validated.

Last updated: 2025-10-26 (Sprint 23).