# Stella Policy DSL (`stella-dsl@1`) > **Audience:** Policy authors, reviewers, and tooling engineers building lint/compile flows for the Policy Engine v2 rollout (Sprint 20). This document specifies the `stella-dsl@1` grammar, semantics, and guardrails used by Stella Ops to transform SBOM facts, Concelier advisories, and Excititor VEX statements into effective findings. Use it with the [Policy Engine Overview](overview.md) for architectural context and the upcoming lifecycle/run guides for operational workflows. --- ## 1 · Design Goals - **Deterministic:** Same policy + same inputs ⇒ identical findings on every machine. - **Declarative:** No arbitrary loops, network calls, or clock access. - **Explainable:** Every decision records the rule, inputs, and rationale in the explain trace. - **Lean authoring:** Common precedence, severity, and suppression patterns are first-class. - **Offline-friendly:** Grammar and built-ins avoid cloud dependencies, run the same in sealed deployments. --- ## 2 · Document Structure Policy packs ship one or more `.stella` files. Each file contains exactly one `policy` block: ```dsl policy "Default Org Policy" syntax "stella-dsl@1" { metadata { description = "Baseline severity + VEX precedence" tags = ["baseline","vex"] } profile severity { map vendor_weight { source "GHSA" => +0.5 source "OSV" => +0.0 source "VendorX" => -0.2 } env exposure_adjustments { if env.runtime == "serverless" then -0.5 if env.exposure == "internal-only" then -1.0 } } rule vex_precedence priority 10 { when vex.any(status in ["not_affected","fixed"]) and vex.justification in ["component_not_present","vulnerable_code_not_present"] then status := vex.status because "Strong vendor justification prevails"; } } ``` High-level layout: | Section | Purpose | |---------|---------| | `metadata` | Optional descriptive fields surfaced in Console/CLI. | | `imports` | Reserved for future reuse (not yet implemented in `@1`). | | `profile` blocks | Declarative scoring modifiers (`severity`, `trust`, `reachability`). | | `rule` blocks | When/then logic applied to each `(component, advisory, vex[])` tuple. | | `settings` | Optional evaluation toggles (sampling, default status overrides). | --- ## 3 · Lexical Rules - **Case sensitivity:** Keywords are lowercase; identifiers are case-sensitive. - **Whitespace:** Space, tab, newline act as separators. Indentation is cosmetic. - **Comments:** `// inline` and `/* block */` are ignored. - **Literals:** - Strings use double quotes (`"text"`); escape with `\"`, `\n`, `\t`. - Numbers are decimal; suffix `%` allowed for percentage weights (`-2.5%` becomes `-0.025`). - Booleans: `true`, `false`. - Lists: `[1, 2, 3]`, `["a","b"]`. - **Identifiers:** Start with letter or underscore, continue with letters, digits, `_`. - **Operators:** `=`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`, `not in`, `and`, `or`, `not`, `:=`. --- ## 4 · Grammar (EBNF) ```ebnf policy = "policy", string, "syntax", string, "{", policy-body, "}" ; policy-body = { metadata | profile | settings | rule | helper } ; metadata = "metadata", "{", { meta-entry }, "}" ; meta-entry = identifier, "=", (string | list) ; profile = "profile", identifier, "{", { profile-item }, "}" ; profile-item= map | env-map | scalar ; map = "map", identifier, "{", { "source", string, "=>", number, ";" }, "}" ; env-map = "env", identifier, "{", { "if", expression, "then", number, ";" }, "}" ; scalar = identifier, "=", (number | string | list), ";" ; settings = "settings", "{", { setting-entry }, "}" ; setting-entry = identifier, "=", (number | string | boolean), ";" ; rule = "rule", identifier, [ "priority", integer ], "{", "when", predicate, { "and", predicate }, "then", { action }, [ "else", { action } ], [ "because", string ], "}" ; predicate = expression ; expression = term, { ("and" | "or"), term } ; term = ["not"], factor ; factor = comparison | membership | function-call | literal | identifier | "(" expression ")" ; comparison = value, comparator, value ; membership = value, ("in" | "not in"), list ; value = identifier | literal | function-call | field-access ; field-access= identifier, { ".", identifier | "[" literal "]" } ; function-call = identifier, "(", [ arg-list ], ")" ; arg-list = expression, { ",", expression } ; literal = string | number | boolean | list ; action = assignment | ignore | escalate | require | warn | defer | annotate ; assignment = target, ":=", expression, ";" ; target = identifier, { ".", identifier } ; ignore = "ignore", [ "until", expression ], [ "because", string ], ";" ; escalate = "escalate", [ "to", expression ], [ "when", expression ], ";" ; require = "requireVex", "{", require-fields, "}", ";" ; warn = "warn", [ "message", string ], ";" ; defer = "defer", [ "until", expression ], ";" ; annotate = "annotate", identifier, ":=", expression, ";" ; ``` Notes: - `helper` is reserved for shared calculcations (not yet implemented in `@1`). - `else` branch executes only if `when` predicates evaluate truthy **and** no prior rule earlier in priority handled the tuple. - Semicolons inside rule bodies are optional when each clause is on its own line; the compiler emits canonical semicolons in IR. --- ## 5 · Evaluation Context Within predicates and actions you may reference the following namespaces: | Namespace | Fields | Description | |-----------|--------|-------------| | `sbom` | `purl`, `name`, `version`, `licenses`, `layerDigest`, `tags`, `usedByEntrypoint` | Component metadata from Scanner. | | `advisory` | `id`, `source`, `aliases`, `severity`, `cvss`, `publishedAt`, `modifiedAt`, `content.raw` | Canonical Concelier advisory view. | | `vex` | `status`, `justification`, `statementId`, `timestamp`, `scope` | Current VEX statement when iterating; aggregator helpers available. | | `vex.any(...)`, `vex.all(...)`, `vex.count(...)` | Functions operating over all matching statements. | | `run` | `policyId`, `policyVersion`, `tenant`, `timestamp` | Metadata for explain annotations. | | `env` | Arbitrary key/value pairs injected per run (e.g., `environment`, `runtime`). | | `telemetry` | Optional reachability signals; missing fields evaluate to `unknown`. | | `profile.` | Values computed inside profile blocks (maps, scalars). | Missing fields evaluate to `null`, which is falsey in boolean context and propagates through comparisons unless explicitly checked. --- ## 6 · Built-ins (v1) | Function / Property | Signature | Description | |---------------------|-----------|-------------| | `normalize_cvss(advisory)` | `Advisory → SeverityScalar` | Parses `advisory.content.raw` for CVSS data; falls back to policy maps. | | `cvss(score, vector)` | `double × string → SeverityScalar` | Constructs a severity object manually. | | `severity_band(value)` | `string → SeverityBand` | Normalises strings like `"critical"`, `"medium"`. | | `risk_score(base, modifiers...)` | Variadic | Multiplies numeric modifiers (severity × trust × reachability). | | `vex.any(predicate)` | `(Statement → bool) → bool` | `true` if any statement satisfies predicate. | | `vex.all(predicate)` | `(Statement → bool) → bool` | `true` if all statements satisfy predicate. | | `vex.latest()` | `→ Statement` | Lexicographically newest statement. | | `advisory.has_tag(tag)` | `string → bool` | Checks advisory metadata tags. | | `advisory.matches(pattern)` | `string → bool` | Glob match against advisory identifiers. | | `sbom.has_tag(tag)` | `string → bool` | Uses SBOM inventory tags (usage vs inventory). | | `exists(expression)` | `→ bool` | `true` when value is non-null/empty. | | `coalesce(a, b, ...)` | `→ value` | First non-null argument. | | `days_between(dateA, dateB)` | `→ int` | Absolute day difference (UTC). | | `percent_of(part, whole)` | `→ double` | Fractions for scoring adjustments. | | `lowercase(text)` | `string → string` | Normalises casing deterministically (InvariantCulture). | All built-ins are pure; if inputs are null the result is null unless otherwise noted. --- ## 7 · Rule Semantics 1. **Ordering:** Rules execute in ascending `priority`. When priorities tie, lexical order defines precedence. 2. **Short-circuit:** Once a rule sets `status`, subsequent rules only execute if they use `combine`. Use this sparingly to avoid ambiguity. 3. **Actions:** - `status := ` – Allowed values: `affected`, `not_affected`, `fixed`, `suppressed`, `under_investigation`, `escalated`. - `severity := ` – Either from `normalize_cvss`, `cvss`, or numeric map; ensures `normalized` and `score`. - `ignore until ` – Temporarily treats finding as suppressed until timestamp; recorded in explain trace. - `warn message ""` – Adds warn verdict and deducts `warnPenalty`. - `escalate to severity_band("critical") when condition` – Forces verdict severity upward when condition true. - `requireVex { vendors = ["VendorX"], justifications = ["component_not_present"] }` – Fails evaluation if matching VEX evidence absent. - `annotate reason := "text"` – Adds free-form key/value pairs to explain payload. 4. **Because clause:** Mandatory for actions changing status or severity; captured verbatim in explain traces. --- ## 8 · Scoping Helpers - **Maps:** Use `profile severity { map vendor_weight { ... } }` to declare additive factors. Retrieve with `profile.severity.vendor_weight["GHSA"]`. - **Environment overrides:** `env` profiles allow conditional adjustments based on runtime metadata. - **Tenancy:** `run.tenant` ensures policies remain tenant-aware; avoid hardcoding single-tenant IDs. - **Default values:** Use `settings { default_status = "affected"; }` to override built-in defaults. --- ## 9 · Examples ### 9.1 Baseline Severity Normalisation ```dsl rule advisory_normalization { when advisory.source in ["GHSA","OSV"] then severity := normalize_cvss(advisory) because "Align vendor severity to CVSS baseline"; } ``` ### 9.2 VEX Override with Quiet Mode ```dsl rule vex_strong_claim priority 5 { when vex.any(status == "not_affected") and vex.justification in ["component_not_present","vulnerable_code_not_present"] then status := vex.status annotate winning_statement := vex.latest().statementId warn message "VEX override applied" because "Strong VEX justification"; } ``` ### 9.3 Environment-Specific Escalation ```dsl rule internet_exposed_guard { when env.exposure == "internet" and severity.normalized >= "High" then escalate to severity_band("Critical") because "Internet-exposed assets require critical posture"; } ``` ### 9.4 Anti-pattern (flagged by linter) ```dsl rule catch_all { when true then status := "suppressed" because "Suppress everything" // ❌ Fails lint: unbounded suppression } ``` --- ## 10 · Validation & Tooling - `stella policy lint` ensures: - Grammar compliance and canonical formatting. - Static determinism guard (no forbidden namespaces). - Anti-pattern detection (e.g., unconditional suppression, missing `because`). - `stella policy compile` emits IR (`.stella.ir.json`) and SHA-256 digest used in `policy_runs`. - CI pipelines (see `DEVOPS-POLICY-20-001`) compile sample packs and fail on lint violations. - Simulation harnesses (`stella policy simulate`) highlight provided/queried fields so policy authors affirm assumptions before promotion. --- ## 11 · Anti-patterns & Mitigations | Anti-pattern | Risk | Mitigation | |--------------|------|------------| | Catch-all suppress/ignore without scope | Masks all findings | Linter blocks rules with `when true` unless `priority` > 1000 and justification includes remediation plan. | | Comparing strings with inconsistent casing | Missed matches | Wrap comparisons in `lowercase(value)` to align casing or normalise metadata during ingest. | | Referencing `telemetry` without fallback | Null propagation | Wrap access in `exists(telemetry.reachability)`. | | Hardcoding tenant IDs | Breaks multi-tenant | Prefer `env.tenantTag` or metadata-sourced predicates. | | Duplicated rule names | Explain trace ambiguity | Compiler enforces unique `rule` identifiers within a policy. | --- ## 12 · Versioning & Compatibility - `syntax "stella-dsl@1"` is mandatory. - Future revisions (`@2`, …) will be additive; existing packs continue to compile with their declared version. - The compiler canonicalises documents (sorted keys, normalised whitespace) before hashing to ensure reproducibility. --- ## 13 · Compliance Checklist - [ ] **Grammar validated:** Policy compiles with `stella policy lint` and matches `syntax "stella-dsl@1"`. - [ ] **Deterministic constructs only:** No use of forbidden namespaces (`DateTime.Now`, `Guid.NewGuid`, external services). - [ ] **Rationales present:** Every status/severity change includes a `because` clause or `annotate` entry. - [ ] **Scoped suppressions:** Rules that ignore/suppress findings reference explicit components, vendors, or VEX justifications. - [ ] **Explain fields verified:** `annotate` keys align with Console/CLI expectations (documented in upcoming lifecycle guide). - [ ] **Offline parity tested:** Policy pack simulated in sealed mode (`--sealed`) to confirm absence of network dependencies. --- *Last updated: 2025-10-26 (Sprint 20).*