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). Imposed rule: Policies that alter reachability or trust weighting must run in shadow mode first with coverage fixtures; promotion to active is blocked until shadow + coverage gates pass.

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 for architectural context, the Policy Lifecycle and Policy Runs guides for operational workflows, and the Policy Editor guide for Console authoring.

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.
• Reachability-aware: Policies can consume reachability lattice states (ReachState) and evidence scores to drive VEX gates (not_affected, under_investigation, affected).
• Signal-first: Trust, reachability, entropy, and uncertainty signals are first-class so explain traces stay reproducible.

2 · Document Structure

Policy packs ship one or more .stella files. Each file contains exactly one policy block:

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";
  }

  rule reachability_gate priority 20 {
    when telemetry.reachability.state == "reachable" and telemetry.reachability.score >= 0.6
    then status := "affected"
    because "Runtime/graph evidence shows reachable code path";
  }

  rule trust_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";
  }
}

High-level layout:

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)

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 calculations (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.
• settings.shadow = true enables shadow-mode evaluation (findings recorded but not enforced). Promotion gates require at least one shadow run with coverage fixtures.

5 · Evaluation Context

Within predicates and actions you may reference the following namespaces:

Reachability evidence gate. When reachability.state == "unreachable" but reachability.evidence_ref is missing (or confidence is below the high-confidence threshold), Policy Engine downgrades the state to under_investigation to avoid false “not affected” claims.

Secrets namespace. When StellaOps.Scanner.Analyzers.Secrets is enabled the Policy Engine receives masked findings (secret.findings[*]) plus bundle metadata (secret.bundle.id, secret.bundle.version). Policies should rely on the helper predicates listed below rather than reading raw arrays to preserve determinism and future compatibility.

Missing fields evaluate to null, which is falsey in boolean context and propagates through comparisons unless explicitly checked.

6 · Built-ins (v1)

All built-ins are pure; if inputs are null the result is null unless otherwise noted.

6.1 · Ruby Component Scope

Inside sbom.any_component(...), Ruby gems surface a ruby scope with the following helpers:

Scheduler capability sub-types use dot notation (ruby.capability("scheduler.sidekiq")) and inherit from the broad scheduler capability.

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 := <string> – Allowed values: affected, not_affected, fixed, suppressed, under_investigation, escalated.
   • severity := <SeverityScalar> – Either from normalize_cvss, cvss, or numeric map; ensures normalized and score.
   • ignore until <ISO-8601> – Temporarily treats finding as suppressed until timestamp; recorded in explain trace.
   • warn message "<text>" – 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

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

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

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 Shadow mode & coverage

• Enable settings { shadow = true; } for new policies or major changes. Findings are recorded but not enforced.
• Provide coverage fixtures under tests/policy/<policyId>/cases/*.json; run stella policy test locally and in CI. Coverage results must be attached on submission.
• Promotion to active is blocked until shadow runs + coverage gates pass (see the Policy Lifecycle guide).

9.5 Authoring workflow (quick checklist)

1. Write/update policy with shadow enabled.
2. Add/refresh coverage fixtures; run stella policy test.
3. stella policy lint and stella policy simulate --fixtures ... with expected signals (trust_score, reachability, entropy_penalty) noted in comments.
4. Submit with attachments: lint, simulate diff, coverage results.
5. After approval, disable shadow and promote; retain fixtures for regression tests.

9.6 Anti-pattern (flagged by linter)

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

12 · Uncertainty Gates (U1/U2/U3)

Uncertainty gates enforce evidence-quality thresholds before a policy is allowed to commit to a high-confidence VEX decision. When evidence is missing or signal entropy is high, a policy should downgrade the verdict to under_investigation rather than risk a false not_affected claim.

The relevant signal is signals.uncertainty.level, which the Policy Engine normalises into three tiers (see §5, Evaluation Context):

12.1 Gating on Uncertainty Level

Hold a not_affected outcome until uncertainty is resolved:

rule gate_high_uncertainty priority 4 {
  when vex.any(status == "not_affected")
       and signals.uncertainty.level == "U1"
  then status := "under_investigation"
       annotate uncertainty_gate := "U1: missing core resolution"
  because "High uncertainty must be resolved before accepting not_affected";
}

12.2 Tier-Aware Compound Rules

Combine an uncertainty tier with a reachability state for nuanced gating — for example, allow a downgrade only when both confidence and reachability evidence are strong:

rule accept_low_uncertainty priority 6 {
  when vex.any(status == "not_affected")
       and signals.uncertainty.level == "U3"
       and signals.reachability.state == "unreachable"
       and exists(signals.reachability.evidence_ref)
  then status := vex.status
  because "Low uncertainty plus reachability evidence supports not_affected";
}

12.3 Remediation Guidance

Policies should steer authors and operators toward reducing uncertainty rather than silently accepting a weak verdict. Use annotate to surface the required next step alongside the gated verdict:

Restore needed. The detailed uncertainty-gate tier thresholds, the per-gate block/allow matrix, and the YAML configuration block that previously lived in this section were lost in an earlier edit and could not be reconstructed from a verifiable source. Treat the rules above as illustrative until the canonical thresholds are restored from the Policy Engine determinization configuration (see Policy architecture).

13 · Signed Override Enforcement (Sprint 20260112.004)

Signed VEX overrides provide cryptographic assurance that operator decisions (not_affected, compensating controls) are authentic and auditable. The Policy Engine exposes override signature status to DSL rules for enforcement.

13.1 Override Signal Namespace

Within predicates and actions you may reference the following override signals:

13.2 Enforcement Rules

13.2.1 Require Signed Overrides

Block unsigned VEX overrides from being accepted:

rule require_signed_overrides priority 1 {
  when vex.any(status in ["not_affected", "fixed"])
       and not override.signed
  then status := "under_investigation"
       annotate override_blocked := "Unsigned override rejected"
  because "Production environments require signed VEX overrides";
}

13.2.2 Require Rekor Anchoring for Critical Assets

For critical assets, require transparency log anchoring:

rule require_rekor_for_critical priority 2 {
  when env.asset_tier == "critical"
       and vex.any(status == "not_affected")
       and override.signed
       and not override.rekor_verified
  then status := "under_investigation"
       warn message "Critical asset requires Rekor-anchored override"
  because "Critical assets require transparency log verification";
}

13.2.3 Trust Level Gating

Gate override acceptance based on signer trust level:

rule gate_by_trust_level priority 5 {
  when override.signed
       and override.key_trust_level in ["Unknown", "LowTrust"]
       and env.security_posture == "strict"
  then status := "under_investigation"
       annotate trust_gate_failed := override.signer_identity
  because "Strict posture requires OrganizationTrusted or higher";
}

13.2.4 Validity Period Enforcement

Reject expired or not-yet-valid overrides:

rule enforce_validity_period priority 3 {
  when override.signed
       and exists(override.valid_until)
       and not override.within_validity_period
  then status := "affected"
       annotate override_expired := override.valid_until
  because "VEX override has expired or is not yet valid";
}

13.3 Default Enforcement Profile

The default enforcement profile blocks unsigned overrides in production:

settings {
  require_signed_overrides = true;
  require_rekor_for_production = false;
  minimum_trust_level = "OrganizationTrusted";
  enforce_validity_period = true;
}

Override these settings in environment-specific policy packs.

13.4 Offline Mode Considerations

In sealed/offline deployments:

• override.rekor_verified evaluates to false (no network access to verify).
• Use embedded proofs in the DSSE envelope for signature verification.
• Policies should fall back to signature verification without requiring Rekor:

rule offline_safe_override priority 5 {
  when env.sealed_mode == true
       and override.signed
       and override.key_trust_level in ["OrganizationTrusted", "HighlyTrusted"]
  then status := vex.status
  because "Offline mode accepts signed overrides from trusted keys without Rekor";
}

14 · 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.

15 · 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 (see the Policy Lifecycle guide).
• [ ] Offline parity tested: Policy pack simulated in sealed mode (--sealed) to confirm absence of network dependencies.

Last updated: 2025-12-13 (Sprint 0401).