Initial commit

docs/60_POLICY_TEMPLATES.md

@@ -0,0 +1,101 @@
+# 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.*