Reference

This page describes everything Ergo accepts and everything it returns, the same for both engines. If you haven’t used Ergo before, start with the README. How to run Ergo is on the page of each engine: Ergo with OPA for ergo.rego, and Ergo CLI for the ergo command.

• Policies
• Subjects
• Requirements
• Checks
• The report
• Causes
• Violations
• Failing closed
• Policies written before 0.1

Policies

A policy is an object with two sections and the version of the spec it’s written for, and it can describe itself too. subjects says what the policy checks and where to find it in the input, and requirements says what must be true of it. Each section maps names to definitions. A policy is plain data, so it usually lives in a YAML or JSON file with top-level ergo_spec, subjects and requirements keys:

ergo_spec: v0.6
subjects:
  deployment: { ... }
  commit: { ... }
requirements:
  approved_deploy: { subject: deployment, ... }
  signed_commits: { subject: commit, ... }

An engine takes the policy, the input and the params, and reads only those, so the same arguments always give the same report. How to hand them over is on the page of each engine.

ergo_spec is the version of the spec the policy is written for, and this copy of Ergo follows v0.6. A policy without it, or with null, a number like 0.1, or another version, is written wrong, so every requirement’s $well_formed row fails and lists it with the policy’s other problems, as an input named policy ergo_spec. Its value says what’s wrong: missing, not a string, not a version V0.1 for a string that isn’t shaped like a version, or unsupported version v0.1, expected v0.6 for one this copy of Ergo doesn’t follow. When the policy is in a file, pass ergo_spec from that file, like data.ergo_spec above, and don’t write it in the Rego that hands the policy over: a fixed value there would say the file follows v0.6 whatever it was written for. A policy written in Rego says it in the policy itself, like {"ergo_spec": "v0.6", "subjects": ...}.

Because each name is an object key, two requirements can’t share a name, and every row in the report points back to exactly one requirement.

A policy with no requirements is never compliant: it doesn’t check anything, so it can’t vouch for anything either. The same goes for a policy that isn’t an object, or whose requirements isn’t one. Its report then has a requirement of Ergo’s own, $policy, with one $well_formed row that fails and says what is wrong, so the violations don’t come back empty. For the policy {"ergo_spec": "v0.6"} and the input {}, the row is:

{
  "cause": "value",
  "check": "$well_formed",
  "inputs": [
    {
      "locations": [],
      "name": "requirements",
      "value": [
        "missing"
      ]
    }
  ],
  "message": "requirements: missing",
  "passed": false,
  "requirement": "$policy",
  "subject": {
    "id": "$policy",
    "type": "$policy"
  }
}

requirements says missing, not an object or empty, and a wrong ergo_spec, description or meta is listed next to it, as policy ergo_spec. A requirement can’t be called $policy, or anything else that starts with $: it is written wrong, with requirement name holding a name can't start with $ in its $well_formed row. Ergo leaves out any other section of the policy, so it changes nothing in the report.

Describing a policy

A policy can have a description and a meta of its own, next to its sections. They work like a requirement’s: description says what the policy asks for, meta keeps anything else, like the id of the control the policy checks, and Ergo copies both to the top of the report and never reads them. This is where a control with several requirements keeps its text:

ergo_spec: v0.6
description: Production changes are reviewed and approved
meta: {control: DEV-0401, title: Security testing and code review}
subjects:
  deployment:
    from: deployments whose environment is "prod"
    identified_by: id
requirements:
  approved:
    subject: deployment
    checks:
      approved: approved_by is a non-empty string
  reviewed:
    subject: deployment
    checks:
      reviewed: reviewer is a non-empty string

With this input:

{"deployments": [{"id": "d-1", "environment": "prod", "approved_by": "alice", "reviewer": "bob"}]}

the report starts with:

{
  "compliant": true,
  "description": "Production changes are reviewed and approved",
  "engine": {
    "name": "ergo-rego",
    "version": "0.6.0"
  },
  "ergo": "v0.6",
  "meta": {
    "control": "DEV-0401",
    "title": "Security testing and code review"
  },
  ...
}

null counts as not written, so the defaults above give "" and {}. A description that isn’t a string, or a meta that isn’t an object or holds something JSON can’t, belongs to every requirement, so every requirement’s $well_formed row fails and lists it last, like {"name": "policy meta", "value": ["not an object"], "locations": []}. The report then shows "" or {} in its place.

Params

Params are the values that change between runs, like the regions a policy allows. They aren’t in the policy or the input, and an engine doesn’t look for them anywhere else, so how they are passed in is on the page of each engine.

A sentence reads them with $params, like region is in $params.regions. Params aren’t part of the input, so $input.params doesn’t reach them, and $params doesn’t read the input. With params of {}, a read of a field in them, like $params.regions, fails as absent, as any missing field does. With no params, null, it fails as absent too, and that includes exists, which otherwise fails a missing field as value, and does not exist, which otherwise passes. So a condition like that on a param fails the requirement instead of deciding the scope. Params that are anything else, like a string or a list, can only be a mistake, so they fail every check and every $min_subjects row as unusable, even in a policy that reads no params. A check whose path into them stops there says what they are, like $params is 3, which isn't an object for $params.a is 1, and so does the $min_subjects message of a subject that isn’t a child subject when its from line reads them with named by or named by each of, like things named by each of $params.ks, which then makes no subjects. A child subject’s from line, like t.m named by $params.env, and a whose in a from line, like things whose id is $params.x, don’t name them. A check that reads them whole, like x is in $params, says what it says with any params. $min_subjects also says why in its inputs: {"name": "$params", "value": ["not an object"], "locations": []}. Ergo has no defaults, so a policy run without its params fails instead of checking something nobody configured.

Subjects

A subject is the kind of thing a requirement checks, like a deployment or a pull request, and says where to find them in the input:

deployment:
  description: A deployment to production
  from: deployments whose environment is "prod"
  identified_by: id

A from or identified_by that isn’t a string, and the fields applies_to and of, are written wrong.

The subject’s name is what the report calls each one, in every row, like "subject": {"type": "deployment", "id": "d-2"}, and in the descriptions of the checks Ergo adds, like The in-scope deployment count is at least 1. So name it the way a reader would, like deployment or pull request.

A requirement names its subject with subject. Several requirements can name the same subject, and each one checks it on its own, with its own rows. A subject that no requirement names isn’t read, so it changes nothing in the report.

A few details:

• If from leads to a list, each item is a subject. If it leads to a single object, that object is the only subject. If it leads nowhere, to null, or to anything else, like a string or a number, there are no subjects and $min_subjects fails with cause absent, null or unusable, even with min_subjects: 0, because that’s what a typo in from looks like. A path through something that can’t hold the next key, like "build": "b1" for build.items, gives unusable, and a missing or null value along the path gives absent, as they do in a check. An empty list is different: it was read fine, so it fails $min_subjects as value, or passes with min_subjects: 0.
• The input has to be an object. A null input fails $min_subjects as null when from is empty or left out, and as absent when it has a step. Any other input that isn’t an object, a list included, fails it as unusable.
• If identified_by doesn’t lead anywhere, the subject’s id is null. Its rows are still there. A subject whose from uses named by each of takes its key as its id, so it can’t have an identified_by.
• No two subjects can share an id, or their rows could be identical and the report couldn’t say which one failed. If two do, $unique_ids fails and so does the requirement. Every subject counts, even one that its conditions leave out, and null is an id like any other, so two subjects without one clash. A requirement on a child subject checks the ids of its parent and grandparent in the same way, on $unique_ancestor_ids rows.
• An item of the list that isn’t an object, like a string or a null, is still a subject. Its id is the item itself, and its checks fail with cause not_an_object.
• Without from, a subject reads the input field named like it, so artifact reads artifact. A subject with nothing under it, artifact: alone in YAML, does the same. To check the whole input as one subject, write from: $input. When the input is a list, from: $input and from: every $input make each item a subject, as from: things does on a list called things, with locations like /0/x. When a walk from the input breaks in one item, like commits being 5 in the second item for from: every $input.commits, failed_items names the place $input[1].commits. When the walk breaks on the input itself, like an object or null for from: every $input, the place is named $input. The expressions of $min_subjects and $unique_ids name a position on the input from $input too, like count(matching(item 1 of $input)) >= 1 for from: $input[0], and write a from that starts with named by as it is, like count(matching(every $input named by $params.k)) >= 1. A position, like from: $input[0] or from: first of $input, reads the item at it, and ends absent when the list has none. from: every $input[0] makes each item of that item a subject. Without identified_by, each row repeats the whole subject as its id, so two identical subjects clash.
• A subject that’s written wrong fails $well_formed on every requirement that names it, so none of them is met. That’s a subject that isn’t an object, or that has a field that isn’t in the table above, like subject_type, applies_to or of, or whose from or identified_by isn’t a string or can’t be read, or whose description isn’t a string. The $well_formed row names each field with its subject, like {"name": "subjects.deployment.from", "value": ["doesn't parse"], "locations": []} or {"name": "subjects.deployment.from", "value": ["not a string"], "locations": []} for a list. Each of those requirements gets only its $well_formed row, as for a requirement that’s written wrong, and a from that isn’t a string or can’t be read is shown as <invalid from> in expressions.

From lines

A from line is a path, and whose or that with conditions joined by and keeps the subjects they hold for. Each condition starts with its own whose or that, so a second one is and whose or and that, and and followed by a bare condition is written wrong. Paths and conditions are written as in checks. identified_by is a path written the same way:

ergo_spec: v0.6
subjects:
  emergency change:
    from: deployments whose environment is "prod" and whose change_type is "emergency"
    identified_by: id
  artifact:
    identified_by: fingerprint
requirements:
  approved:
    subject: emergency change
    checks:
      approved: approved_by is a non-empty string
  signed:
    subject: artifact
    checks:
      signed: signed is true

With this input:

{"deployments": [
  {"id": "d-1", "environment": "prod", "change_type": "emergency", "approved_by": "bob"},
  {"id": "d-2", "environment": "prod", "change_type": "standard"},
  {"id": "d-3", "environment": "prod"}
],
 "artifact": {"fingerprint": "sha256:abc", "signed": true}}

the $applies rows keep d-1 and leave d-2 out:

{"check": "$applies", "subject": {"id": "d-1", "type": "emergency change"}, "passed": true, "cause": "satisfied",
 "inputs": [{"name": "change_type", "value": "emergency", "locations": ["/deployments/0/change_type"]}, {"name": "environment", "value": "prod", "locations": ["/deployments/0/environment"]}], "failed_assertions": []}
{"check": "$applies", "subject": {"id": "d-2", "type": "emergency change"}, "passed": false, "cause": "value", "message": "change_type is \"standard\"",
 "inputs": [{"name": "change_type", "value": "standard", "locations": ["/deployments/1/change_type"]}, {"name": "environment", "value": "prod", "locations": ["/deployments/1/environment"]}],
 "failed_assertions": [{"assertion": "change_type is \"emergency\"", "cause": "value"}]}
{"check": "$applies", "subject": {"id": "d-3", "type": "emergency change"}, "passed": false, "cause": "absent", "message": "change_type is missing",
 "inputs": [{"name": "change_type", "value": null, "locations": ["/deployments/2"]}, {"name": "environment", "value": "prod", "locations": ["/deployments/2/environment"]}],
 "failed_assertions": [{"assertion": "change_type is \"emergency\"", "cause": "absent"}]}

and the $applies entry’s expression is the conditions as written, environment is "prod" and change_type is "emergency". With several conditions, each row has failed_assertions, the conditions that failed in the order written and [] when none did, as a check written as several sentences has. d-3 has no change_type, so Ergo can’t tell whether it’s an emergency change, and approved isn’t met. artifact has no from, so it reads the input field artifact, and signed is met.

• named by $params.name picks one key: from: trail.artifacts named by $params.artifact_name. When the param is missing, null or not a string, there are no subjects and $min_subjects fails as absent, null or unusable, also with every in front of the line. A number is not a key and never reads an item of a list, so x named by $params.k with {"k": 1} fails as unusable.

• named by each of $params.kinds makes each key in the list a subject: from: build.test_runs named by each of $params.kinds. Each key is a subject, even one the object doesn’t have, and the key is its id, so an identified_by on that subject is written wrong, with not allowed with named by each of: the key is the id. When the object itself is missing, null or not an object, a list included, each key is still a subject, but $min_subjects fails as absent, null or unusable, so the requirement is never met. A child subject whose parent isn’t an object makes no subject of its keys, because nothing below that parent is read: its $min_subjects fails as not_an_object. When the list is missing, isn’t a list, or holds anything but strings, there are no subjects and $min_subjects fails as absent, null or unusable. The list is read from $params or $input. A path that starts anywhere else, like t.keys, keys or .keys, is written wrong, with named by each of takes a list from $params or $input, so it can't start at a field or a subject, so a parent can’t list the keys of its children and nothing is read from that path. A ref before named by each of, like $params.env in scans named by $params.env named by each of $params.kinds, is read first: when it’s missing, null or not a string, $min_subjects fails as absent, null or unusable, whatever the list holds. Whether each key is still a subject then is an open question.

  The path to the list is read as one path and never walks a list, so the keys must be a list in one place. With this policy:

  ergo_spec: v0.6
  subjects:
    scan:
      from: $input.scans named by each of $input.required.kind
  requirements:
    scanned:
      subject: scan
      checks:
        passed: status is "pass"
  

  and this input, where required is a list of objects:

  {
    "scans": {"snyk": {"status": "pass"}, "trivy": {"status": "pass"}},
    "required": [{"kind": "snyk"}, {"kind": "trivy"}]
  }
  

  there are no subjects, and $min_subjects fails:

  {
    "cause": "unusable",
    "check": "$min_subjects",
    "inputs": [{"locations": [], "name": "in-scope scan count", "value": 0}],
    "message": "$input.required is [{\"kind\": \"snyk\"}, {\"kind\": \"trivy\"}], which isn't an object",
    "passed": false,
    "requirement": "scanned",
    "subject": {"id": null, "type": "scan"}
  }
  

  With "required": {"kind": ["snyk", "trivy"]}, both scans are subjects and pass. The $refs of $min_subjects and $unique_ids list $input.required.kind with the value null.

• A condition can ask about the items of a list with a one-line some or every, written as in a check. With this policy:

  subjects:
    release:
      from: releases whose some files.path does not match "^docs/"
      identified_by: version
  requirements:
    ticketed:
      subject: release
      min_subjects: 0
      checks:
        approved: ticket.status is "approved"
  

  and this input:

  {"releases": [
    {"version": "1.4.0", "files": [{"path": "docs/upgrade.md"}, {"path": "src/api.go"}], "ticket": {"status": "approved"}},
    {"version": "1.4.1", "files": [{"path": "docs/upgrade.md"}], "ticket": {"status": "open"}},
    {"version": "1.4.2", "files": [], "ticket": {"status": "open"}}
  ]}
  

  the $applies rows keep 1.4.0, which changes a file outside docs/, and leave the other two out. They read, and list as failed_items, what the same sentence does as a check:

  {"check": "$applies", "subject": {"id": "1.4.0", "type": "release"}, "passed": true, "cause": "satisfied",
   "inputs": [{"name": "files[].path", "value": ["docs/upgrade.md", "src/api.go"], "locations": ["/releases/0/files/0/path", "/releases/0/files/1/path"]}], "failed_items": []}
  {"check": "$applies", "subject": {"id": "1.4.1", "type": "release"}, "passed": false, "cause": "value", "message": "item 1 of files: path is \"docs/upgrade.md\"",
   "inputs": [{"name": "files[].path", "value": ["docs/upgrade.md"], "locations": ["/releases/1/files/0/path"]}],
   "failed_items": [{"path": "files[0].path", "item": "item 1 of files", "cause": "value", "value": "docs/upgrade.md", "locations": ["/releases/1/files/0/path"]}]}
  {"check": "$applies", "subject": {"id": "1.4.2", "type": "release"}, "passed": false, "cause": "value", "message": "files is []",
   "inputs": [{"name": "files[].path", "value": [], "locations": []}],
   "failed_items": [{"path": "files", "item": "files", "cause": "value", "value": [], "locations": ["/releases/2/files"]}]}
  

  A release with no files field at all isn’t out of scope: Ergo can’t tell, so the row fails as absent (null and unusable for a null or a wrong type), with the input {"name": "files.path", "value": [], "locations": []}, and the requirement isn’t met. every files.path matches "^docs/" keeps the releases that only change documentation, and every files.path, if any, matches "^docs/" keeps the ones with no files too. some takes no , if any,. A bare name after some or every is the item’s, and a parent subject’s name on the right is the parent. The condition can’t have a whose of its own, and a whose in a check or on a for line takes no some or every condition.

• A subject’s own name at the start of its from is the input field, so lockfile can have from: lockfile whose status is "COMPLETE".

• A from line that’s another subject’s name, with or without a whose, narrows that subject (a position after the name, like p[1] or first of p, doesn’t narrow it: the subject reads that position inside each p, and fails $min_subjects as unusable when a p is an object), as in a subject built on another: critical defect with from: defect whose severity is "critical" keeps the defects that pass defect’s conditions and its own. A name with a space goes in quotes, so the whole line goes in single quotes in YAML: from: '"critical defect" whose team is "b"'. It takes its id from the subject it narrows, so an identified_by of its own is written wrong, with not allowed on a subject that narrows another. When that subject is read with every, the narrowing subject takes its flat list of subjects and filters it, and its $min_subjects expression starts with every too.

• A from line with one name, like deployments or .deployments, gives each item of a list as a subject. A line with more than one name needs every to read a list, wherever the list is: $input, another subject’s name, each field and each key a named by reads count as names, and a position like [0] or first of doesn’t. So $input.deployments, build.tests, build named by $params.k and builds[0].tests need every when the value they reach is a list, and builds[0].tests[0] doesn’t. Without it, $min_subjects fails as unusable and says what to write, like trails is a list: write every trails.r.prs to read each item. The data decides whether a value is a list, so the line isn’t written wrong.

• A from line that ends at text, a number or true or false gives that value as one subject, and a check reads it by the subject’s name: with {"version": "1.2.0"}, version with from: version is a subject, and version is "1.2.0" passes. An input that is itself text still fails $min_subjects as unusable.

• All the subjects a from line gives must be of one type: objects, lists, text, numbers, or true or false. from: tags on {"tags": ["a", {"x": 1}]} fails $min_subjects as unusable, even with min_subjects: 0, with item 1 of tags is text, item 2 of tags is an object, and both are still subjects and are checked. The row’s failed_items lists the values the message names, item 1 of tags and item 2 of tags. An item that is null is a subject too and doesn’t count as a type. Only that line’s $min_subjects fails: a child subject read from it is still read under each parent, so with d from ds and m from d.m, {"ds": [{"m": {"up": false}}, "x"]} gives m under the first d, and d is "x", which isn't an object under the second.

• A from line that starts at another subject’s name and goes on reads the rest of its path from that subject. With {"params": {"artifact_name": "web"}} and this input:

  {"trail": {"artifacts": {"web": {"fingerprint": "sha-1", "pull_requests": [
    {"url": "pr/7", "approved_by": "bob"},
    {"url": "pr/8", "approved_by": ""}
  ]}}}}
  

  these subjects read the pull requests of the web artifact:

  subjects:
    artifact:
      from: trail.artifacts named by $params.artifact_name
      identified_by: fingerprint
    pull request:
      from: every artifact.pull_requests
      identified_by: url
  

  The pull requests are a child subject of artifact: they only exist under an artifact that’s in scope, and each one belongs to one artifact. Every row of a requirement on pull request says which, under in, apart from $well_formed, which is about the requirement as written:

  {"check": "approved", "subject": {"type": "pull request", "id": "pr/8", "in": {"artifact": "sha-1"}}, "passed": false, "cause": "value", "message": "approved_by is \"\"",
   "inputs": [{"name": "approved_by", "value": "", "locations": ["/trail/artifacts/web/pull_requests/1/approved_by"]}]}
  

  A check reads the artifact by its name, like artifact.name. Only checks written as sentences can read it.

  So can a whose in the child’s from line. With {"params": {"artifact_name": "web"}} and this input:

  {"trail": {"artifacts": {"web": {"fingerprint": "sha-1", "branch": "main", "pull_requests": [
    {"url": "pr/7", "base": "main"},
    {"url": "pr/8", "base": "dev"}
  ]}}}}
  

  from: every artifact.pull_requests whose base is artifact.branch keeps pr/7 and leaves pr/8 out of scope:

  {"check": "$applies", "subject": {"type": "pull request", "id": "pr/8", "in": {"artifact": "sha-1"}}, "passed": false, "cause": "value", "message": "base is \"dev\", and artifact.branch is \"main\"",
   "inputs": [{"name": "artifact.branch", "value": "main", "locations": ["/trail/artifacts/web/branch"]}, {"name": "base", "value": "dev", "locations": ["/trail/artifacts/web/pull_requests/1/base"]}]}
  

  On the left of a whose, artifact.branch is the pull request’s own field, as in any whose.

  When the artifact is several subjects, the pull requests of each are read and checked in turn. With this input:

  {"trail": {"artifacts": [
    {"fingerprint": "sha-1", "environment": "prod", "pull_requests": [{"url": "pr/7", "approvals": 2}, {"url": "pr/8", "approvals": 0}]},
    {"fingerprint": "sha-2", "environment": "prod", "pull_requests": []},
    {"fingerprint": "sha-3", "environment": "staging", "pull_requests": [{"url": "pr/9", "approvals": 0}]},
    {"fingerprint": "sha-4", "pull_requests": [{"url": "pr/10", "approvals": 1}]}
  ]}}
  

  and these subjects and requirement:

  subjects:
    artifact:
      from: every trail.artifacts whose environment is "prod"
      identified_by: fingerprint
    pull request:
      from: every artifact.pull_requests
      identified_by: url
  requirements:
    reviewed:
      subject: pull request
      checks:
        approved: approvals is at least 1
  

  the report has these rows:

  {"check": "$well_formed",  "subject": {"type": "pull request", "id": null}, "passed": true, "cause": "satisfied"}
  {"check": "$min_subjects", "subject": {"type": "pull request", "id": null, "in": {"artifact": "sha-1"}}, "passed": true, "cause": "satisfied"}
  {"check": "$min_subjects", "subject": {"type": "pull request", "id": null, "in": {"artifact": "sha-2"}}, "passed": false, "cause": "value", "message": "in-scope pull request count is 0"}
  {"check": "$min_subjects", "subject": {"type": "pull request", "id": null, "in": {"artifact": "sha-4"}}, "passed": false, "cause": "absent", "message": "in-scope pull request count is 0"}
  {"check": "$unique_ids",   "subject": {"type": "pull request", "id": null, "in": {"artifact": "sha-1"}}, "passed": true, "cause": "satisfied"}
  {"check": "$unique_ids",   "subject": {"type": "pull request", "id": null, "in": {"artifact": "sha-2"}}, "passed": true, "cause": "satisfied"}
  {"check": "$unique_ancestor_ids", "subject": {"type": "artifact", "id": null}, "passed": true, "cause": "satisfied"}
  {"check": "approved",      "subject": {"type": "pull request", "id": "pr/7", "in": {"artifact": "sha-1"}}, "passed": true, "cause": "satisfied"}
  {"check": "approved",      "subject": {"type": "pull request", "id": "pr/8", "in": {"artifact": "sha-1"}}, "passed": false, "cause": "value", "message": "approvals is 0"}
  

  • Each artifact gets its own $min_subjects and $unique_ids rows. sha-2 has no pull requests, so it fails on its own row, unless the requirement has min_subjects: 0. Ids only need to be unique within each artifact, so pr/7 under two artifacts is fine.

  • The artifacts’ own ids are checked once, on the $unique_ancestor_ids row, with no in, counting sha-3 too, as $unique_ids counts the subjects its conditions leave out. Two artifacts with the same fingerprint fail it, and so does the requirement, even with require: some, where the pull requests of both artifacts would otherwise count as one artifact’s. With commit read from commits by sha, pull request from every commit.pull_requests, and two commits that both have the sha a, the row is:

    {"check": "$unique_ancestor_ids", "subject": {"type": "commit", "id": null}, "passed": false, "cause": "value", "message": "repeated commit ids is [\"a\"]",
     "inputs": [{"name": "repeated commit ids", "value": ["a"], "locations": ["/commits/0/sha", "/commits/1/sha"]}]}
    

  • sha-3 is out of scope, so its pull requests aren’t subjects at all and it has no rows. Nothing in them is read, so pr/9 isn’t checked.

  • sha-4 has no environment, so Ergo can’t tell whether it’s in scope. Its $min_subjects row fails with the cause, even with min_subjects: 0, and its pull requests aren’t checked.

  • When no artifact is in scope, there’s one $min_subjects row with no in. It fails with value, or passes with min_subjects: 0, as for any subject that finds none.

  A child subject can have child subjects of its own, so a chain can be three subjects deep, like artifact, pull request and commit:

  commit:
    from: 'every "pull request".commits'
    identified_by: sha
  

  Each commit row says which artifact and which pull request it belongs to, like "in": {"artifact": "sha-1", "pull request": "pr/7"}, and each pull request gets its own $min_subjects and $unique_ids rows. The requirement gets one $unique_ancestor_ids row for the artifacts, with no in, then one for the pull requests of each artifact in scope, with the artifact under in, and the checks entry joins both: Every artifact id is unique and every pull request id is unique. An artifact or a pull request that’s out of scope leaves out everything below it. An artifact whose conditions can’t be decided gets one failing $min_subjects row, with "in": {"artifact": ...}. A check reads any ancestor by its name, like artifact.name or "pull request".title, and its parts too. A fourth level is written wrong, with a chain of more than three subjects isn't supported yet, and so is a subject whose from line narrows a child subject. A chain that comes back to a subject already in it, like b with from: kid.x and kid with from: b.kids, is written wrong with leads to a loop, however many subjects it goes through.

  A parent that isn’t an object, a string or a null for instance, can’t hold the child’s field, so its $min_subjects row fails as not_an_object, with in up to the parent, even with min_subjects: 0. A parent that’s an object without the field still gives absent, and a from that starts with a position, like artifact[0].commits, keeps the cause it had. A parent that is a list is read with every: with batch read from batches, every batch.owner gives the owners in each batch, with the batch under in, and batch.owner fails as not_an_object with batch is a list: write every batch.owner to read each item. every never stands for the parent itself: every batch and every batch whose size is 2 are written wrong, with batch is a subject: write batch whose … to narrow it, without every.

  Use a child subject when something only makes sense inside another thing, like the test runs of a build. Its id only has to be unique inside its parent, so unit can appear in every build, and every row names the parent under in, so a reader knows which build a failing test run belongs to. With {"params": {"kinds": ["unit", "integration"]}} and this input:

  {"builds": [
    {"id": "b1", "test_runs": {"unit": {"passed": true}, "integration": {"passed": true}}},
    {"id": "b2", "test_runs": {"unit": {"passed": true}, "integration": {"passed": false}}}
  ]}
  

  and this policy:

  subjects:
    build:
      from: builds
      identified_by: id
    test run:
      from: build.test_runs named by each of $params.kinds
  requirements:
    tests pass:
      subject: test run
      checks:
        passed: passed is true
  

  there are four test runs, unit and integration under each build, and only integration in b2 fails:

  {"check": "passed", "subject": {"type": "test run", "id": "integration", "in": {"build": "b2"}}, "passed": false, "cause": "value", "message": "passed is false"}
  

  every can’t go with named by each of, so every builds.test_runs named by each of $params.kinds is written wrong: the keys would be the ids, and with two builds the rows wouldn’t say which build they belong to. When a from line meets a list before named by each of, like build.test_runs with test_runs a list, $min_subjects fails as unusable with build.test_runs is a list, but named by each of reads the keys of one object: make each item a subject and read the keys in it, and each key is still a subject that fails its checks. The same goes for $input named by each of $params.kinds when the input is a list, which says $input is a list, but …. A parent subject that is a list, under artifact named by each of $params.kinds, fails as not_an_object with artifact is a list, but ….

• A from line that starts at another subject’s name and ends with named by each of, like artifact named by each of $params.keys, is a child subject too: each key in the list is a subject read inside each parent, so the keys are looked up in the parent and not in an input field named like it, and every row carries the parent under in. artifact.x named by each of $params.keys reads the keys inside x of each parent. A parent that isn’t an object fails $min_subjects as not_an_object and makes no subject of its keys. A missing, null or wrong-typed list fails $min_subjects of each parent as absent, null or unusable. A first key written with a dot, like .artifact named by each of $params.keys or .artifact.pull_requests, is always the input field, never the parent, so that line isn’t a child subject. A position after the parent’s name, like artifact[0] named by each of $params.keys or first of artifact named by each of $params.keys, reads the parent as a list: $min_subjects fails as unusable for each parent that’s an object, and the keys are still subjects that fail their checks.

• every in front of the path reads one list at each name along it, the last one included, and at the value it starts at, and each value it ends at is a subject. With this input:

  {"artifacts": [
    {"fingerprint": "sha-1", "pull_requests": [{"url": "pr/7", "approvals": 2}, {"url": "pr/8", "approvals": 0}]},
    {"fingerprint": "sha-2", "pull_requests": []},
    {"fingerprint": "sha-3"}
  ]}
  

  and this policy:

  subjects:
    pull request:
      from: every artifacts.pull_requests
      identified_by: url
  requirements:
    reviewed:
      subject: pull request
      checks:
        approved: approvals is at least 1
  

  the pull requests are one list, pr/7 and pr/8, and the report has these rows after $well_formed:

  {"check": "$min_subjects", "subject": {"type": "pull request", "id": null}, "passed": false, "cause": "absent", "message": "item 3 of artifacts: pull_requests is missing",
   "inputs": [{"name": "in-scope pull request count", "value": 2, "locations": ["/artifacts/0/pull_requests/0", "/artifacts/0/pull_requests/1"]}],
   "failed_items": [{"path": "artifacts[2].pull_requests", "item": "artifacts[2].pull_requests", "cause": "absent", "value": null, "locations": ["/artifacts/2"]}]}
  {"check": "$unique_ids",   "subject": {"type": "pull request", "id": null}, "passed": true,  "cause": "satisfied"}
  {"check": "approved",      "subject": {"type": "pull request", "id": "pr/7"}, "passed": true,  "cause": "satisfied"}
  {"check": "approved",      "subject": {"type": "pull request", "id": "pr/8"}, "passed": false, "cause": "value", "message": "approvals is 0"}
  

  • Unlike a child subject, these pull requests don’t belong to an artifact. Their rows have no in, they’re counted once, and their ids must be unique across all of them. A check can’t read the artifact.
  • An empty list, like sha-2’s, adds nothing and fails nothing.
  • A list that’s missing, like sha-3’s, or null fails $min_subjects with the worst cause found, even with min_subjects: 0. The row’s failed_items says where, and the pull requests that could be read are still checked. So does a path with no list along it: every deps on {"deps": {"id": 1}} fails with deps is {"id": 1}, which isn't a list.
  • A value at the end can be an object, text, a number or true or false: every builds.version on {"builds": [{"version": "1.0"}, {"version": "1.1"}]} gives "1.0" and "1.1".
  • A name every reads as a list in one item must be a list in all of them. every builds.tags on {"builds": [{"tags": ["a", "b"]}, {"tags": "c"}]} gives a, b and c, and $min_subjects fails as unusable with tags is a list in item 1 of builds but "c" in item 2, and lists builds[0].tags and builds[1].tags in failed_items. A policy that expects both shapes can say so with a subject for each, like listed build with from: build whose tags is a list and tag with from: every "listed build".tags.
  • A list directly inside a list is an item like any other, and every doesn’t read into it. With {"batches": [[{"owner": {"name": "ann"}}], [{"owner": {"name": "cy"}}]]}, every batches gives two subjects, each a list, and every batches.owner fails as not_an_object, because a list has no owner. A subject for each level, batch and every batch.owner, reads the owners. Text, a number or true or false where a name is read fails as unusable instead, with the message a check gives: every builds.version.x on {"builds": [{"version": "1.0"}]} says item 1 of builds: version is "1.0", which isn't an object.
  • every can start at another subject’s name, like every artifact.pull_requests, which reads the pull requests of each artifact, with the artifact under in, as a child subject does. every can’t go with named by each of, which is written wrong. A path that starts with a dot, like every .artifact.p, reads the input field.

• every distinct makes one subject of items that are exactly the same, which SBOM tools often write twice. With this input:

  {"sbom": {"components": [
    {"name": "click", "version": "8.1"},
    {"name": "jinja2", "version": "3.1"},
    {"name": "click", "version": "8.1"}
  ]}}
  

  and this policy:

  subjects:
    component:
      from: every distinct sbom.components
      identified_by: name
  requirements:
    versioned:
      subject: component
      checks:
        version: version exists
  

  there are two subjects, and each row of click lists both copies, so the report still shows it was there twice:

  {"check": "$min_subjects", "subject": {"type": "component", "id": null}, "passed": true, "cause": "satisfied",
   "inputs": [{"name": "in-scope component count", "value": 2, "locations": ["/sbom/components/0", "/sbom/components/2", "/sbom/components/1"]}]}
  {"check": "$unique_ids", "subject": {"type": "component", "id": null}, "passed": true, "cause": "satisfied"}
  {"check": "version", "subject": {"type": "component", "id": "click"}, "passed": true, "cause": "satisfied",
   "inputs": [{"name": "version", "value": "8.1", "locations": ["/sbom/components/0/version", "/sbom/components/2/version"]}]}
  {"check": "version", "subject": {"type": "component", "id": "jinja2"}, "passed": true, "cause": "satisfied",
   "inputs": [{"name": "version", "value": "3.1", "locations": ["/sbom/components/1/version"]}]}
  

  • Two values are the same when they’re equal as JSON: 1 and 1.0 are the same, and so are two objects with the same keys in another order. Two lists with the same items in another order aren’t.
  • Items that share an id but differ in anything else, like a third click with version 8.2, are all kept, and $unique_ids fails on them and lists the location of every copy’s id. Ergo never picks one of two pieces of evidence that disagree, so there’s no distinct by a field.
  • Copies are merged before the whose is read, so they get one $applies row, and the rows of a child subject, like from: every component.licenses, list the location under every copy too. A path that starts at $input, like version is $input.sbom.components[2].version, lists only the location it names.
  • distinct goes after every on a from line. Without every, like from: distinct sbom.components, it is written wrong.

• A from or identified_by that can’t be read is written wrong, and the $well_formed row says why, like {"name": "subjects.x.from", "value": ["doesn't parse"], "locations": []}.

• A from that can’t be read fails $min_subjects, and its message says where the read stopped: item 2 of things is missing, or things is 5, which isn't a list or an object. A child subject names the path inside its parent, without the parent’s name, like ws is missing or item 1 of ws is missing. When the read stops before its first step, the message names $input, like $input is null, or the parent, like artifact is null, artifact is "x", which isn't an object or item 1 of artifact is missing for a child of artifact.

A subject built on another

When requirements check different parts of the same list, give each part its own subject, built on one that says where the list is. Say the SBOM lists components, some pinned by the lockfile and some exempt from the licence rules:

ergo_spec: v0.6
subjects:
  component:
    from: components
    identified_by: name
  locked component:
    from: component whose lock_release exists
  non-exempt component:
    from: component whose exempt is false
requirements:
  versions:
    subject: locked component
    checks:
      matches_lock: sbom_release equals lock_release
  licences:
    subject: non-exempt component
    checks:
      licence_known: some licences is a non-empty string

With this input:

{"components": [
  {"name": "a", "sbom_release": "1.2", "lock_release": "1.2", "exempt": false, "licences": ["MIT"]},
  {"name": "b", "sbom_release": "2.0", "lock_release": "2.1", "exempt": true, "licences": []},
  {"name": "c", "sbom_release": "3.0", "exempt": false, "licences": [""]}
]}

licences checks a and c, and versions checks a and b. Both fail:

A from line that’s another subject’s name reads that subject’s from and identified_by, and keeps only the items that pass that subject’s conditions and its own. Everything else about it is its own: its rows and descriptions use its name, like locked component.

• A subject can build on one that builds on another, and so on. A name with a space goes in quotes, so the whole line goes in single quotes in YAML: from: '"locked component" whose exempt is false'.
• A chain that comes back to a subject already in it never reaches a list. It fails as leads to a loop.
• A from line can’t start at a subject whose name is blank, like " ", since no requirement can name it. It fails as " " isn't a subject name.
• A problem fails $well_formed on every requirement that names a subject whose chain has it, and that row is the requirement’s only row.
• A requirement can name the subject others build on too, like component to check every component.

Parts

Data often keeps what a check needs deep inside the subject. Kosli, for one, puts every attestation at compliance_status.attestations_statuses.<name>.attestation_data, so a policy that reads three attestations repeats that path in every check. A subject can give a path a name once, with has, and the checks use the name. Each entry of has is a part, and its key is the part’s alias. An alias is a short word that stands for something longer, as as pr does on a for line.

ergo_spec: v0.6
subjects:
  round:
    from: trail
    identified_by: name
    has:
      findings: compliance_status.attestations_statuses.findings.attestation_data
      coverage:
        from: compliance_status.attestations_statuses.coverage-verification
        identified_by: attestation_id
requirements:
  review_round:
    subject: round
    checks:
      complete: findings.truncated is false
      every_hunk_acknowledged: coverage.attestation_data.hunks_acknowledged equals coverage.attestation_data.hunks_total

With this input:

{
  "trail": {
    "name": "round-1",
    "compliance_status": {
      "attestations_statuses": {
        "findings": { "attestation_data": { "truncated": false } },
        "coverage-verification": {
          "attestation_id": "cov-9",
          "attestation_data": { "hunks_acknowledged": 25, "hunks_total": 28 }
        }
      }
    }
  }
}

complete passes and every_hunk_acknowledged fails with cause value:

{"check": "complete", "subject": {"type": "round", "id": "round-1"}, "passed": true, "cause": "satisfied",
 "inputs": [{"name": "findings.truncated", "value": false, "locations": ["/trail/compliance_status/attestations_statuses/findings/attestation_data/truncated"], "part": {"name": "findings", "id": null}}]}
{"check": "every_hunk_acknowledged", "subject": {"type": "round", "id": "round-1"}, "passed": false, "cause": "value", "message": "coverage.attestation_data.hunks_acknowledged is 25, and coverage.attestation_data.hunks_total is 28",
 "inputs": [{"name": "coverage.attestation_data.hunks_acknowledged", "value": 25, "locations": ["/trail/compliance_status/attestations_statuses/coverage-verification/attestation_data/hunks_acknowledged"], "part": {"name": "coverage", "id": "cov-9"}},
            {"name": "coverage.attestation_data.hunks_total", "value": 28, "locations": ["/trail/compliance_status/attestations_statuses/coverage-verification/attestation_data/hunks_total"], "part": {"name": "coverage", "id": "cov-9"}}]}

Each input read through a part says which part, and which one of them: part has the alias as the check writes it, and the id, the value at the part’s identified_by inside the part. That is how a reader tells one attestation from another when a subject has several of the same kind. A one-line part has no id, so its id is null, and so is the id of a part that is missing or has nothing at identified_by. An input that doesn’t go through a part has no part.

A part is a short name for its path and nothing more. coverage.attestation_data.hunks_total gives exactly the rows that compliance_status.attestations_statuses.coverage-verification.attestation_data.hunks_total gives: the same passed, the same cause and the same values. A part that is missing fails the check as absent, a null one as null, and one of the wrong type as unusable, because the full path would. When a step follows a null part, the message names the part, like findings is null for findings.truncated is false. A key read from a field after the null is named too, like pl is null; p is 3, which isn't text for pl.z named by p exists with p 3. Only the names differ. With coverage-verification missing from the input, the row is

{"check": "every_hunk_acknowledged", "subject": {"type": "round", "id": "round-1"}, "passed": false, "cause": "absent", "message": "coverage.attestation_data.hunks_acknowledged is missing, and coverage.attestation_data.hunks_total is missing",
 "inputs": [{"name": "coverage.attestation_data.hunks_acknowledged", "value": null, "locations": ["/trail/compliance_status/attestations_statuses"], "part": {"name": "coverage", "id": null}},
            {"name": "coverage.attestation_data.hunks_total", "value": null, "locations": ["/trail/compliance_status/attestations_statuses"], "part": {"name": "coverage", "id": null}}]}

and written out in full, its inputs are named compliance_status.attestations_statuses.coverage-verification.attestation_data.hunks_acknowledged and ...hunks_total, with the same null. The expression of a check and the names in its inputs and failed_items keep the alias, so a reader sees the words the policy was written in.

• A part is one line, a path, or an object with from, a path, and identified_by, a path read inside the part. The report shows it under parts, and tags each input read through the part with the id it leads to. A count of or sum of has the tag only when the list it counts or sums starts at the part: count of items whose w is pa.w counts the subject’s items, so its number has no tag, while the entry for pa.w, which it reads, has.

• A path is written as in a from line: keys joined by ., keys in quotes, positions, and named by a key of $params or $input. It is a path inside the subject, so it can’t start at $params or $input, and it can’t have whose, count of or named by each of.

• A part can be any path, even one that ends at a single value: ratio: compliance_status.attestations_statuses.coverage.attestation_data.ratio makes ratio is at least 0.8 read the same.

• Keep the data’s own names, as findings and coverage do, because a reader who knows the data finds coverage.attestation_data.hunks_total where they’d look for it.

• An alias is read wherever a bare first key reads the subject: in the subject’s checks, in the assertions of a for line, and in the conditions of the subject’s from line and of a subject that narrows it, where .limit reads the field instead. In a whose, where a bare first key is a field of the item, it’s read on the right side and never right after whose, as a for line’s name is: whose limit is at least 4 reads the item’s limit, and .limit on the right of a whose reads the item’s. After a one-line every or some, the right side is read from the subject, so every items.price is at most limit reads the part limit, and .limit there reads the subject’s own field. A term of a plus and the path of an elapsed time on the right read it the same way, so whose lo is at least limit plus hi reads the part limit and the item’s hi. A count of or sum of is read the same way: in count of items whose n is count of limit.rows is 1 the right side counts the part’s limit.rows, and in count of items whose count of limit.rows is 1 is 3 the left side counts each item’s own limit.rows. After that, count of xs that is count of limit.rows is 1 counts the part’s limit.rows too, even when the items are numbers. named by a part’s alias is written wrong, with named by coverage reads a part, which isn't supported yet.

• An alias shadows a field of the subject with the same name. To read the field, put a dot in front: .coverage is the subject’s field coverage, not the part. A row’s inputs name a field read like that with the dot, like .coverage.pct, when the field is named like a part, a parent subject or a for alias, so it isn’t taken for the part’s coverage.pct. The list a count of or a walk reads keeps the dot too, like .coverage.items[].

• An alias is a bare word that isn’t a word of the grammar, params or input, or it is written wrong with invalid alias. A part’s alias named like a subject of the policy (its own, its parent or any other) is written wrong with <alias> can't be an alias: it's a subject's name, and one named like a part of a parent or grandparent subject, or like a part kept from a subject it narrows, with <alias> can't be an alias: it's a part of <subject>, which names the subject that declares the part and puts a name with a space in it in double quotes, like "pull request". A name always means one thing, so nobody has to wonder whether it reads the subject or the alias. The problem is listed under the part, like subjects.kid.has.x.

• An alias of a for line can’t be named like a subject, the check’s own, a parent or any other in the policy, or like a part of the check’s own subject, of a parent or grandparent subject, or of a subject they narrow. Either is written wrong, so that a name always means one thing and a bare name never reads the parent when the item lacks the field. The problem is under the check, as <alias> can't be an alias: it's a subject's name or <alias> can't be an alias: it's a part of <subject>, and both are listed when both apply. With this policy and this input:

  subjects:
    b:
      from: bs
      identified_by: id
      has:
        cap: limit
    kid:
      from: every b.kids
      identified_by: id
  requirements:
    r:
      subject: kid
      checks:
        c:
          for: every xs as b
          assert: b.v is 1
  

  {"bs": [{"id": "b1", "limit": 2, "kids": [{"id": "k1", "xs": [{"v": 1}]}]}]}
  

  the $well_formed row fails with {"name": "checks.c", "value": ["b can't be an alias: it's a subject's name"], "locations": []}, and with as cap it fails with ["cap can't be an alias: it's a part of b"]. A name that clashes with nothing, like as entry, reads the item.

• A subject that narrows another keeps its parts and can add its own. The report lists them all.

• A child subject reads its parent’s parts through the parent’s name, and its from line can start from one. With {"params": {"artifact_name": "web"}} and this input:

  {"trail": {"artifacts": {"web": {"fingerprint": "sha-1", "attestations_statuses": {
    "pull-request": {"attestation_data": {"approvers": ["bob"], "pull_requests": [{"url": "pr/7"}, {"url": "pr/8"}]}}}}}}}
  

  this policy reads the pull requests of the attestation, and checks each of them against its approvers:

  subjects:
    artifact:
      from: trail.artifacts named by $params.artifact_name
      identified_by: fingerprint
      has:
        pr_attestation: attestations_statuses.pull-request.attestation_data
    pull request:
      from: every artifact.pr_attestation.pull_requests
      identified_by: url
  requirements:
    approved:
      subject: pull request
      checks:
        approved: artifact.pr_attestation.approvers is not empty
  

  {"check": "approved", "subject": {"type": "pull request", "id": "pr/7", "in": {"artifact": "sha-1"}}, "passed": true, "cause": "satisfied",
   "inputs": [{"name": "artifact.pr_attestation.approvers", "value": ["bob"], "locations": ["/trail/artifacts/web/attestations_statuses/pull-request/attestation_data/approvers"], "part": {"name": "artifact.pr_attestation", "id": null}}]}
  

  A part is only reached through its subject, so a bare pr_attestation in a check of pull request is one of its own fields.

• A part that is written wrong fails $well_formed on every requirement that names the subject, with the problem under the part’s alias, like {"name": "subjects.round.has.coverage", "value": ["missing from"], "locations": []}. That is a has that isn’t an object (not an object), a part that isn’t a string or an object (not a string or an object), an object without from (missing from), with a field other than from and identified_by (unknown field <name>), or with a from or identified_by that isn’t a string (invalid from, invalid identified_by), and a path that can’t be read (from: a part is a path: whose and named by each of can't go in it, from: a part reads inside its subject, so it can't start at $params or $input, or the problems a from line gives).

• The report lists every part under the subject’s parts, including the ones it keeps from a subject it narrows.

Requirements

prod_deploy:
  description: Every production deployment is approved
  meta: {control: SDLC-CTRL-0007, frameworks: [SOC 2]}
  subject: deployment
  require: every
  min_subjects: 1
  checks:
    approved: approved_by is a non-empty string

A few details:

• meta can hold anything JSON can, like {"control": "SDLC-CTRL-0007", "frameworks": ["SOC 2", "ISO 27001"], "version": 3, "reviewed": true}. Its numbers follow the same rule as numbers anywhere else in a policy: one a 64-bit float can’t hold, like 1e400, makes the requirement written wrong. So does a key that isn’t a string, or a set, which a policy written in Rego can hold but JSON can’t. In the report, a number is written in its plain form, so 1.50, 1e2 and -0 come out as 1.5, 100 and 0, and the same meta gives the same report however it was written.
• min_subjects defaults to 1 so that a typo in from fails the requirement instead of quietly passing it. Set it to 0 when you mean “if there are any, they must pass; if there are none, that’s fine”. It means the same under every and some. When none are left, the requirement is not applicable. That only holds for a list that’s there: a from that leads nowhere still fails, as above. A from that ends with named by each of is the exception, because each key is a subject even when from leads nowhere.
• Under some, one subject has to pass all the checks by itself. Two subjects that each pass half of them don’t count. For a child subject, that holds under each parent: every parent with subjects in scope needs one that passes, and the failing subjects under a parent that has a passing one aren’t violations.
• A requirement with no checks, a require other than every or some, a check that’s written wrong, or a subject that’s written wrong, is never met. The $well_formed row says so, and says what’s wrong, like {"name": "require", "value": ["neither every nor some"], "locations": []}. That row is the requirement’s only row: Ergo doesn’t read its subjects, so it has no $min_subjects, $unique_ids, $unique_ancestor_ids, $applies or check rows, and its subjects counts are 0. Its entry in requirements still lists every check, the ones Ergo adds included, so the report shows what the policy wrote. Other requirements in the policy still get theirs.
• So is a name that starts with $, whether it names a subject, a requirement, a check, an any_of option or a part, because the report would mix it up with Ergo’s own rows, like $well_formed. A $ later in a name, like a$b, is fine, and so is $input or $params at the start of a path, which aren’t names. The $well_formed row says {"name": "checks.$foo", "value": ["a name can't start with $"], "locations": []} for a check, subjects.$foo for a subject, subjects.deployment.has.$foo for a part and requirement name for a requirement, and for an option it says option $foo: a name can't start with $ under the check. A check with such a name has no entry in requirements. A for alias can’t start with $ either: the line doesn’t parse. A name can’t start or end with a space or an invisible character either, like " $well_formed", "approved " or a zero width space (U+200B) before a name: the problem is a name can't start or end with a space or an invisible character, listed in the same places, and a name with both problems lists both. A space inside a name, like x y, is fine. The characters are the ones Unicode calls White_Space or Cf, as names.edge says. An empty name, "", is written wrong too, with a name can't be empty in the same places, as names.empty says. A requirement whose subject is "" gets empty or not a string under subject.
• So is a requirement without a subject, or whose subject isn’t in subjects, like a typo for deploymnt. The $well_formed row says {"name": "subject", "value": ["missing"], "locations": []} or {"name": "subject", "value": ["not in subjects"], "locations": []}. If subjects itself isn’t an object, every requirement that names a subject fails with {"name": "subjects", "value": ["not an object"], "locations": []}.
• So is a requirement with a field that isn’t in the table above, like from or requires, because Ergo would otherwise ignore it and check something you didn’t mean. from and identified_by belong to the subject. The $well_formed row lists each one in order and says what’s wrong with it, the way it does for a check that’s written wrong, like {"name": "from", "value": ["unknown field"], "locations": []}.
• So is a requirement that isn’t an object, or whose checks isn’t an object, whose min_subjects isn’t a whole number from 0 to 1,000,000, whose subject isn’t a string with something besides whitespace in it, since rows and descriptions name the subject by it, whose description isn’t a string, or whose meta isn’t an object. null counts as the wrong type, except for description and meta: Ergo only copies those, so a null one counts as not written, which is what YAML gives for an empty description:. 2.0 is a whole number, but -1 and 0.5 aren’t, and 1000001 is too big. It still has its entry in requirements and its $well_formed row, which shows each such field and what it should be, like {"name": "checks", "value": ["not an object"], "locations": []}, or the whole requirement and its value, like {"name": "requirement", "value": 5, "locations": []}.

A requirement that only applies sometimes

Some controls only apply to some inputs, like “new features must be tested”, which doesn’t apply to a bug fix. Make the thing that decides it the subject, and keep it only when the control applies, with whose. This one reads a param:

params:
  untested_change_types: [bug_fix, refactor]
subjects:
  deployment:
    from: $input whose deployment.change_type is not in $params.untested_change_types
requirements:
  features_tested:
    subject: deployment
    min_subjects: 0
    checks:
      tested: some test_runs.status exists
      passed: every test_runs.status is "passed"

With {"deployment": {"change_type": "bug_fix"}, "test_runs": []}, the deployment is out of scope, and the report says so:

"compliant": true,
"requirements": {
  "features_tested": {
    "status": "not_applicable",
    "subjects": { "matching": 0, "total": 1 },
    ...

The $applies row reads {"name": "$params.untested_change_types", "value": ["bug_fix", "refactor"], "locations": ["$params:/untested_change_types"]} and {"name": ".deployment.change_type", "value": "bug_fix", "locations": ["/deployment/change_type"]}, and the $applies entry in checks records the list it was compared with too, under $refs: {"name": "$params.untested_change_types", "value": ["bug_fix", "refactor"], "locations": ["$params:/untested_change_types"]}. A new feature with no test runs fails tested and passed, and so does a change type that isn’t listed, like hotfix, so a new or misspelt type has to be tested until someone adds it to the list. A deployment with no change_type fails the requirement, because Ergo can’t tell whether it applies.

The condition lists the types that don’t need tests, rather than the ones that do. deployment.change_type is "new_development" would also work, but then any other type, misspelt ones included, would quietly skip the tests.

Don’t make the test runs the subject instead, with from: test_runs and min_subjects: 0. That lets a new feature with no test runs pass, because there’s nothing to check.

Picking the subject

The subject is what each row is about, so it’s the first choice to make, and it changes more than the rows. Take “every commit was reviewed in an approved pull request”, with this input:

{"commits": [
  {"sha": "a1", "pull_requests": [{"number": 7, "approved_by": "bob"}, {"number": 8}]},
  {"sha": "a2", "pull_requests": []}
]}

With the commit as the subject, the check looks through its pull requests:

ergo_spec: v0.6
subjects:
  commit:
    from: commits
    identified_by: sha
requirements:
  reviewed:
    subject: commit
    checks:
      reviewed:
        description: Some pull request for the commit was approved
        assert: some pull_requests.approved_by is a non-empty string

The requirement is not_met: a2 has no pull request.

With the pull request as the subject, the same sentence turns into “some pull request was approved”:

ergo_spec: v0.6
subjects:
  pull request:
    from: every commits[0].pull_requests
    identified_by: number
requirements:
  reviewed:
    subject: pull request
    require: some
    checks:
      approved:
        description: The pull request was approved
        assert: approved_by is a non-empty string

The requirement is met. Pull request 7 is approved, and a2 is never looked at, because from reads one commit’s pull requests. Same input, same words, opposite answers.

Read the pull requests as a child subject of the commit instead, and require: some is decided for each commit. With this policy and {"commits": [{"sha": "a1", "pull_requests": [{"number": 7, "approved_by": "bob"}, {"number": 8}]}, {"sha": "a2", "pull_requests": [{"number": 9}]}]}:

ergo_spec: v0.6
subjects:
  commit:
    from: commits
    identified_by: sha
  pull request:
    from: every commit.pull_requests
    identified_by: number
requirements:
  reviewed:
    subject: pull request
    require: some
    checks:
      approved:
        description: The pull request was approved
        assert: approved_by is a non-empty string

The requirement is not_met, and its causes is [{"cause": "absent", "rows": 1}]. Commit a1 has an approved pull request, so pull request 8 isn’t a violation, but a2 has none, so pull request 9 is the only violation, with in {"commit": "a2"}. A commit with no pull request fails its own $min_subjects row, or is skipped with min_subjects: 0. With a chain of more than two subjects, each direct parent needs a passing subject. To ask for one anywhere instead, read the pull requests from the input, like every commits.pull_requests: their rows have no in, and some counts across all of them.

So before writing a check, decide:

• What would the policy’s owner list? The report has one row per subject, so the subject is what it lists. A rule about commits should list commits, even when the evidence is organised by pull request.
• What id would they cite? The id that identified_by picks is how a row is found again, and how two reports are compared.
• How many lists sit between the subject and the values compared? every and some walk them all, but a check that compares fields at two levels needs a for line, which takes two lists at most. A check that needs more usually means the subject is one list too high, or the evidence was recorded at the wrong grain. Moving the subject down flattens the check, but then the report lists the smaller thing, as above.
• Does require still say what the sentence says? “Every commit has some approved pull request” is every over commits with some inside a check. With the pull request as a subject read from the input it becomes some over all pull requests, which is only the same rule when there is one commit. As a child subject of the commit it is the same rule.

A policy can hold several requirements with different subjects over the same input, like a lockfile and each of its entries. Each requirement picks its own grain.

Checks

A check is a sentence: one line of English. spec/syntax.md has the full grammar. Write the sentence on its own, or under assert when the check has a description or meta:

ergo_spec: v0.6
subjects:
  deployment:
    from: deployments
    identified_by: id
requirements:
  prod_deploy:
    subject: deployment
    checks:
      approver: approved_by is a non-empty string
      reviewed:
        description: The change was reviewed before it was deployed
        assert: reviewed_at is before deployed_at
      region: region is in $params.regions
      tickets: tickets contains all of 'OPS-1'

With the params {"regions": ["eu-west-1"]} and this input:

{
  "deployments": [
    {"id": "d1", "approved_by": "ann", "reviewed_at": "2026-10-01T09:00:00Z", "deployed_at": "2026-10-01T10:00:00Z", "region": "eu-west-1", "tickets": ["OPS-1"]},
    {"id": "d2", "approved_by": "", "reviewed_at": "2026-10-02T11:00:00Z", "deployed_at": "2026-10-02T10:00:00Z", "region": "us-east-1", "tickets": []}
  ]
}

d1 passes every check and d2 fails every one. Each check’s entry in the report has its description, meta and expression, and the expression is the sentence:

"reviewed": {
  "description": "The change was reviewed before it was deployed",
  "expression": "reviewed_at is before deployed_at",
  "meta": {}
},
"tickets": {
  "description": "",
  "expression": "tickets contains all of \"OPS-1\"",
  "meta": {}
}

The report prints every sentence one way, so 'OPS-1' shows as "OPS-1", two spaces as one, is equal to "a" as is "a", and is before a field as equals. The rows are the rows of the operator each sentence runs as, so d2’s reviewed row reads both fields:

{
  "cause": "value",
  "check": "reviewed",
  "inputs": [
    {"locations": ["/deployments/1/reviewed_at"], "name": "reviewed_at", "value": "2026-10-02T11:00:00Z"},
    {"locations": ["/deployments/1/deployed_at"], "name": "deployed_at", "value": "2026-10-02T10:00:00Z"}
  ],
  "message": "reviewed_at is \"2026-10-02T11:00:00Z\", and deployed_at is \"2026-10-02T10:00:00Z\"",
  "passed": false,
  "requirement": "prod_deploy",
  "subject": {"id": "d2", "type": "deployment"}
}

A sentence is a path, then a phrase, then what the phrase takes:

The time phrases can take a written time or number too, like opened is before "2024-01-01T00:00:00Z" or opened is after 100. The field and the written value must both be RFC 3339 times, both be dates like "2026-10-01", or both be numbers, or the check fails as unusable. A date and an RFC 3339 time fail too, even one at midnight, because a date doesn’t say in which time zone it starts. A written value that isn’t a time, a date or a number, like opened is before "yesterday", is written wrong, with "is before" takes a time or a number.

is not ... within and does not equal ... within pass when the two numbers are further apart than the number after within, so x is not 0.1 within 0.19 passes on 0.3 and fails on 0.29. They fail like the positive forms when a side is missing, null or not a number, so the opposite of a check never passes by reading nothing. The same goes for does not start with and does not end with, for is not a <type> and is not a non-empty string, which pass on "" and on any value that isn’t a string, for is not between, and for contains some of and does not contain all of, which need a list like contains all of.

within works out the gap exactly on the decimals, so 0.3 and 0.1 are within 0.2. That’s promised for numbers with at most 15 significant digits. Longer ones, like 0.30000000000000004, are compared on their digits too, but an engine may not tell two of them apart when they differ only past those digits, so don’t rely on it: Ergo with OPA says what ergo.rego does. The only numbers it can’t compare are ones whose exponents, with the number after within, are more than 4096 apart, like 1e5000 and 1. That check fails as unusable.

is empty passes on "" or [] and is not empty on a string or a list with something in it. Anything else that’s there, like a number or an object, fails both as unusable. Their operators only exist for sentences. starts with and ends with compare two strings: anything else, two numbers included, fails as unusable, and a written value after them that isn’t text, like x starts with 1, is written wrong. is alphabetically before and is alphabetically after order two strings in the same way, code point by code point, so every uppercase letter comes first: "Zoe" is alphabetically before "adam". is alphabetically on or before and is alphabetically on or after pass on two equal strings too.

The negative phrases need what the positive ones need, so a field that can’t be read fails them with the same cause. With this policy:

ergo_spec: v0.6
subjects:
  artifact:
    from: artifacts
    identified_by: name
requirements:
  releasable:
    subject: artifact
    checks:
      not_a_snapshot: version does not end with "-SNAPSHOT"
      not_near_limit: size_mb is not 100 within 5
      trusted_license: licenses contains some of "MIT", "Apache-2.0"
      notes_empty: notes is not a non-empty string

and this input:

{"artifacts": [
  {"name": "api", "version": "1.2.0-SNAPSHOT", "size_mb": 101, "licenses": ["GPL-3.0"], "notes": "ready"},
  {"name": "web", "version": "2.0.0", "size_mb": 140, "licenses": ["MIT", "GPL-3.0"], "notes": ""},
  {"name": "cli", "version": 3, "licenses": null, "notes": null}
]}

every check fails on api, with value. web passes all four, notes being "". cli fails each of them for the reason it can’t be read:

Text can be joined on the right side with followed by, from written strings and fields, as many pieces as you like: rego.version is tag.version followed by "-dev", or rego.spec is "v" followed by tag.version. It goes after is, equals, is not, does not equal, starts with, ends with, does not start with, does not end with, contains, does not contain and the alphabetical phrases, and the sentence asks what the phrase asks of the joined text. There is no preceded by, because "v" followed by x says it. Every piece must be a string: a written one that isn’t, like followed by 1, is written wrong, and a field that isn’t one fails the check as unusable. With this policy:

ergo_spec: v0.6
subjects:
  release:
    from: releases
    identified_by: tag.version
requirements:
  ready:
    subject: release
    checks:
      dev_version: rego.version is tag.version followed by "-dev"
      spec_is_tagged: rego.spec is "v" followed by tag.version

and this input:

{"releases": [
  {"tag": {"version": "0.4"}, "rego": {"version": "0.4-dev", "spec": "v0.4"}},
  {"tag": {"version": "0.5"}, "rego": {"version": "0.5", "spec": "v0.4"}},
  {"tag": {"version": 5}, "rego": {"version": "5-dev", "spec": "v5"}},
  {"tag": {}, "rego": {"version": "x", "spec": "v"}}
]}

both checks pass for 0.4, fail as value for 0.5, whose rego.version doesn’t end with -dev and whose rego.spec isn’t v0.6, fail as unusable for 5, because tag.version is a number, and fail as absent for the last one, because it has no tag.version. The row of each check shows the left side and then each piece that is a field, in order: for 0.5 the dev_version row has rego.version with "0.5" and tag.version with "0.5", and the joined text isn’t one of them. When a piece can’t be read, the check fails with the cause of the first piece that can’t, left to right, even when the left side is missing too. followed by isn’t run yet after every or some, in a whose or in a from line, where it is written wrong with "followed by" isn't supported yet after every or some, or in a whose. It is run in an assertion and under a for line, where a piece can be the alias. Text that spells the words, like "a followed by b", is one string.

is at least, is at most, is more than and is less than only order numbers. Two strings fail as unusable, because a number held as a string would be ordered as text, and with this input:

{"conditions": [{"metric": "coverage", "value": "9", "errorThreshold": "80"}]}

every conditions.value is at least errorThreshold would pass, since "9" comes after "80" as text. A written value that isn’t a number, like score is at least "3", is written wrong, with "is at least" takes a number.

After is in, is not in, contains, does not contain, contains all of, contains none of, contains some of, does not contain all of, matches and does not match, the thing on the right can be a field too, read like the field after is at least: from the subject, from the name of a for line or from the item of a one-line every or some and a whose. With this policy and this input:

ergo_spec: v0.6
subjects:
  deployment:
    from: deployments
    identified_by: id
requirements:
  prod_deploy:
    subject: deployment
    checks:
      reviewed_by_peer: tested_by is in reviewers
      tickets_covered: tickets contains all of required_tickets

{
  "deployments": [
    {"id": "d1", "tested_by": "ann", "reviewers": ["ann", "bob"], "tickets": ["OPS-1", "OPS-2"], "required_tickets": ["OPS-1"]},
    {"id": "d2", "tested_by": "cy", "reviewers": ["ann", "bob"], "tickets": ["OPS-1"]}
  ]
}

d1 passes both and d2 fails both. Its reviewed_by_peer row fails as value, because cy isn’t in the list, and its tickets_covered row fails as absent, because required_tickets is missing:

{
  "cause": "absent",
  "check": "tickets_covered",
  "inputs": [
    {"locations": ["/deployments/1/tickets"], "name": "tickets", "value": ["OPS-1"]},
    {"locations": ["/deployments/1"], "name": "required_tickets", "value": null}
  ],
  "message": "required_tickets is missing",
  "passed": false,
  "requirement": "prod_deploy",
  "subject": {"id": "d2", "type": "deployment"}
}

They run as compare with in, not_in, includes, excludes, includes_all, excludes_all, includes_some, not_includes_all, matches_any and not_matches_any, and only sentences can use those. The row has the same passed and cause as the sentence with $params.required_tickets holding that field’s value, and the field is in the row’s inputs after the left side. A $params or $input path after these phrases, like $params.regions or $input.sbom.components.name, is in the row’s inputs after the left side too, with null when nothing was read, and stays in the check’s $refs, so a violation lists it once. A field on the right that’s missing or null fails the row as absent or null, whatever the left side is. One that can’t be used fails it as unusable: not a list after is in, is not in, contains all of, contains none of, contains some of, does not contain all of, matches and does not match, an empty list after contains all of, contains none of, contains some of and does not contain all of, and patterns that aren’t all valid regular expressions. Only when the right side can be used does the left side’s own cause count.

The rows of every, some and count of list such a path where they list the right side of is at least: one from $input is listed, and one from $params isn’t, since those rows leave $params to $refs. A for line’s own row lists one from either. With the release {"id": "r1", "approvers": [{"username": "ann"}, {"username": "zed"}]} in releases, "staff": ["ann", "bob"] in the input and {"staff": ["ann", "bob"]} as params, every approvers.username is in $input.staff has the inputs

[
  {"locations": ["/staff"], "name": "$input.staff", "value": ["ann", "bob"]},
  {"locations": ["/releases/0/approvers/0/username", "/releases/0/approvers/1/username"], "name": "approvers[].username", "value": ["ann", "zed"]}
]

and for: every approvers as approver with approver.username is in $params.staff has

[
  {"locations": ["$params:/staff"], "name": "$params.staff", "value": ["ann", "bob"]},
  {"locations": ["/releases/0/approvers/0", "/releases/0/approvers/1"], "name": "approvers[]", "value": [{"username": "ann"}, {"username": "zed"}]}
]

on the row, and the same $params.staff entry after approver.username in the failed assertion of item 2.

A path on the right that goes through a list of objects is walked the way a path after every is, and the phrase compares with the list of what the path ends at in each item. With this policy and this input:

ergo_spec: v0.6
subjects:
  pin:
    from: pins
    identified_by: name
requirements:
  pinned:
    subject: pin
    checks:
      in_the_sbom: name is in $input.sbom.components.name

{
  "sbom": {"components": [{"name": "click"}, {"name": "jinja2"}]},
  "pins": [{"name": "click"}, {"name": "attrs"}]
}

click passes and attrs fails as value:

{
  "cause": "value",
  "check": "in_the_sbom",
  "inputs": [
    {"locations": ["/pins/1/name"], "name": "name", "value": "attrs"},
    {"locations": ["/sbom/components/0/name", "/sbom/components/1/name"], "name": "$input.sbom.components[].name", "value": ["click", "jinja2"]}
  ],
  "message": "name is \"attrs\", and $input.sbom.components[].name is [\"click\", \"jinja2\"]",
  "passed": false,
  "requirement": "pinned",
  "subject": {"id": "attrs", "type": "pin"}
}

The path is in the check’s $refs as $input.sbom.components[].name, with the location of each name, and in the row’s inputs after the left side, as a path from the subject is. It works after every phrase above but contains and does not contain, which take one value. Ergo can’t tell whether the names are complete when one can’t be read, so every row fails: a component with no name fails as absent, with the message item 2 of $input.sbom.components: name is missing, one with a null name as null, something that isn’t an object in the list or after the name as unusable, and an empty list as value, even after is not in, with the message $input.sbom.components is []. A path that meets no list is read as before, so a list that is null or missing fails as null or absent, and text fails as unusable with $input.sbom.components is "x", which isn't an object. A phrase that takes one value, like is or starts with, doesn’t read its right side this way.

contains and does not contain look for one value in a list, so the path after them never walks a list. A list it ends at is one value, so a list of pairs can be searched for a pair. A list it meets on the way fails the row as unusable and names that list. On an input that is a list, a path from $input whose first step is a name, like $input.k, fails as not_an_object with $input is [...], which isn't an object, said once without an item inside a whose; $input[0].k reads the first item, and $input alone is the whole input, looked for as one value. To check a list of values, use contains all of, contains some of or contains none of. With this policy and this input:

ergo_spec: v0.6
subjects:
  repo:
    from: repos
    identified_by: id
requirements:
  pinned:
    subject: repo
    checks:
      has_pair: pins contains wanted
      every_team: teams contains all of $input.owners.team
      one_team: teams contains $input.owners.team

{
  "owners": [{"team": "web"}, {"team": "ops"}],
  "repos": [
    {
      "id": "api",
      "pins": [["click", "8.1"], ["jinja2", "3.1"]],
      "wanted": ["click", "8.1"],
      "teams": ["web", "ops"]
    }
  ]
}

has_pair passes, because ["click", "8.1"] is one of the pins. every_team passes, because teams holds both names. one_team fails as unusable, because $input.owners is a list and contains reads one value:

{
  "cause": "unusable",
  "check": "one_team",
  "inputs": [
    {"locations": ["/repos/0/teams"], "name": "teams", "value": ["web", "ops"]},
    {"locations": ["/owners"], "name": "$input.owners.team", "value": null}
  ],
  "message": "$input.owners is [{\"team\": \"web\"}, {\"team\": \"ops\"}], which isn't an object",
  "passed": false,
  "requirement": "pinned",
  "subject": {"id": "api", "type": "repo"}
}

The thing on the right is a value when it’s in quotes, a number, true, false or null, and a field otherwise. A list of values is separated by , . A string can be in single quotes, which keep backslashes as written, so '^\s*FROM' needs no doubled backslash.

A path is keys joined by ., like build.commit.sha. A key with anything but letters, digits, _ and - goes in double quotes, like labels."app.kubernetes.io/name". $params.regions reads the params and $input.repo the input. artifacts named by $params.name reads the key the param holds, and so does artifacts[$params.name]. named by a bare field reads the key the subject holds, as below. item 2 of commits, first of commits and commits[1] read one item of a list. A position above 9007199254740991, the largest whole number a 64-bit float holds exactly, is written wrong, with 9007199254740992 can't be a list position. A param or input value after named by or in brackets has to hold a string: a number never picks a position, so commits[$params.n] with n holding 1 fails the check as unusable, and so does a boolean, a list or an object. A null one fails it as null and a missing one as absent. A path can’t start with a word the sentences use, like empty, count or true. Put a dot in front, .empty is 1, to read a field with that name. The subject’s own name is the subject itself, so a field called like the subject is written with a dot too.

named by a bare field picks the key from the subject, so a limit can depend on a field like the severity. With the params {"max_days": {"critical": 1, "high": 5}}, this policy:

ergo_spec: v0.6
subjects:
  vuln:
    from: vulns
    identified_by: id
requirements:
  fixed_in_time:
    subject: vuln
    checks:
      within_limit: age_days is less than $params.max_days named by severity

and this input:

{"vulns": [
  {"id": "v-1", "severity": "high", "age_days": 3},
  {"id": "v-2", "severity": "critical", "age_days": 2},
  {"id": "v-3", "severity": "unknown", "age_days": 0}
]}

v-1 passes, v-2 fails as value, and v-3 fails as absent, because the params have no limit for unknown. Each row shows the field that picked the key after the check’s own inputs:

{"check": "within_limit", "subject": {"id": "v-2", "type": "vuln"}, "passed": false, "cause": "value", "message": "age_days is 2, and $params.max_days named by severity is 1",
 "inputs": [
   {"name": "age_days", "value": 2, "locations": ["/vulns/1/age_days"]},
   {"name": "$params.max_days named by severity", "value": 1, "locations": ["$params:/max_days/critical"]},
   {"name": "severity", "value": "critical", "locations": ["/vulns/1/severity"]}
 ]}

A field that’s missing fails the check as absent, a null one as null, and one that isn’t a string, a number included, as unusable. The path before the field is read first, so when it’s missing or can’t be read, like $params.max_days missing from the params, the check fails as that path does, whatever the field holds. A field that can’t be read never lets a check pass, does not exist included: x[0] named by zz does not exist with no x fails as absent when zz is missing, null or a number, and passes only when zz is text. A null before the field doesn’t stop the path. In an every, some, count of, sum of or a for line, a list before the field is walked, so every rows.w named by k is "xy" fails as null when k is null. A null there, like rows being null, fails it as null whatever k holds, and failed_items names rows, as every rows.w.k does. Anywhere else, a list before the field fails the check as unusable, so rows.w named by k is "xy" does when rows is a list. A path that reads inside an item that isn’t an object, like w.k named by zz with w a list, fails as not_an_object whatever zz holds. When nothing is read inside it, like w named by zz with w holding 3, the field decides first, so the check fails as absent, null or unusable when zz is missing, null or not text, and as not_an_object when it is text. An alias that is a list, read by a position, like w[0] named by zz, is read as a list. A name from a for line hides a field with the same name. Inside a whose the field is the item’s, as a bare key is there. In the phrase of a one-line every or some it’s the subject’s, whatever the path starts at, so every xs.v equals $params.m named by k reads the subject’s k for every item, and when the subject has no k the check fails once as absent, with k is missing. A from line and identified_by can’t use it, because they don’t have a subject yet.