git.stella-ops.org/docs/policy/spl-v1.md

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)

{
  "$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

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

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

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