feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules
- 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.
This commit is contained in:
@@ -1,179 +1,179 @@
|
||||
# Policy Editor Workspace
|
||||
|
||||
> **Audience:** Product/UX, UI engineers, policy authors/reviewers using the Console.
|
||||
> **Scope:** Layout, features, RBAC, a11y, simulation workflow, approvals, run dashboards, and offline considerations for the Policy Engine v2 editor (“Policy Studio”).
|
||||
|
||||
The Policy Editor is the primary Console workspace for composing, simulating, and approving `stella-dsl@1` policies. It combines Monaco-based editing, diff visualisations, and governance tools so authors and reviewers can collaborate without leaving the browser.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Access & Prerequisites
|
||||
|
||||
- **Routes:** `/console/policy` (list) → `/console/policy/:policyId/:version?`.
|
||||
- **Scopes / roles:**
|
||||
- `policy:author` (role `policy-author`) to edit drafts, run lint/compile, and execute quick simulations.
|
||||
- `policy:review` (role `policy-reviewer`) to review drafts, leave comments, and request changes.
|
||||
- `policy:approve` (role `policy-approver`) to approve or reject submissions.
|
||||
- `policy:operate` (role `policy-operator`) to trigger batch simulations, promotions, and canary runs.
|
||||
- `policy:audit` (role `policy-auditor`) to access immutable history and audit exports.
|
||||
- `policy:simulate` to run simulations from Console; `findings:read` to open explain drawers.
|
||||
- **Feature flags:** `policyStudio.enabled` (defaults true once Policy Engine v2 API available).
|
||||
- **Browser support:** Evergreen Chrome, Edge, Firefox, Safari (last two versions). Uses WASM OPA sandbox; ensure COOP/COEP enabled per [UI architecture](../ARCHITECTURE_UI.md).
|
||||
|
||||
---
|
||||
|
||||
## 2 · Workspace Layout
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Header: Policy selector • tenant switch • last activation banner │
|
||||
├────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Sidebar (left) │ Main content (right) │
|
||||
│ - Revision list │ ┌───────────── Editor tabs ───────────────┐ │
|
||||
│ - Checklist status │ │ DSL │ Simulation │ Approvals │ ... │ │
|
||||
│ - Pending reviews │ └─────────────────────────────────────────┘ │
|
||||
│ - Run backlog │ │
|
||||
│ │ Editor pane / Simulation diff / Run viewer │
|
||||
└────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- **Sidebar:** Revision timeline (draft, submitted, approved), compliance checklist cards, outstanding review requests, run backlog (incremental queue depth and SLA).
|
||||
- **Editor tabs:**
|
||||
- *DSL* (primary Monaco editor)
|
||||
- *Simulation* (pre/post diff charts)
|
||||
- *Approvals* (comments, audit log)
|
||||
- *Runs* (heatmap dashboards)
|
||||
- *Explain Explorer* (optional drawer for findings)
|
||||
- **Right rail:** context cards for VEX providers, policy metadata, quick links to CLI/API docs.
|
||||
|
||||
> Placeholder screenshot: `` (add after UI team captures latest build).
|
||||
|
||||
---
|
||||
|
||||
## 3 · Editing Experience
|
||||
|
||||
- Monaco editor configured for `stella-dsl@1`:
|
||||
- Syntax highlighting, IntelliSense for rule/action names, snippets for common patterns.
|
||||
- Inline diagnostics sourced from `/policies/{id}/lint` and `/compile`.
|
||||
- Code actions (“Fix indentation”, “Insert requireVex block”).
|
||||
- Mini-map disabled by default to reduce contrast noise; toggle available.
|
||||
- **Keyboard shortcuts (accessible via `?`):**
|
||||
- `Ctrl/Cmd + S` – Save draft (uploads to API if changed).
|
||||
- `Ctrl/Cmd + Shift + Enter` – Run lint + compile.
|
||||
- `Ctrl/Cmd + Shift + D` – Open diff view vs baseline.
|
||||
- `Alt + Shift + F` – Format document (canonical ordering).
|
||||
- **Schema tooltips:** Hover on `profile`, `rule`, `action` to view documentation (sourced from DSL doc).
|
||||
- **Offline warnings:** When `sealed` mode detected, banner reminds authors to validate with offline bundle.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Simulation & Diff Panel
|
||||
|
||||
- Triggered via “Run simulation” (toolbar) or automatically after compile.
|
||||
- Displays:
|
||||
- **Summary cards:** total findings added/removed/unchanged; severity up/down counts.
|
||||
- **Rule hit table:** top rules contributing to diffs with percentage change.
|
||||
- **Component list:** virtualised table linking to explain drawer; supports filters (severity, status, VEX outcome).
|
||||
- **Visualisations:** stacked bar chart (severity deltas), sparkline for incremental backlog impact.
|
||||
- Supports run presets:
|
||||
- `Golden SBOM set` (default)
|
||||
- Custom SBOM selection (via multi-select and search)
|
||||
- Import sample JSON from CLI (`Upload diff`).
|
||||
- Diff export options:
|
||||
- `Download JSON` (same schema as CLI output)
|
||||
- `Copy as Markdown` for review comments
|
||||
- Simulation results persist per draft version; history accessible via timeline.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Review & Approval Workflow
|
||||
|
||||
- **Commenting:** Line-level comments anchored to DSL lines; global comments supported. Uses rich text (Markdown subset) with mention support (`@group/sec-reviewers`).
|
||||
- **Resolution:** Approvers/reviewers can mark comment resolved; history preserved in timeline.
|
||||
- **Approval pane:**
|
||||
- Checklist (lint, simulation, determinism CI) with status indicators; links to evidence.
|
||||
- Reviewer checklist (quorum, blocking comments).
|
||||
- Approval button only enabled when checklist satisfied.
|
||||
- **Audit log:** Chronological view of submit/review/approve/archive events with actor, timestamp, note, attachments.
|
||||
- **RBAC feedback:** When user lacks permission, actions are disabled with tooltip referencing required scope(s).
|
||||
- **Notifications:** Integration with Notifier—subscribe/unsubscribe from review reminders within panel.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Runs & Observability
|
||||
|
||||
- **Run tab** consumes `/policy/runs` data:
|
||||
- Heatmap of rule hits per run (rows = runs, columns = top rules).
|
||||
- VEX override counter, suppressions, quieted findings metrics.
|
||||
- Incremental backlog widget (queue depth vs SLA).
|
||||
- Export CSV/JSON button.
|
||||
- **Replay/Download:** For each run, actions to download sealed replay bundle or open CLI command snippet.
|
||||
- **Alert banners:**
|
||||
- Determinism mismatch (red)
|
||||
- SLA breach (amber)
|
||||
- Pending replay (info)
|
||||
|
||||
---
|
||||
|
||||
## 7 · Explain & Findings Integration
|
||||
|
||||
- Inline “Open in Findings” button for any diff entry; opens side drawer with explain trace (same schema as `/findings/*/explain`).
|
||||
- Drawer includes:
|
||||
- Rule sequence with badges (block/warn/quiet).
|
||||
- VEX evidence and justification codes.
|
||||
- Links to advisories (Concelier) and SBOM components.
|
||||
- Copy-to-clipboard (JSON) and “Share permalink” features (permalinks encode tenant, policy version, component).
|
||||
|
||||
---
|
||||
|
||||
## 8 · Accessibility & i18n
|
||||
|
||||
- WCAG 2.2 AA:
|
||||
- Focus order follows logical workflow; skip link available.
|
||||
- All actionable icons paired with text or `aria-label`.
|
||||
- Simulation charts include table equivalents for screen readers.
|
||||
- Keyboard support:
|
||||
- `Alt+1/2/3/4` to switch tabs.
|
||||
- `Shift+?` toggles help overlay (with key map).
|
||||
- Internationalisation:
|
||||
- Translations sourced from `/locales/{lang}.json`.
|
||||
- Date/time displayed using user locale via `Intl.DateTimeFormat`.
|
||||
- Theming:
|
||||
- Light/dark CSS tokens; Monaco theme syncs with overall theme.
|
||||
- High-contrast mode toggled via user preferences.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Offline & Air-Gap Behaviour
|
||||
|
||||
- When console operates in sealed enclave:
|
||||
- Editor displays “Sealed mode” banner with import timestamp.
|
||||
- Simulation uses cached SBOM/advisory/VEX data only; results flagged accordingly.
|
||||
- “Export bundle” button packages draft + simulations for transfer.
|
||||
- Approvals require local Authority; UI blocks actions if `policy:approve` scope absent due to offline token limitations.
|
||||
- Run tab surfaces bundle staleness warnings (`policy_runs.inputs.env.sealed=true`).
|
||||
|
||||
---
|
||||
|
||||
## 10 · Telemetry & Testing Hooks
|
||||
|
||||
- User actions (simulate, submit, approve, activate) emit telemetry (`ui.policy.action` spans) with anonymised metadata.
|
||||
- Console surfaces correlation IDs for lint/compile errors to ease support triage.
|
||||
- Cypress/Playwright fixtures available under `ui/policy-editor/examples/`; docs should note to re-record after significant UI changes.
|
||||
|
||||
---
|
||||
|
||||
## 11 · Compliance Checklist
|
||||
|
||||
- [ ] **Lint integration:** Editor surfaces diagnostics from API compile endpoint; errors link to DSL documentation.
|
||||
- [ ] **Simulation parity:** Diff panel mirrors CLI schema; export button tested.
|
||||
- [ ] **Workflow RBAC:** Buttons enable/disable correctly per scope (`policy:write/submit/review/approve`).
|
||||
- [ ] **A11y verified:** Keyboard navigation, focus management, colour contrast (light/dark) pass automated Axe checks.
|
||||
- [ ] **Offline safeguards:** Sealed-mode banner and bundle export flows present; no network calls trigger in sealed mode.
|
||||
- [ ] **Telemetry wired:** Action spans and error logs include policyId, version, traceId.
|
||||
- [ ] **Docs cross-links:** Links to DSL, lifecycle, runs, API, CLI guides validated.
|
||||
- [ ] **Screenshot placeholders updated:** Replace TODO images with latest UI captures before GA.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 20).*
|
||||
# Policy Editor Workspace
|
||||
|
||||
> **Audience:** Product/UX, UI engineers, policy authors/reviewers using the Console.
|
||||
> **Scope:** Layout, features, RBAC, a11y, simulation workflow, approvals, run dashboards, and offline considerations for the Policy Engine v2 editor (“Policy Studio”).
|
||||
|
||||
The Policy Editor is the primary Console workspace for composing, simulating, and approving `stella-dsl@1` policies. It combines Monaco-based editing, diff visualisations, and governance tools so authors and reviewers can collaborate without leaving the browser.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Access & Prerequisites
|
||||
|
||||
- **Routes:** `/console/policy` (list) → `/console/policy/:policyId/:version?`.
|
||||
- **Scopes / roles:**
|
||||
- `policy:author` (role `policy-author`) to edit drafts, run lint/compile, and execute quick simulations.
|
||||
- `policy:review` (role `policy-reviewer`) to review drafts, leave comments, and request changes.
|
||||
- `policy:approve` (role `policy-approver`) to approve or reject submissions.
|
||||
- `policy:operate` (role `policy-operator`) to trigger batch simulations, promotions, and canary runs.
|
||||
- `policy:audit` (role `policy-auditor`) to access immutable history and audit exports.
|
||||
- `policy:simulate` to run simulations from Console; `findings:read` to open explain drawers.
|
||||
- **Feature flags:** `policyStudio.enabled` (defaults true once Policy Engine v2 API available).
|
||||
- **Browser support:** Evergreen Chrome, Edge, Firefox, Safari (last two versions). Uses WASM OPA sandbox; ensure COOP/COEP enabled per [UI architecture](../modules/ui/architecture.md).
|
||||
|
||||
---
|
||||
|
||||
## 2 · Workspace Layout
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Header: Policy selector • tenant switch • last activation banner │
|
||||
├────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Sidebar (left) │ Main content (right) │
|
||||
│ - Revision list │ ┌───────────── Editor tabs ───────────────┐ │
|
||||
│ - Checklist status │ │ DSL │ Simulation │ Approvals │ ... │ │
|
||||
│ - Pending reviews │ └─────────────────────────────────────────┘ │
|
||||
│ - Run backlog │ │
|
||||
│ │ Editor pane / Simulation diff / Run viewer │
|
||||
└────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- **Sidebar:** Revision timeline (draft, submitted, approved), compliance checklist cards, outstanding review requests, run backlog (incremental queue depth and SLA).
|
||||
- **Editor tabs:**
|
||||
- *DSL* (primary Monaco editor)
|
||||
- *Simulation* (pre/post diff charts)
|
||||
- *Approvals* (comments, audit log)
|
||||
- *Runs* (heatmap dashboards)
|
||||
- *Explain Explorer* (optional drawer for findings)
|
||||
- **Right rail:** context cards for VEX providers, policy metadata, quick links to CLI/API docs.
|
||||
|
||||
> Placeholder screenshot: `` (add after UI team captures latest build).
|
||||
|
||||
---
|
||||
|
||||
## 3 · Editing Experience
|
||||
|
||||
- Monaco editor configured for `stella-dsl@1`:
|
||||
- Syntax highlighting, IntelliSense for rule/action names, snippets for common patterns.
|
||||
- Inline diagnostics sourced from `/policies/{id}/lint` and `/compile`.
|
||||
- Code actions (“Fix indentation”, “Insert requireVex block”).
|
||||
- Mini-map disabled by default to reduce contrast noise; toggle available.
|
||||
- **Keyboard shortcuts (accessible via `?`):**
|
||||
- `Ctrl/Cmd + S` – Save draft (uploads to API if changed).
|
||||
- `Ctrl/Cmd + Shift + Enter` – Run lint + compile.
|
||||
- `Ctrl/Cmd + Shift + D` – Open diff view vs baseline.
|
||||
- `Alt + Shift + F` – Format document (canonical ordering).
|
||||
- **Schema tooltips:** Hover on `profile`, `rule`, `action` to view documentation (sourced from DSL doc).
|
||||
- **Offline warnings:** When `sealed` mode detected, banner reminds authors to validate with offline bundle.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Simulation & Diff Panel
|
||||
|
||||
- Triggered via “Run simulation” (toolbar) or automatically after compile.
|
||||
- Displays:
|
||||
- **Summary cards:** total findings added/removed/unchanged; severity up/down counts.
|
||||
- **Rule hit table:** top rules contributing to diffs with percentage change.
|
||||
- **Component list:** virtualised table linking to explain drawer; supports filters (severity, status, VEX outcome).
|
||||
- **Visualisations:** stacked bar chart (severity deltas), sparkline for incremental backlog impact.
|
||||
- Supports run presets:
|
||||
- `Golden SBOM set` (default)
|
||||
- Custom SBOM selection (via multi-select and search)
|
||||
- Import sample JSON from CLI (`Upload diff`).
|
||||
- Diff export options:
|
||||
- `Download JSON` (same schema as CLI output)
|
||||
- `Copy as Markdown` for review comments
|
||||
- Simulation results persist per draft version; history accessible via timeline.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Review & Approval Workflow
|
||||
|
||||
- **Commenting:** Line-level comments anchored to DSL lines; global comments supported. Uses rich text (Markdown subset) with mention support (`@group/sec-reviewers`).
|
||||
- **Resolution:** Approvers/reviewers can mark comment resolved; history preserved in timeline.
|
||||
- **Approval pane:**
|
||||
- Checklist (lint, simulation, determinism CI) with status indicators; links to evidence.
|
||||
- Reviewer checklist (quorum, blocking comments).
|
||||
- Approval button only enabled when checklist satisfied.
|
||||
- **Audit log:** Chronological view of submit/review/approve/archive events with actor, timestamp, note, attachments.
|
||||
- **RBAC feedback:** When user lacks permission, actions are disabled with tooltip referencing required scope(s).
|
||||
- **Notifications:** Integration with Notifier—subscribe/unsubscribe from review reminders within panel.
|
||||
|
||||
---
|
||||
|
||||
## 6 · Runs & Observability
|
||||
|
||||
- **Run tab** consumes `/policy/runs` data:
|
||||
- Heatmap of rule hits per run (rows = runs, columns = top rules).
|
||||
- VEX override counter, suppressions, quieted findings metrics.
|
||||
- Incremental backlog widget (queue depth vs SLA).
|
||||
- Export CSV/JSON button.
|
||||
- **Replay/Download:** For each run, actions to download sealed replay bundle or open CLI command snippet.
|
||||
- **Alert banners:**
|
||||
- Determinism mismatch (red)
|
||||
- SLA breach (amber)
|
||||
- Pending replay (info)
|
||||
|
||||
---
|
||||
|
||||
## 7 · Explain & Findings Integration
|
||||
|
||||
- Inline “Open in Findings” button for any diff entry; opens side drawer with explain trace (same schema as `/findings/*/explain`).
|
||||
- Drawer includes:
|
||||
- Rule sequence with badges (block/warn/quiet).
|
||||
- VEX evidence and justification codes.
|
||||
- Links to advisories (Concelier) and SBOM components.
|
||||
- Copy-to-clipboard (JSON) and “Share permalink” features (permalinks encode tenant, policy version, component).
|
||||
|
||||
---
|
||||
|
||||
## 8 · Accessibility & i18n
|
||||
|
||||
- WCAG 2.2 AA:
|
||||
- Focus order follows logical workflow; skip link available.
|
||||
- All actionable icons paired with text or `aria-label`.
|
||||
- Simulation charts include table equivalents for screen readers.
|
||||
- Keyboard support:
|
||||
- `Alt+1/2/3/4` to switch tabs.
|
||||
- `Shift+?` toggles help overlay (with key map).
|
||||
- Internationalisation:
|
||||
- Translations sourced from `/locales/{lang}.json`.
|
||||
- Date/time displayed using user locale via `Intl.DateTimeFormat`.
|
||||
- Theming:
|
||||
- Light/dark CSS tokens; Monaco theme syncs with overall theme.
|
||||
- High-contrast mode toggled via user preferences.
|
||||
|
||||
---
|
||||
|
||||
## 9 · Offline & Air-Gap Behaviour
|
||||
|
||||
- When console operates in sealed enclave:
|
||||
- Editor displays “Sealed mode” banner with import timestamp.
|
||||
- Simulation uses cached SBOM/advisory/VEX data only; results flagged accordingly.
|
||||
- “Export bundle” button packages draft + simulations for transfer.
|
||||
- Approvals require local Authority; UI blocks actions if `policy:approve` scope absent due to offline token limitations.
|
||||
- Run tab surfaces bundle staleness warnings (`policy_runs.inputs.env.sealed=true`).
|
||||
|
||||
---
|
||||
|
||||
## 10 · Telemetry & Testing Hooks
|
||||
|
||||
- User actions (simulate, submit, approve, activate) emit telemetry (`ui.policy.action` spans) with anonymised metadata.
|
||||
- Console surfaces correlation IDs for lint/compile errors to ease support triage.
|
||||
- Cypress/Playwright fixtures available under `ui/policy-editor/examples/`; docs should note to re-record after significant UI changes.
|
||||
|
||||
---
|
||||
|
||||
## 11 · Compliance Checklist
|
||||
|
||||
- [ ] **Lint integration:** Editor surfaces diagnostics from API compile endpoint; errors link to DSL documentation.
|
||||
- [ ] **Simulation parity:** Diff panel mirrors CLI schema; export button tested.
|
||||
- [ ] **Workflow RBAC:** Buttons enable/disable correctly per scope (`policy:write/submit/review/approve`).
|
||||
- [ ] **A11y verified:** Keyboard navigation, focus management, colour contrast (light/dark) pass automated Axe checks.
|
||||
- [ ] **Offline safeguards:** Sealed-mode banner and bundle export flows present; no network calls trigger in sealed mode.
|
||||
- [ ] **Telemetry wired:** Action spans and error logs include policyId, version, traceId.
|
||||
- [ ] **Docs cross-links:** Links to DSL, lifecycle, runs, API, CLI guides validated.
|
||||
- [ ] **Screenshot placeholders updated:** Replace TODO images with latest UI captures before GA.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-26 (Sprint 20).*
|
||||
|
||||
Reference in New Issue
Block a user