Writ

Policy input and built-ins

The input a policy reads, the Rego built-ins it can call, and its bounds.

A policy reads one input, the masked plan document, and can call a fixed list of Rego built-ins. Everything it does runs in a bounded child process. Policy explains when policies run, and Write and test a policy shows how to write one.

Input

The input is the masked plan document as writ serve stores it, with one key added, input.writ. It has format_version, terraform_version, timestamp, errored, resource_changes, resource_drift, output_changes, checks, and relevant_attributes as tofu show -json writes them, with these differences, which the mask makes:

  • A value under a sensitive mark is the string (sensitive).
  • planned_values and prior_state are dropped. They repeat the changes.
  • variables is a list of the variables' names, with no values.
  • configuration has providers, each with key, name, full_name, alias, version_constraint, and module_address, and modules, each with address, source, and version_constraint.

A schema of the input type checks every rule at start. A rule that reads a key the input never has, such as input.planned_values, is refused, because under writ serve it would never deny.

input.writ:

KeyAt the plan pointAt the apply point
decision"plan""apply"
nowWhen the plan was evaluated, RFC 3339, UTCWhen the apply was asked for
environmentThe plan's environmentThe same
stackThe plan's stackThe same
actorThe plan's author: person, display, kind, and teamsThe person or CI job that asks for the apply
approvals[]The approvals that count: person, display, and via

Under conftest, input.writ is absent. A rule that reads it gets no value there, and gives no message. To read it with a default, use object.get, as examples/policy/writ.rego does:

environment := object.get(input, ["writ", "environment"], "")

Built-ins

A policy can call only the built-ins below. A rule that calls another fails to compile, so writ serve doesn't start. internal/policy/builtins.go has the same list, and a test keeps the two equal.

FamilyBuilt-insWhy
Operatorseq, assign, equal, neq, gt, gte, lt, lte, plus, minus, mul, div, rem, and, or, internal.member_2, internal.member_3Comparison, arithmetic, set intersection and union, and in. Every rule needs them
Numbersabs, round, ceil, floor, to_number, format_intCounts and limits
Aggregatescount, sum, max, min, sortA rule over the changes of a plan
Collectionsarray.concat, array.slice, array.reverse, intersection, union, object.get, object.keys, object.unionReading the input's lists and objects, and input.writ where conftest has none
Typesis_string, is_number, is_boolean, is_array, is_set, is_object, is_null, type_nameA value of a change can be any type, or null
Stringsconcat, contains, startswith, endswith, lower, upper, split, replace, trim, trim_space, trim_prefix, trim_suffix, indexof, substring, sprintfAddresses, types, and messages
Patternsregex.match, glob.matchMatching addresses and types. Go's regexp runs in linear time
Timetime.parse_rfc3339_ns, time.parse_ns, time.parse_duration_ns, time.date, time.clock, time.weekday, time.add_date, time.diff, time.formatChange windows over input.writ.now. "Local" is UTC
Encodingjson.marshalA message that shows a value of the input

Writ leaves out every other built-in of OPA v1.22.4, for one of these reasons:

  • http.send, net.lookup_ip_addr, providers.aws.sign_req, and opa.runtime read the network, the host, or its environment.
  • time.now_ns, rand.intn, and uuid.rfc4122 read the clock or randomness, so a decision wouldn't depend on its input alone. A rule reads the time from input.writ.now.
  • json.verify_schema and json.match_schema follow a file:// reference. A security review read a host file into a message with one.
  • strings.render_template, every bits.*, numbers.range, and numbers.range_step can run past a deadline or allocate gigabytes in one call.
  • print and trace write the input out.
  • walk, yaml.*, the encodings, graphql.*, rego.*, and the rest have no use here yet.

Bounds and failures

writ serve evaluates every set of one decision in a child process: the writ binary itself, with UTC as its only time zone, no environment, and only stdin and stdout. It closes every descriptor that it inherited. Its garbage collector works hard from half of memory, and on Linux its address space can grow by memory past what it maps at its start. writ serve kills it at timeout. The input it gets is at most 16 MiB.

A decision keeps at most 100 messages of each set. The mask sweeps each message whole, and then cuts it at 1,000 bytes. A cut that falls inside a (sensitive) marker cuts before the marker.

Every failure that Writ detects denies at a mandatory set's level, so a plan that a failed policy checked can't be approved:

  • The process ran past timeout, or past its memory, or crashed, or wrote anything but the protocol's lines. Every set is an error.
  • A rule's built-in failed, such as to_number("seven"). Built-in errors are strict.
  • A built-in panicked.
  • A rule's value isn't a set of messages, or a message isn't a string.
  • The input couldn't be built, or is larger than 16 MiB.

Limits. A condition that's false for a wrong reason isn't detected. input.writ.environment == "production" where the environment is prod gives no value, which reads as no deny. A set's tests guard against it.

This page is built from docs/policy-reference.md in the repository. It is also served as plain Markdown.

On this page