# Policy Templates — YAML & Rego Examples

Stella Ops lets you enforce *pass / fail* rules in two ways:

1. **YAML “quick policies”** — simple equality / inequality checks.  
2. **OPA Rego modules** — full‑power logic for complex organisations.

> **Precedence:** If the same image is subject to both a YAML rule *and* a Rego
> module, the **Rego result wins**.  That is, `deny` in Rego overrides any
> `allow` in YAML.

---

## 1 · YAML quick policy

```yaml
# file: policies/root_user.yaml
version: 1
id: root-user
description: Disallow images that run as root
severity: high

rules:
  - field: ".config.user"
    operator: "equals"
    value: "root"
    deny_message: "Image runs as root — block."
````

Place the file under `/opt/stella/plugins/policies/`.

---

## 2 · Rego example (deny on critical CVE)

```rego
# file: policies/deny_critical.rego
package stella.policy

default deny = []

deny[msg] {
  some f
  input.findings[f].severity == "critical"
  msg := sprintf("Critical CVE %s – build blocked", [input.findings[f].id])
}
```

*Input schema* — the Rego `input` document matches the public
`ScanResult` POCO (see SDK).  Use the bundled JSON schema in
`share/schemas/scanresult.schema.json` for IDE autocompletion.

---

## 3 · Pass‑through warnings (Rego)

Return a `warn` array to surface non‑blocking messages in the UI:

```rego
package stella.policy

warn[msg] {
  input.image.base == "ubuntu:16.04"
  msg := "Image uses EOL Ubuntu 16.04 — please upgrade."
}
```

Warnings decrement the **quality score** but do *not* affect the CLI exit
code.

---

## 4 · Testing policies locally

```bash
# run policy evaluation without pushing to DB
stella scan alpine:3.20 --policy-only \
  --policies ./policies/
```

The CLI prints `PASS`, `WARN` or `DENY` plus structured JSON.

Unit‑test your Rego modules with the OPA binary:

```bash
opa test policies/
```

---

## 5 · Developer quick‑start (plug‑ins)

Need logic beyond Rego?  Implement a plug‑in via **C#/.NET {{ dotnet }}** and
the `StellaOps.SDK` NuGet:

* Tutorial: [`dev/30_PLUGIN_DEV_GUIDE.md`](dev/30_PLUGIN_DEV_GUIDE.md)
* Quick reference: `/plugins/`

---

*Last updated {{ "now" | date: "%Y‑%m‑%d" }} — constants auto‑injected.*