master
7b5bdcf4d3
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes. - Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes. - Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables. - Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
193 lines
9.8 KiB
Markdown
193 lines
9.8 KiB
Markdown
# 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:
|
|
- ``
|
|
- ``
|
|
- ``
|
|
- 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/modules/cli/guides/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).*
|