Policies
Write down which model providers and AI components your code may reference, and let keryn scan fail when it references anything else. A policy is a short YAML file checked against the AI-BOM.
Before you start
Section titled “Before you start”- The Keryn CLI (install) and a repository.
- The AI-BOM idea: a policy talks about components (a library, a model, an agent framework) and their category, not about lines of code.
A policy can:
- allow or block model providers and components (for example: only approved providers, no model loaded with remote code enabled),
- mark components for review instead of failing (an MCP server, an LLM gateway),
- judge changes against a base: prompt edits need review, a model swap blocks,
- waive a policy rule, for every component or one, with a reason, an owner and an expiry date (see suppressions).
1. Start from the starter
Section titled “1. Start from the starter”keryn initkeryn policy lint .keryn/policy.ymlwrote .keryn.ymlwrote .keryn/policy.ymlrules: bundled:all (vulnerability, audit and AI-BOM inventory rules, the same as `keryn scan` with no config); edit "rules" in .keryn.yml to narrow it (bundled:aibom = inventory only)..keryn/policy.yml: valid (keryn.dev/policy/v1)keryn init writes a project configuration that points at the policy and runs every bundled rule pack (rules: bundled:all, what keryn scan does with no config; it prints what is included), and a starter policy with three rules: only openai and anthropic as model providers, no remote-code models, agent frameworks need a guardrail library. policy lint checks the file against the policy schema and exits 0 when valid, 1 with the path and the problem.
2. Run the gate
Section titled “2. Run the gate”keryn scan . | grep -A1 "^AI-component constraints"AI-component constraints: satisfied (3 checks, 0 violations)Exceptions: 0 expired suppression entries; changes since the base unknown (no base run with its exceptions)The policy passes: the repository references only openai and anthropic. (The scan as a whole can still fail on findings from the rules: the policy is one part of the gate, shown on its own policy: line.)
3. Make it fail on purpose
Section titled “3. Make it fail on purpose”Narrow the allowed providers to openai only:
apiVersion: keryn.dev/policy/v1name: openai-onlyrules: - id: approved-llm-providers description: Only approved model providers may be referenced severity: error match: {kind: library, category: llm-sdk} allowOnly: {field: name, values: [openai]}keryn scan . | grep -A1 "^AI-component constraints"AI-component constraints: violated (1 checks, 1 violations) [error] approved-llm-providers: Only approved model providers may be referenced: name 'anthropic' of 'anthropic' is not on the allow-list @ support.py:1The violation names the rule, the component and the file and line where the component was found. A policy rule has a match (which components it looks at) and one test: allowOnly, deny or requires. Every key is in the policy reference.
4. Check a BOM you saved earlier
Section titled “4. Check a BOM you saved earlier”A policy does not need the source. You can judge a saved AI-BOM, which is how a release job re-checks what a build contained:
keryn bom . --no-config > ../bom.cdx.json 2>/dev/nullkeryn policy check ../bom.cdx.json --policy .keryn/policy.yml | grep -A1 "^AI-component constraints"AI-component constraints: violated (1 checks, 1 violations) [error] approved-llm-providers: Only approved model providers may be referenced: name 'anthropic' of 'anthropic' is not on the allow-list @ support.py:1With --base base.cdx.json the check also judges changes: changes.model: block fails a model swap and changes.prompt: review warns on an edited prompt. See baselines and deltas.
5. Start from a template
Section titled “5. Start from a template”Keryn ships six templates (baseline, agent tools, prompt change review, and three that cite clauses of the EU AI Act, NIST AI RMF and ISO/IEC 42001). They are printed in full, with every key of the format, in the policy reference. Copy one, change the provider lists (the ones shown are placeholders) and lint it.
6. Gate dependency licences
Section titled “6. Gate dependency licences”The same file can judge the licences of your locked dependencies with a licenses: key (deny and allow lists of SPDX identifiers, and what to do with unknown licences). Those violations print under Dependency licences, apart from the AI-component rules. Where the licences come from and how expressions with OR are judged: software composition analysis.
What you just proved
Section titled “What you just proved”A policy turns “we only use approved providers” from a sentence in a wiki into a gate on the edge between your code and the services it reaches: the build fails when a new provider appears, with the file and line where it appeared. It judges what the code references, not what runs in production, and it needs a person to decide the list. It does not decide the list for you.
- Accept an exception, with an owner and an expiry: suppressions.
- Judge a pull request by what it adds: baselines and deltas.
- Run it in the pipeline: CI.
Try a policy
Section titled “Try a policy”The file below references openai. The policy allows only anthropic, so the provider rule fails. Use the CLI steps above to check changes to the allowed provider list.
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
reply = client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}])Policy
apiVersion: keryn.dev/policy/v1
name: anthropic-only
rules:
- id: approved-llm-providers
description: Only approved model providers may be referenced
severity: error
match: {kind: library, category: llm-sdk}
allowOnly: {field: name, values: [anthropic]}2 findings · 29 of 29 rules ran on 1 file
- info
keryn.inv.lib.openailine 2proof 0 inventoryReferences the OpenAI SDK.
Edge depends_on
from openai import OpenAI - info
keryn.inv.model.openailine 5proof 0 inventoryHard-coded OpenAI model identifier.
Edge depends_on
reply = client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}])
AI-BOM delta: 2 new components vs an empty baseline
- + library
openai(openai) · line 2 - + model
gpt-4o-mini(openai) · line 5
Your policy pass
Result computed when this page was built. Run an example with the CLI