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
117 lines
3.8 KiB
Markdown
117 lines
3.8 KiB
Markdown
# Stella Policy Language (SPL) v1
|
|
|
|
> **Status:** Draft (2025-11)
|
|
> **Imposed rule:** SPL packs must pass lint, simulate, shadow, and coverage gates before activation; IR hashes must be attested when published.
|
|
|
|
This document defines the SPL v1 language: syntax, semantics, JSON schema, and examples used by the Policy Engine.
|
|
|
|
## 1. Syntax summary
|
|
- File-level directive: `policy "<name>" syntax "stella-dsl@1" { ... }`
|
|
- Blocks: `metadata`, `profile <name> {}`, `settings {}`, `rule <name> [priority n] { when ... then ... because "..." }`
|
|
- No loops, no network/clock access; pure, deterministic evaluation.
|
|
|
|
## 2. JSON Schema (canonical IR)
|
|
|
|
```jsonc
|
|
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"title": "Stella Policy Language v1",
|
|
"type": "object",
|
|
"required": ["policyId", "syntax", "rules"],
|
|
"properties": {
|
|
"policyId": {"type": "string"},
|
|
"syntax": {"const": "stella-dsl@1"},
|
|
"metadata": {"type": "object"},
|
|
"settings": {
|
|
"type": "object",
|
|
"properties": {
|
|
"shadow": {"type": "boolean"},
|
|
"default_status": {"type": "string"}
|
|
}
|
|
},
|
|
"profiles": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"properties": {
|
|
"maps": {"type": "object"},
|
|
"env": {"type": "object"},
|
|
"scalars": {"type": "object"}
|
|
}
|
|
}
|
|
},
|
|
"rules": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["name", "when", "then"],
|
|
"properties": {
|
|
"name": {"type": "string"},
|
|
"priority": {"type": "integer", "minimum": 0},
|
|
"when": {"type": "object"},
|
|
"then": {"type": "array"},
|
|
"else": {"type": "array"},
|
|
"because": {"type": "string"}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Notes:
|
|
- The compiler emits canonical IR JSON sorted by keys; hashing uses this canonical form.
|
|
- `when` and actions are expressed as AST nodes; see engine schema for exact shape.
|
|
|
|
## 3. Built-in functions (v1)
|
|
- `normalize_cvss`, `cvss`, `severity_band`, `risk_score`, `reach_state`, `exists`, `coalesce`, `percent_of`, `lowercase`.
|
|
- VEX helpers: `vex.any`, `vex.all`, `vex.latest`.
|
|
- Secrets helpers: `secret.hasFinding`, `secret.match.count`, `secret.bundle.version`, `secret.mask.applied`, `secret.path.allowlist`.
|
|
- Signals: access via `signals.trust_score`, `signals.reachability.state/score`, `signals.entropy_penalty`, `signals.uncertainty.level`, `signals.runtime_hits`.
|
|
|
|
## 4. Data namespaces
|
|
- `sbom`, `advisory`, `vex`, `run`, `env`, `telemetry`, `signals`, `secret`, `profile.*`.
|
|
- Missing fields evaluate to `null/unknown`; comparisons must handle `unknown` explicitly.
|
|
|
|
## 5. Examples
|
|
|
|
### 5.1 Reachability-aware gate
|
|
```dsl
|
|
rule reachability_gate priority 20 {
|
|
when signals.reachability.state == "reachable" and signals.reachability.score >= 0.6
|
|
then status := "affected"
|
|
because "Runtime/graph evidence shows reachable code path";
|
|
}
|
|
```
|
|
|
|
### 5.2 Trust/entropy penalty
|
|
```dsl
|
|
rule trust_entropy_penalty priority 30 {
|
|
when signals.trust_score < 0.4 or signals.entropy_penalty > 0.2
|
|
then severity := severity_band("critical")
|
|
because "Low trust score or high entropy";
|
|
}
|
|
```
|
|
|
|
### 5.3 Shadow mode on
|
|
```dsl
|
|
settings {
|
|
shadow = true
|
|
}
|
|
```
|
|
|
|
## 6. Authoring workflow (quick)
|
|
1. Write/update SPL with shadow enabled; add coverage fixtures.
|
|
2. Run `stella policy lint`, `stella policy simulate`, and `stella policy test`.
|
|
3. Attach artefacts to submission; ensure determinism twin-run passes in CI.
|
|
4. Publish with DSSE attestation (IR hash + metadata) and promote to environments.
|
|
|
|
## 7. Compatibility
|
|
- SPL v1 aligns with `stella-dsl@1` grammar. Future SPL versions will be additive; declare `syntax` explicitly.
|
|
|
|
## 8. References
|
|
- `docs/policy/dsl.md`
|
|
- `docs/policy/lifecycle.md`
|
|
- `docs/policy/architecture.md`
|
|
- `docs/policy/overview.md`
|