d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
50 lines
2.5 KiB
Markdown
50 lines
2.5 KiB
Markdown
# Policy Editor Guide
|
|
|
|
> **Imposed rule:** Edits must run lint, simulate, and shadow+coverage gates before promotion; UI enforces attachment of results on submission.
|
|
|
|
This guide walks through the Console Policy Editor: authoring, validation, simulation, approvals, and offline workflow.
|
|
|
|
## 1. Workspace
|
|
- **Left rail:** policy list, versions, status (draft/submitted/approved/active/archived), shadow flag badge.
|
|
- **Editor pane:** YAML/SPL with schema validation, syntax highlighting, auto-format; shows IR hash after successful lint.
|
|
- **Metadata panel:** description, tags, AOC indicator, attestation status.
|
|
- **Attachments panel:** lint report, simulate diff, coverage results; mandatory before submission.
|
|
|
|
## 2. Validation
|
|
- Live lint via compiler service; blocks save on fatal errors.
|
|
- Schema assist: hover shows field descriptions; unknown fields flagged as warnings.
|
|
- Determinism check: twin-run diff runs on save; failures block submission.
|
|
|
|
## 3. Simulation
|
|
- Quick simulate: select fixtures (SBOM/VEX bundles) → runs in shadow mode; results shown inline with deltas vs previous version.
|
|
- Batch simulate: enqueue via orchestrator; results stored as attachments; required freshness <24h for submission.
|
|
|
|
## 4. Submission & approvals
|
|
- Submit requires: lint OK, simulate attachment, coverage results, shadow enabled.
|
|
- Reviewers comment inline; blocking comments must be resolved before approval.
|
|
- Approvers must enter reason/ticket; Authority enforces two-person rule when configured.
|
|
|
|
## 5. Promotion & activation
|
|
- Publish & sign: produces DSSE attestation over IR hash + approval metadata; Rekor mirror when online.
|
|
- Activate: selects approved version; records input cursors; triggers run if requested.
|
|
- Rollback: pick prior approved version; requires reason.
|
|
|
|
## 6. Offline workflow
|
|
- Load policy pack + attachments from Offline Kit; editor runs local lint/simulate with sealed inputs.
|
|
- Submit/approve offline records events locally; sync to Authority when reconnected.
|
|
|
|
## 7. Shortcuts & a11y
|
|
- Keyboard: `Ctrl+S` save, `Ctrl+Shift+L` lint, `Ctrl+Shift+R` simulate.
|
|
- Screen reader labels on editor, results table, and buttons; focus order follows workflow.
|
|
|
|
## 8. Troubleshooting
|
|
- Lint failures: open Problems tab; fix schema/unknown fields.
|
|
- Simulate stale: rerun quick simulate; ensure fixtures match policy inputs.
|
|
- Attestation mismatch: regenerate IR (auto) and retry publish; check Authority scopes.
|
|
|
|
## References
|
|
- `docs/policy/dsl.md`
|
|
- `docs/policy/spl-v1.md`
|
|
- `docs/policy/lifecycle.md`
|
|
- `docs/policy/runtime.md`
|