stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

Add Policy DSL Validator, Schema Exporter, and Simulation Smoke tools
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source 
- 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:
master
2025-10-27 08:00:11 +02:00
parent 651b8e0fa3
commit 96d52884e8
712 changed files with 49449 additions and 6124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
docs/security/policy-governance.md Normal file
View File

@@ -0,0 +1,114 @@
# Policy Governance & Least Privilege
> **Audience:** Security Guild, Policy Guild, Authority Core, auditors.
> **Scope:** Scopes, RBAC, approval controls, tenancy, auditing, and compliance requirements for Policy Engine v2.
---
## 1 · Governance Principles
1. **Least privilege by scope** – API clients receive only the `policy:*` scopes required for their role; `effective:write` reserved for service identity.
2. **Immutable history** – All policy changes, approvals, runs, and suppressions produce audit artefacts retrievable offline.
3. **Separation of duties** – Authors cannot approve their own submissions; approvers require distinct scope and should not have deployment rights.
4. **Deterministic verification** – Simulations, determinism checks, and incident replay bundles provide reproducible evidence for auditors.
5. **Tenant isolation** – Policies, runs, and findings scoped to tenants; cross-tenant access requires explicit admin scopes and is logged.
6. **Offline parity** – Air-gapped sites follow the same governance workflow with sealed-mode safeguards and signed bundles.
---
## 2 · Authority Scopes & Role Mapping
| Scope | Description | Recommended role |
|-------|-------------|------------------|
| `policy:read` | View policies, revisions, runs, findings. | Readers, auditors. |
| `policy:write` | Create/edit drafts, run lint/compile. | Authors (SecOps engineers). |
| `policy:submit` | Move draft → submitted, attach simulations. | Authors with submission rights. |
| `policy:review` | Comment/approve/request changes (non-final). | Reviewers (peer security, product). |
| `policy:approve` | Final approval; can archive. | Approval board/security lead. |
| `policy:activate` | Promote approved version, schedule activation. | Runtime operators / release managers. |
| `policy:run` | Trigger runs, inspect live status. | Operators, automation bots. |
| `policy:runs` | Read run history, replay bundles. | Operators, auditors. |
| `policy:archive` | Retire versions, perform rollbacks. | Approvers, operators. |
| `policy:simulate` | Execute simulations via API/CLI. | Authors, reviewers, CI. |
| `policy:operate` | Activate incident mode, toggle sampling. | SRE/on-call. |
| `findings:read` | View effective findings/explain. | Analysts, auditors, CLI. |
| `effective:write` | **Service only** – materialise findings. | Policy Engine service principal. |
> Map organisation roles to scopes via Authority issuer config (`authority.tenants[].roles`). Document assignments in tenant onboarding checklist.
> **Authority configuration tip:** the Policy Engine service client must include `properties.serviceIdentity: policy-engine` and a tenant hint in `authority.yaml`. Authority rejects `effective:write` tokens that lack this marker. See [Authority scopes](authority-scopes.md) for the full scope catalogue.
---
## 3 · Workflow Controls
- **Submit gate:** CLI/UI require fresh lint + simulation artefacts (<24 h). Submissions store reviewer list and diff attachments.
- **Review quorum:** Authority policy enforces minimum reviewers (e.g., 2) and optional separation between functional/security domains.
- **Approval guard:** Approvers must acknowledge simulation + determinism check completion. CLI enforces `--note` and `--attach` fields.
- **Activation guard:** Policy Engine refuses activation when latest full run status ≠ success or incremental backlog aged > SLA.
- **Rollback policy:** Rollbacks require incident reference and produce `policy.rollback` audit events.
---
## 4 · Tenancy & Data Access
- Policies stored per tenant; `tenant-global` used for shared baselines.
- API filters all requests by `X-Stella-Tenant` (default from token). Cross-tenant requests require `policy:tenant-admin`.
- Effective findings collections include `tenant` field and unique indexes preventing cross-tenant writes.
- CLI/Console display tenant context prominently; switching tenant triggers warnings when active policy differs.
- Offline bundles encode tenant metadata; import commands validate compatibility before applying.
---
## 5 · Audit & Evidence
- **Collections:** `policies`, `policy_reviews`, `policy_history`, `policy_runs`, `policy_run_events`, `effective_finding_*_history`.
- **Events:** `policy.submitted`, `policy.review.requested`, `policy.approved`, `policy.activated`, `policy.archived`, `policy.run.*`, `policy.incident.*`.
- **Explain traces:** Stored for critical findings (sampled); available via CLI/UI for auditors (requires `findings:read`).
- **Offline evidence:** `stella policy bundle export` produces DSSE-signed packages containing DSL, IR digest, simulations, approval notes, run summaries, trace metadata.
- **Retention:** Default 365 days for run history, extendable per compliance requirements; incident mode extends to 30 days minimum.
---
## 6 · Secrets & Configuration Hygiene
- Policy Engine configuration loaded from environment/secret stores; no secrets in repo.
- CLI profiles should store tokens encrypted (`stella profile set --secret`).
- UI/CLI logs redact tokens, reviewer emails, and attachments.
- Rotating tokens/keys: Authority exposes `policy scopes` in discovery docs; follow `/docs/security/authority-scopes.md` for rotation.
- Use `policy:operate` to disable self-service simulation temporarily during incident response if needed.
---
## 7 · Incident Response
- Trigger incident mode for determinism violations, backlog surges, or suspected policy abuse.
- Capture replay bundles and run `stella policy run replay` for affected runs.
- Coordinate with Observability dashboards (see `/docs/observability/policy.md`) to monitor queue depth, failures.
- After resolution, document remediation in Lifecycle guide (§8) and attach to approval history.
---
## 8 · Offline / Air-Gapped Governance
- Same scopes apply; tokens issued by local Authority.
- Approvers must use offline UI/CLI to sign submissions; attachments stored locally.
- Bundle import/export must be signed (DSSE + cosign). CLI warns if signatures missing.
- Sealed-mode banner reminds operators to refresh bundles when staleness thresholds exceeded.
- Offline audits rely on evidence bundles and local `policy_runs` snapshot.
---
## 9 · Compliance Checklist
- [ ] **Scope mapping reviewed:** Authority issuer config updated; RBAC matrix stored with change request.
- [ ] **Separation enforced:** Automated checks block self-approval; review quorum satisfied.
- [ ] **Activation guard documented:** Operators trained on run health checks before promoting.
- [ ] **Audit exports tested:** Evidence bundles verified (hash/signature) and stored per compliance policy.
- [ ] **Incident drills rehearsed:** Replay/rollback procedures executed and logged.
- [ ] **Offline parity confirmed:** Air-gapped site executes submit/approve flow with sealed-mode guidance.
- [ ] **Documentation cross-links:** References to lifecycle, runs, observability, CLI, and API docs validated.
---
*Last updated: 2025-10-26 (Sprint 20).*