# Policies

> Decide which AI providers and components are allowed, what needs review and what a change may add, and gate a scan on it.

Source: https://keryn.dev/docs/guides/policies/

## Goal

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

- The Keryn CLI ([install](https://keryn.dev/docs/start/install/)) and a repository.
- The [AI-BOM](https://keryn.dev/docs/guides/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](https://keryn.dev/docs/guides/suppressions/)).

## 1. Start from the starter

```sh
keryn init
keryn policy lint .keryn/policy.yml
```

```text
wrote .keryn.yml
wrote .keryn/policy.yml
rules: 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

```sh
keryn scan . | grep -A1 "^AI-component constraints"
```

```text
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

Narrow the allowed providers to `openai` only:

```yaml
apiVersion: keryn.dev/policy/v1
name: openai-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: [openai]}
```

```sh
keryn scan . | grep -A1 "^AI-component constraints"
```

```text
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:1
```

The 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](https://keryn.dev/docs/reference/policy/).

## 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:

```sh
keryn bom . --no-config > ../bom.cdx.json 2>/dev/null
keryn policy check ../bom.cdx.json --policy .keryn/policy.yml | grep -A1 "^AI-component constraints"
```

```text
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:1
```

With `--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](https://keryn.dev/docs/guides/baselines/).

## 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](https://keryn.dev/docs/reference/policy/). Copy one, change the provider lists (the ones shown are placeholders) and lint it.

> **Caution: Not a compliance determination**
> A template's `references:` block points readers to framework clauses. Keryn ignores it when it evaluates, and a passing run says nothing about any regulation or standard.

## 6. Gate dependency licences

> **Caution: Ships in the next release**
> On main; Keryn 0.5.2 does not read a `licenses:` key.

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](https://keryn.dev/docs/guides/sca/#licence-policy).

## 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.

## Next

- Accept an exception, with an owner and an expiry: [suppressions](https://keryn.dev/docs/guides/suppressions/).
- Judge a pull request by what it adds: [baselines and deltas](https://keryn.dev/docs/guides/baselines/).
- Run it in the pipeline: [CI](https://keryn.dev/docs/guides/ci/).

## 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.

**A policy against a small file** (a live example on the page; the engine runs in the browser, nothing is uploaded)

```python
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:

```yaml
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]}
```

Result, computed when the site was built by the same engine as `keryn scan`:

```text
2 findings · 29 of 29 rules ran on 1 file

info keryn.inv.lib.openai line 2 [proof 0 inventory]
  References the OpenAI SDK.
  Edge: depends_on
  | from openai import OpenAI

info keryn.inv.model.openai line 5 [proof 0 inventory]
  Hard-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
```
