Policy DSL Reference (Rego / OPA Authoring Surface)

Overview

Chainsaw has two policy surfaces. The dashboard / YAML conditions: surface (covered in How to Configure Chainsaw with YAML Configuration Files) is the simpler, built-in one — pick a condition, pick an operator, pick a value. The Policy DSL is the second surface: a Rego / OPA rule set you author as code, sign, and load into the server. It exists for the long tail of org-specific rules that don’t map cleanly onto a single built-in condition — multi-field logic, surface-scoped tightening, and rules that key on caller identity or coordinate patterns.

This page is the authoring reference: the entrypoint, the input fields a rule can read, the decision it returns, and which inputs are populated at which surface.

Prerequisites

• Admin access to the Chainsaw server and its filesystem (the bundle loads from CHAINSAW_POLICY_BUNDLE)
• Familiarity with Rego
• Signing set up before you enforce in production — see Signed Policy Bundles

The entrypoint

Every rule contributes to a single decision query:

data.chainsaw.policy.decision

Your module declares package chainsaw.policy and adds one or more partial decision rules. The engine collects every decision object that fires for a request and reduces them to the strictest action.

package chainsaw.policy

decision contains {
	"action":             "block",
	"rule_id":            "my-rule",
	"message":            "human-readable reason",
	"exception_eligible": true,
} if {
	# conditions that read input.* fields
	input.isKnownMalicious == true
}

The decision object

Each decision your rule emits is an object with these keys:

The actions and their strictness ranking (strictest first):

• block — refuse the request.
• quarantine — at the proxy, the artifact may be cached but withheld; at the publish surface there is no stored row to withhold yet, so a quarantine verdict refuses the upload outright (quarantine-at-publish is block-not-log).
• monitor — record what would have happened without enforcing. Only escalates an otherwise-allow decision.
• allow — explicit permit.
• notify_owner — a side-effect action that adds an ownership routing intent without gating the install. It ranks at the same level as allow (it carries no enforcement weight on its own). See How to Route Violations to Owners.

Input fields

The request is projected onto a single JSON document (input) before your rule runs. Every surface produces the same shape; missing fields stay zero-valued (false, 0, "", or omitted). The field names below are the contract — they are lowerCamelCase so you don’t have to remember Go conventions.

Surface and identity

Caller / network identity

Package metadata

Vulnerability

Supply-chain integrity

Attestation (SLSA / Sigstore)

Install-script and behavior signals

Version and Unicode anomalies

Manifest hygiene and maintainer signals

Capability scanners (npm; gated)

AI-artifact signals

Checksum

Which inputs are available at which surface

The input shape is identical at every surface, but the intelligence-derived signal fields are only populated when the intelligence providers have run for that request.

Worked examples

The examples below are adapted from the demo bundle that ships in the repo at policies/chainsaw_policy.rego — use that file as your starting point.

Example 1 — young maintainer + install script

The canonical demo rule: block packages that declare an install script and have a maintainer account younger than 90 days. Authored once, enforced at every surface where both signals are populated.

package chainsaw.policy

decision contains {
	"action":             "block",
	"rule_id":            "young-maintainer-with-install-script",
	"message":            sprintf("youngest maintainer is %d days old; package declares install script", [input.maintainerAccountAgeDays]),
	"exception_eligible": true,
} if {
	input.maintainerAccountAgeDays > 0
	input.maintainerAccountAgeDays <= 90
	input.hasInstallScript == true
}

Example 2 — harder verdict on remote-fetching install scripts

Same shape, no exception, when the install script fetches a remote payload — that’s the exfil signature, not just a build step.

decision contains {
	"action":             "block",
	"rule_id":            "young-maintainer-with-remote-fetching-install-script",
	"message":            "young maintainer + install script that fetches remote payload",
	"exception_eligible": false,
} if {
	input.maintainerAccountAgeDays > 0
	input.maintainerAccountAgeDays <= 90
	input.installScriptFetchesRemote == true
}

Example 3 — surface-scoped tightening

React to input.surface. At runtime install, flag young maintainers in monitor mode even when the install-script signal is missing (some ecosystems only get it after a tarball-side scan).

decision contains {
	"action":             "monitor",
	"rule_id":            "runtime-young-maintainer",
	"message":            "young maintainer at install time — flagging for review",
	"exception_eligible": true,
} if {
	input.surface == "runtime"
	input.maintainerAccountAgeDays > 0
	input.maintainerAccountAgeDays <= 30
}

Audit trail

Every decision the DSL contributes is stamped with the bundle’s content digest, so a verdict is reproducible against a known rule-set version. Each decision your rule emits surfaces in the audit trail as the rule_id and message you set, and that bundle digest is carried into the audit trail — see Signed Policy Bundles.

Next Steps

• Signed Policy Bundles — author, sign, verify-at-load, and promote your bundle
• YAML Conditions vs the Rego DSL — which surface to use, and how they relate
• How to Manage Policy Precedence and Exception Workflows — how DSL verdicts merge with native policy