Skip to main content
A policy is a rule that tells Earnie what to do when a scan finds something. For example, a policy can block any change that introduces a banned licence, or warn when a component is out of date. Earnie uses policies to decide whether a change can merge. Each time Earnie scans a project, it checks the findings against the policies attached to that project. The result is the verdict, and the verdict decides the merge gate. This page explains how to create a policy, choose its action, write its rule, and see which projects it applies to. Before you start:
  • The project needs at least one completed scan, so the policy has findings to evaluate. See Your first scan.
  • You need the Operator or Admin role to create, edit, and delete policies. Viewers can read them. See Team & roles.

What a Policy Does

A project's Policies page, listing the policies attached to it A policy records a decision you would otherwise make by hand on every scan. For example, if you always reject components under a particular licence, a policy rejects them for you each time a scan finds one. You manage policies from Policies in a project’s sidebar. Policies belong to your organisation, and the page lists the ones attached to the current project. See Where a policy applies. Each row reads the policy’s rule in plain words, its domain and action, how many findings violate it right now, how many approval requests are waiting on it, and when it last changed. Turn on Has pending approvals to list only the policies with a request waiting for a decision.

Three Possible Actions

Every policy has one action. The action decides what happens when a finding matches the rule: A gate, a scan or a project waiting on that approval shows Needs approval. When several policies match, the worst action wins: Block, then Require approval, then Warn.
Start with Warn. A new rule set to Warn shows you how many findings it affects without stopping anyone’s merge. Change it to Block once you’ve dealt with the backlog of findings it reports.

When a Policy Does Not Apply to a Run

A policy gates a run only when the run used the scanner the policy reads:
  • If the run didn’t select that scanner, the policy is not applicable to that run. It neither passes nor fails it. For example, a scan that ran only open-source scanning doesn’t answer an AI vendor policy. When every policy in force is not applicable, the gate reads No policy applied.
  • If the run selected the scanner, but it isn’t available, the gate reads Gate could not be evaluated.
  • If the scanner failed during the run, the policies that need it read Not evaluated.
Missing evidence never counts as a pass.

Creating a Policy

You can start from Earnie’s built-in templates, or write your own rule from scratch. Either way, the new policy is attached to the project you created it in.

Starting from Templates

Templates are ready-made policies for the rules most teams set up first.
  1. On the project’s Policies page, select New policy. If the project has no policies yet, select Pick templates instead.
  2. The page has three parts. On the left, Framework, Domain, and Action narrow the list, and each choice shows how many templates it leaves. In the middle are the templates, each with a checkbox, its action, and its rule as a sentence. On the right is a preview of the template you select.
  3. Select a template’s row to preview it. The preview shows its rule in words, what a pull request, a coding agent over MCP, and a full scan do with it, the sentence an agent is told, and the values it starts with. Edit before adding opens it in the editor first.
  4. Tick the templates you want, then select Add n policies (for example Add 3 policies) to add them all at once.
The filters, the search, and the template you are previewing stay in the page address, so a shared link opens the same view. Start from scratch, the last row of the list, opens a blank policy instead. Policies created this way start as drafts, which change no verdict until you turn them on. Open each policy and switch it to Enabled when you want Earnie to enforce it. Policies you turned on in the setup wizard are the exception: those are enabled straight away. If an equivalent policy is already attached to the project, Earnie reuses it instead of creating a duplicate. The built-in templates, with the action each one starts with:

Starting from Scratch

To write a rule yourself, select Start from scratch, on the Policies page or in the template picker. The editor reads from top to bottom as the policy itself:
  1. At the top, type the policy’s name where its title would be, and a sentence about what it protects under it. Choose its Category. A name can be up to 120 characters and a description up to 2,000.
  2. Under What it checks, choose what it evaluates under Evaluates and build the rule.
  3. Under What happens, choose the action.
  4. Under What agents read, write the sentence AI coding agents are told.
Beside them, Try it runs the rule on a project’s findings. A bar at the bottom says whether the policy is ready to save and holds Save policy.

What a Policy Evaluates

Every policy evaluates one kind of finding. When you create a policy, you choose this under Evaluates, at the top of What it checks:
  • OSS findings are findings from open-source scanning.
  • Crypto findings are findings from cryptography scanning. Earnie offers this option only if your organisation has cryptography scanning.
  • AI findings are findings from AI provenance scanning, covering both identified models and AI usage. Earnie offers this option only if your organisation has AI provenance. See AI provenance for the field group and the seven starter templates.
A policy created from a template already has the template’s choice set. The choice decides which fields the rule can read, so you can’t change it after you save the policy: changing it would break the rule. The editor doesn’t show it when you edit a policy, but the policy’s Where this applies panel repeats it, for example “Evaluates Crypto findings.”

Building the Rule

Under What it checks, you can write the condition in two ways, switching between them with Sentence and CEL. Earnie keeps them in sync, so a change in one shows up in the other, and the editor remembers your choice when you reload the page.
  • In Sentence, you build the condition by picking fields, operators, and values, with no syntax to learn. If a condition uses an operator or a value the builder doesn’t offer for that field, the builder still lists it, so the sentence reads what the rule says.
  • In CEL, you write the condition as an expression in CEL (Common Expression Language), with autocomplete and live validation. Use it for conditions the Sentence builder can’t express.
The sentence numbers its conditions: 1, 2, and 2a, 2b inside a group. A value the policy keeps as a parameter, such as a licence list or a minimum key size, shows in the sentence as a chip with the parameter’s name and its value. Select the chip to change the value, rename the parameter, or, for a single value, use a fixed value instead. Renaming a parameter also renames it in the rule and in the sentence agents read. A line under the rule lists the parameters it uses, and names any that are declared but unused, or used but not declared. Open Manage parameters there to add, rename, or remove them; it’s also shown in CEL. When part of a rule has no sentence form, for example a calculation or a check on how a text begins, the sentence shows that part as CEL and says in words why. Its parameters still show as chips you can change, and Edit in the CEL view opens the expression.
Some fields must be checked before they’re read. Not every finding has every field. For example, a key size exists only where Earnie resolved an actual key length. A rule that asks whether a key is under 2048 bits has to limit itself to findings where the key length is known.The Sentence builder writes that check for you. In CEL, you write it with has(). The editor refuses to save a rule that reads such a field without the check, and names the field and the check to add, for example: field "finding.crypto.key_size" is optional — guard with has(finding.crypto.key_size).
Under What happens, choose the action: Warn, Require approval, or Block. Under it, the editor says what that action does on a pull request, for an AI agent over MCP, and on a full scan. Under What agents read, write one sentence for AI coding agents, such as “Do not add dependencies licensed .” A word in braces is filled with the policy’s value for that parameter, and the editor shows the sentence as agents read it today. It can be up to 500 characters. If you leave it empty, agents read the first sentence of the description instead. When it changes, every organisation admin except you gets an Agent rule changed notification. As you work, the editor checks the rule, and the bar at the bottom says how many issues are left to resolve. Then select Save policy in the bar at the bottom of the editor. Before you save, the bar says what saving does: a new policy is added to the project you’re in, and either evaluates when you save or starts as a draft. A policy you write in the editor starts enabled, and the Enable on save switch at the top of the editor shows this. Switch it off to save the policy as a draft. When you edit an existing policy, the button reads Save changes, and the switch reads Enabled or Disabled to show its current state.

Trying a Rule Before You Save

Try it, beside the rule, runs the rule as you’ve written it on one project’s findings and tells you what it would do, for example “Would block 12 of 340 findings”. It starts on the project you opened the editor from. To try the rule on any other project in your organisation, choose that project. It runs by itself once the rule has no issues left, and again after each change. It reads the same findings a saved policy attached to that project would be evaluated against, and it says when that project was last scanned. Under the count, it lists up to ten of the findings it would flag, each with the condition that matched it. Trying a rule saves nothing and changes no verdict. If the rule reads data that the project’s latest scan didn’t collect, Try it says so and doesn’t count anything. Run a scan that collects it, then try again. An AI coding agent can run the same check before it proposes a rule, with the earnie_try_policy MCP tool.

Parameter Checks on Save

Some policies have parameters, values a rule reads such as a licence list or a severity threshold. When you save, Earnie checks every parameter value against its type:
  • a whole-number parameter must hold a whole number, and a decimal one a number
  • a single choice must be one of its options, and a multiple choice a list of only its options
  • a tag list must be a list of text values
  • a toggle must be true or false
  • Earnie refuses a value for a parameter the policy doesn’t declare
A parameter you don’t set takes its default. If it has no default either, Earnie refuses the save. When it refuses one, the editor names the parameter and what it needs, for example that it must be a whole number. Policies saved before this check existed keep their values until you next change their values or parameters. A copy made with Clone policy is checked when it’s created.

When a Change Takes Effect

Saving, enabling, or disabling a policy makes Earnie re-evaluate the current findings of every project it’s attached to, shortly after you save. A disabled policy changes no verdict. A scan that has already run keeps the gate it got from the policies in force at the time. A new or changed policy applies to later scans, not to that one.

Rules About Cryptography

With cryptography scanning, the rule builder gains a Crypto field group, and seven cryptography templates become available. Without it, Earnie hides the Crypto field group, the cryptography templates, and the cryptography template sets.

Crypto Fields for Export Control

The Crypto group includes the finding’s purpose and three export-control signals. These fields are evidence only. Each export signal has one of four values: met, not_met, unknown, or not_evaluated.
When a Sentence rule uses one of these fields, the builder shows a fixed disclaimer: “Export-control evidence supports your self-classification. It is not legal advice and does not determine or imply an ECCN.”The values mean different things, so write rules with care:
  • An absent field means the producer supplied no value. Use has() when a field may be absent.
  • unknown means the producer supplied an applicable test but couldn’t resolve it.
  • not_evaluated means the test had no applicable occurrence evidence.

Fields That Read More Precisely Than They Look

Every Crypto field can be absent, so guard each one with has() in CEL.
  • Route Evidence (finding.crypto.route_evidence) is the weakest call on the strongest path to the finding. The value is direct when Earnie resolved every call statically, dispatch when the path needs an interface or runtime dispatch call (the finding stays reachable), and name_only when every path needs a call matched by method name alone, so reachability is unknown.
  • No Known Callers (finding.crypto.no_callers_only) is true when every path starts in application code that nothing in the application calls, instead of at a main or a recognised framework entry point. To match “reachable from a known caller”, write has(finding.crypto.no_callers_only) && !finding.crypto.no_callers_only.
  • Dependency Relationship (finding.crypto.dependency_relationship) is direct when your project declares the library a dependency finding sits in, and transitive when the library arrives through another dependency. To match “cryptography in a transitive dependency”, write has(finding.crypto.dependency_relationship) && finding.crypto.dependency_relationship == "transitive". These three fields are absent when the scan traced no path to the finding, and on scans that don’t report them. Dependency Relationship is also absent on findings in your own code, and an absent value never means direct.
  • Reachability (finding.crypto.reachability) has three values, not two: reachable, unreachable, and unknown. The finding shows them as Reachable, Not reached, and Unknown. A rule that should fire only on proven usage must say reachable. A rule that asks for “not unreachable” also matches every finding the analysis couldn’t decide.
  • Key Size (bits) (finding.crypto.key_size) exists only where Earnie resolved an actual key length. Where it couldn’t, the field is absent, and a key-size rule skips the finding instead of guessing.
  • Elliptic Curve (finding.crypto.elliptic_curve) names the curve an algorithm or a piece of key material uses, for example secg/secp256k1, when Earnie resolved one. It’s free text, not a fixed list, because CycloneDX’s own curve vocabulary has hundreds of entries.
  • Risk Assessed (finding.crypto.assessed) records whether Earnie’s curated tables decided this finding’s severity. When it’s false, the severity is a placeholder, not a judgement, and reachability doesn’t raise it.
Post-Quantum Status (finding.crypto.pqc_status) has four values, and you need to tell them apart:
Use Post-Quantum Status, not Quantum Safe. The older Quantum Safe (deprecated) yes/no field still works, but a yes/no value can’t separate “we checked, it’s fine” from “we haven’t looked”. It’s true for safe and not-applicable assets, false for vulnerable ones, and absent, not false, for unassessed ones. A rule on it must therefore say “Quantum Safe is set and is false”. A rule that only says “Quantum Safe is false” errors on the findings it can’t answer for. Write new rules against the four-value field instead.
In the field picker, the Crypto group links to Settings → Crypto Assessment with See the assessment rules. That page lists every algorithm family and verdict a cryptography rule can match on, so check it when you decide which family to name in a rule. The link opens in a new tab, so you don’t lose an unsaved policy draft.

Regulatory Template Sets

Some regulations and standards require specific controls. A regulatory template set selects every template mapped to one clause of a standard in a single action, so you don’t have to find them one by one. The sets appear as Quick start cards on a project with no policies yet. In the template picker, each set is a group at the top of the list, headed by the standard, its clause, and how many policies it holds. The group’s Select all ticks its templates, and Add n policies adds them as drafts you can tune afterwards. A template that belongs to two sets shows under both and is ticked once. The first two need cryptography scanning, and the third needs AI provenance.
Neither cryptography set blocks reachable TLS 1.3, the current version. Neither set checks FIPS 140-3 module validation either: that’s out of scope for Earnie.

Where a Policy Applies

A policy belongs to your organisation, not to a single project, so you can attach the same rule to several projects. Open a policy to see its Where this applies panel. It says how many projects the policy is attached to, and lists each one with its connected repository, or No repository connected. Each attached project is governed by its own findings, whether they came from a repository scan, an uploaded folder or archive, or an imported SBOM.

Attaching a Policy to More Projects

Creating, cloning, or picking templates attaches the policy to the project you’re in. To attach a policy to other projects, use Apply a policy in Needs attention on the All projects page. To take a policy off one project, see Detaching a policy from one project. To stop a policy gating every project without deleting it, disable it.

The Organisation’s Policies Page

To see every policy at once, and where each one applies, choose Policies in the organisation sidebar, right after Projects. You need permission to read policies to see it. The organisation's Policies page with the Applies to sheet open on a policy: the projects it is attached to, each with Open policy and Detach, and the other projects with Attach The page lists every policy your organisation owns, with its domain, its action, whether it is enabled or still a draft, and when it last changed. The Applies to column names the projects a policy is attached to: No projects, the project’s name, or the first name and a count, such as payments-api and 1 more. Search by name, or narrow the list by Domain and Action. The Applies to filter has three choices: Any project, Attached to a project, and Attached nowhere. Use Attached nowhere to find policies that govern nothing yet. The filters are kept in the page’s address, so a link reopens the same view. There is no New policy button here. A policy is still created inside a project, from a template or from scratch, and then appears on this page.

Attaching and Detaching from the Organisation Page

Select a policy’s row to open its Applies to sheet. It shows the policy’s name and rule, then your active projects, with the ones the policy is attached to first.
  • Open policy goes to that project’s page for the policy.
  • Detach takes the policy out of force for that project.
  • Attach puts the policy in force on a project it isn’t attached to. Earnie evaluates it against that project’s findings.
Earnie confirms each change and refreshes the list. If a colleague changed the policy while the sheet was open, Earnie declines your change and refreshes the list, and you choose the action again. You need permission to edit policies to attach or detach. Without it, the sheet lists the projects with Open policy and no buttons. A member limited to some projects sees only those projects.

Detaching a Policy from One Project

Detaching takes a policy out of force for one project only. The policy and its other attachments stay. The project’s current result for the policy is cleared, so the project’s posture stops counting it, and the policy’s history is kept. You can attach it again at any time. Detaching is different from deleting. Deleting a policy removes it from every project. Coding agents can attach and detach policies too, with the earnie_attach_policy and earnie_detach_policy tools.

Editing a Shared Policy

Because the rule is shared, editing it changes the gate for every project it’s attached to. The bar at the bottom of the editor says so before you save: it names the projects the save applies to, or counts them when there are more than three, and says they re-evaluate when you save. If you switch an enabled policy off, it says its verdicts in those projects are cleared. Saving doesn’t ask for a second confirmation. If you leave the editor with unsaved changes, by Cancel or a breadcrumb, Earnie asks before discarding them.

Reading a Policy’s Page

The top of a policy’s page says what the policy is: its rule in plain words, when the rule can be read as a sentence, then its action, how many projects it’s attached to, and when it last changed and who changed it. Select that last line to see every change. The page has five tabs:
  • Overview shows the rule and its CEL, where the policy applies, its parameters and its details.
  • Violations lists the findings it catches now.
  • Approvals lists its exceptions.
  • Evaluations has one row for each time the policy ran, with what triggered it: a scan or a change to the policy. This tab used to be called History, and old links to it still work.
  • Changes lists every change to the policy, newest first.

Who Changed What

The Changes tab gives one sentence per change, such as “Action changed from Warn to Block”, with who made it and when. A change made with an API key, for example by a coding agent that wrote the rule over MCP, names the key. For a change to the rule, the description or the agent rule, select Show before and after to compare the two versions. Anyone who can read the policy can read its changes. They don’t need access to the audit log. Edits made before Earnie kept the details of each change show as Edited, with a note that the details weren’t recorded.

Cloning a Policy

Cloning starts a new rule from an existing one, so you don’t have to start from scratch.
  1. Open the policy you want to copy.
  2. Open the More actions menu and choose Clone policy.
  3. Confirm in the dialog.
The copy:
  • has the original’s name with “(copy)” added to the end
  • has its own identifier
  • is attached to the project you cloned it from, and opens straight away so you can adjust it
  • is enabled or a draft, matching the original
  • is always a custom policy you can edit, even if the original came from a template
The copy starts with the same rule and settings as the original, including parameter values. After that, you edit the two separately, and a change to one never affects the other.

Turning a Policy Off or Deleting It

  • To turn a policy off, switch it to Disabled on its page. It stays attached and keeps its settings, but changes no verdict until you enable it again.
  • To take a policy off one project, detach it from that project.
  • To delete a policy, open the More actions menu and choose Delete policy. Deleting removes it and detaches it from every project, and you can’t undo it. The rule stops enforcing straight away, but its evaluation history is kept.
On the Policies page, you can also tick several policies to Enable, Disable, or Delete them together. Deleting there removes them from your organisation, not only from this project.

What’s Next

Once a policy is live, apply it to more projects from All projects, which shows every project’s standing on one page. Then read Merge gate to see what happens on a pull request when the gate blocks a merge.