Builtin rules and custom Rego

Outcome

By the end of this lesson, you will be able to navigate the builtin rule set and its compliance-framework tagging, decide when custom Rego is warranted, and explain the native-first loading model.

1. Concept

The rules ship with the product. You do not write them to get started, and you can write your own once the builtin set stops being enough.

70 builtin rules, 11 categories

governance      security        iam
networking      cost            reliability
provider        change          data
observability   kubernetes

The set is deliberately broad rather than cost-only, because an IaC gate that checks only cost is a gate teams will not keep. Once you have a decision point in the pull request, the marginal cost of also checking that a bucket is not public is close to zero.

Every rule carries compliance-framework tags

CIS   PCI   SOC2   HIPAA   NIST   ISO   FinOps

This is the feature that makes the rule set usable in an audit conversation rather than only in an engineering one.

THE QUESTION IT ANSWERS
  "Which of our IaC controls map to SOC 2?"

WITHOUT TAGS  someone reads 70 rule descriptions and
              makes a judgement call, annually, and it
              is never quite the same judgement.

WITH TAGS     filter by framework, export the list, and
              the mapping is the same next year.

Pair this with the audit-log control mapping from T3.M3.3.L4 and you have two halves of the same evidence story: what your platform enforces, and what your people did.

Custom Rego, and when it is warranted

CUSTOM POLICIES ARE REAL OPA REGO, SANDBOXED:
  no network access
  no clock access

The sandbox constraints tell you what a policy is allowed to be. A policy is a pure function of the plan, so it is deterministic and reproducible: the same plan yields the same decision today and next month. A policy that could call out to a service or branch on the time of day would be neither.

USE A BUILTIN WHEN
  the check is a standard posture or cost question.
  Almost always.

WRITE REGO WHEN
  the rule encodes something specific to YOUR
  organisation that no external party could know:
    a naming convention that carries meaning
    a module allow-list
    a relationship between two resources in your
      architecture
    an internal standard with no framework behind it

The test is the same one from watch policies (T2.M2.14): if a shipped rule covers it, use the shipped rule, because it carries maintenance and correctness you would otherwise own.

Native-first loading

OPA LOADS LAZILY, ONLY WHEN A REGO POLICY IS PRESENT.

An org running builtins only never pays for the OPA
runtime at all.

This is a small performance note with a governance consequence worth noticing: adopting the builtin set is genuinely lightweight, so “we will start with builtins and add Rego later if we need it” is a real strategy rather than a deferral of the same cost.

How a decision reaches the pull request

The engine evaluates the plan against every applicable policy and emits a decision. Your required check consumes it (L1). A rule that fires explains itself in the PR, so the person who has to act sees the reason at the point of the change rather than in a dashboard they would have to go and open.

That placement is most of the value. A cost or posture finding delivered three days later, in a different tool, competes with everything else in the queue. The same finding in the pull request competes with nothing.

2. Demo

Adopting the rule set over three weeks:

WEEK 1: BUILTINS, WARN ONLY
  Enabled all 70 builtins, decision surfaced in the PR
  but the required check not yet blocking.

  First week across 14 repositories: 312 findings.

  BY CATEGORY (top 5)
    security         89   mostly public-ish defaults on
                          buckets and security groups
    cost             61   see L3
    governance       47   missing required tags
    reliability      38   single-AZ, no backup retention
    iam              29   over-broad policy documents

  NOBODY ACTED ON 312 FINDINGS. That was expected. The
  warn-only week was to size the problem, not fix it.

WEEK 2: PICK A BLOCKING SUBSET
  They made blocking: security + cost only. 150 of 312.

  The other 162 stayed warn-only, visible in the PR and
  not stopping anyone.

  RATIONALE: a gate that blocks on everything on day one
  gets disabled in a fortnight. A gate that blocks on
  the two categories everyone already agrees about
  survives, and the warn-only categories become
  negotiable later from a position of trust.

WEEK 3: THE FRAMEWORK QUESTION
  Their auditor asked which IaC controls mapped to SOC 2.

  Filtered by the SOC2 tag: 23 of the 70 builtins.
  Exported the list with each rule's description and
  whether it was blocking or warn-only.

  That export became an audit artifact. Previously this
  question had produced a spreadsheet somebody
  hand-maintained and nobody trusted.

WHERE REGO CAME IN, AND WHERE IT DID NOT
  WROTE ONE: a module allow-list. Their platform team
  publishes internal Terraform modules, and a resource
  created outside them bypasses conventions no builtin
  could know about. Genuinely org-specific.

  DID NOT WRITE: a "no public S3 buckets" policy. A
  builtin already covered it. The first draft of their
  adoption plan had three Rego policies, and two were
  deleted after checking the builtin list.

  OPA never loaded during weeks 1 and 2, because no Rego
  policy existed yet.

3. Hands-on (6 min)

1. Enable builtins in warn-only mode on one repository.
   Findings in the first run:                 ______

2. Break them down by category. Top three:
   ____________ ______   ____________ ______
   ____________ ______

3. Pick your blocking subset. Which categories does your
   org already agree about, without a debate?
   ______________________________________________
   Everything else stays warn-only for now.

4. Filter by a compliance framework relevant to you:
   framework: __________  rules tagged: ______
   Could you hand that list to an auditor?     Y / N

5. Before writing any Rego, list the policies you think
   you need, then check each against the builtins:
   idea ______________________  builtin exists? Y / N
   idea ______________________  builtin exists? Y / N
   Most first drafts lose more than half here.

Do it through MCP. The same task you just did in the console, asked in one sentence.

BEFORE  A ZopNight account with one cloud connected. A Terraform plan to test against, and CI you can wire a check into.
ASK     "Check this plan against our policies, then add a rule blocking untagged buckets."
CHECK   CI wiring afterwards. A policy that is not in the pipeline is not enforced, which is L4.

Tools behind it: validate_iac_policy (write, tier 1, metadata only), create_iac_policy (write, tier 2, reversible), list_iac_policies (read, Govern), get_iac_ci_status (read, Govern). The full catalogue is at zop.dev/learn/mcp-tools.

4. Knowledge check

Q1

Custom IaC policies are Rego, sandboxed with no network and no clock access. The consequence:

A. Policies cannot reference any external data, which limits them to simple syntax checks and nothing more substantial than those
B. A policy is a pure function of the plan, so it is deterministic and reproducible: the same plan yields the same decision today and next month
C. Policies have to be re-evaluated on every single apply as well as on every plan, which doubles the total work done
D. Rego policies run measurably more slowly than the builtin rules do, because the runtime loads lazily when it is needed

Q2

An org enables only the builtin rules and writes no Rego. The OPA runtime:

A. Runs alongside every evaluation
B. Loads only for the inventory scan
C. Loads once at startup and stays resident
D. Never loads

Q3

Why are the builtin rules tagged with compliance frameworks such as CIS, SOC 2 and HIPAA?

A. To determine which of the rules are enabled by default on a new repository, since a customer onboarding for SOC 2 wants a different starting set from one onboarding purely for cost purposes
B. So “which of our controls map to SOC 2” becomes a filter and an export. The alternative is somebody reading 70 rule descriptions and making a judgement call, which is never quite the same judgement next year.
C. Because the different frameworks each require different Rego dialects, and the tag tells the evaluator which dialect to parse the policy body with before it runs the rule against a plan
D. To set each rule’s severity level, since a control that maps to a named compliance framework is by definition more serious than one that exists purely for cost hygiene reasons alone

5. Apply

Run a warn-only week before blocking anything, then make blocking only the categories your org already agrees about. A gate that blocks on everything on day one is a gate that gets disabled in a fortnight.

Check every Rego idea against the builtin list before writing it. Most first-draft policy lists lose more than half that way, and each deletion is maintenance you no longer own.

Related lessons

• L1: Decision, not enforcement
• L3: Cost guardrails in the pull request (next)
• T2.M2.14.L1: When to write a watch policy
• T3.M3.3.L4: Audit as compliance evidence

Glossary terms touched

Rego · OPA · Compliance framework tag · Native-first loading