Add Policy DSL Validator, Schema Exporter, and Simulation Smoke tools
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implemented PolicyDslValidator with command-line options for strict mode and JSON output. - Created PolicySchemaExporter to generate JSON schemas for policy-related models. - Developed PolicySimulationSmoke tool to validate policy simulations against expected outcomes. - Added project files and necessary dependencies for each tool. - Ensured proper error handling and usage instructions across tools.
This commit is contained in:
191
docs/ui/policies.md
Normal file
191
docs/ui/policies.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# 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:**
|
||||
- `policy:read` (list and details)
|
||||
- `policy:write` (edit drafts, run lint/compile)
|
||||
- `policy:submit`, `policy:review`, `policy:approve` (workflow actions)
|
||||
- `policy:runs` (view run history)
|
||||
- `policy:simulate` (run simulations)
|
||||
- `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:write`, `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:runs`, `policy:simulate` | Approve/promote, trigger runs, view run history. |
|
||||
| **Operator** | `policy:read`, `policy:runs`, `policy:simulate`, `effective:write` | Schedule promotions, monitor runs (no editing). |
|
||||
| **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:
|
||||
- ``
|
||||
- ``
|
||||
- ``
|
||||
- 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).*
|
||||
|
||||
Reference in New Issue
Block a user