# Write your own rules

> Add rules of your own to a scan, check what the engine supports, and keep them in .keryn.yml.

Source: https://keryn.dev/docs/guides/custom-rules/

## Goal

Add a rule of your own to a scan, check that the engine can run it, and keep it in the project configuration so the CLI, CI and the editors all apply it.

## Before you start

- The Keryn CLI ([install](https://keryn.dev/docs/start/install/)) and a repository.
- A pattern in your code that you want flagged, ideally one you can write as a short example.

## 1. Write the rule

Keryn runs rules written in a Semgrep-compatible syntax: `pattern`, `patterns`, `pattern-either`, `pattern-inside`, `pattern-not`, `pattern-regex`, metavariables and their conditions, `focus-metavariable`, and data-flow rules (`mode: taint` with sources, sinks and sanitizers). It is a subset of Semgrep's syntax, and Keryn says so instead of guessing: a rule or a part of a rule the engine cannot run is reported as unsupported or partial in every output, and the scan exits with 3.

```yaml
# rules/no-unbounded-agent.yml
rules:
  - id: acme.agent-without-max-turns
    languages: [python]
    severity: WARNING
    message: Runner.run is called without max_turns; bound the agent loop.
    patterns:
      - pattern: Runner.run(...)
      - pattern-not: Runner.run(..., max_turns=$N, ...)
```

The recorded result below shows the rule applied to a file with one bounded and one unbounded call. Use the commands in step 3 to test changes locally.

**Your rule on a snippet** (a live example on the page; the engine runs in the browser, nothing is uploaded)

```python
from agents import Agent, Runner

triage = Agent(name="triage", instructions="Route the ticket.")

def handle(ticket):
    return Runner.run(triage, ticket)

def handle_bounded(ticket):
    return Runner.run(triage, ticket, max_turns=5)
```

Rule:

```yaml
rules:
  - id: acme.agent-without-max-turns
    languages: [python]
    severity: WARNING
    message: Runner.run is called without max_turns; bound the agent loop.
    patterns:
      - pattern: Runner.run(...)
      - pattern-not: Runner.run(..., max_turns=$N, ...)
```

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

```text
1 finding · 1 of 1 rules ran on 1 file

warning acme.agent-without-max-turns line 7 [proof 1 pattern]
  Runner.run is called without max_turns; bound the agent loop.
  | return Runner.run(triage, ticket)
```

Only line 6 is reported. The call on line 10 passes `max_turns`, so `pattern-not` removes it. The finding is at proof level 1: a pattern matched, nothing more is established.

## 2. Lint it

```sh
keryn rules lint rules/no-unbounded-agent.yml        # structure, and what this engine can run
```

A clean file prints:

```text
rules/no-unbounded-agent.yml: 1 rule(s)
0 error(s), 0 warning(s)
```

## 3. Run it on your code

Put the same two functions in a file of the repository:

```python
from agents import Agent, Runner

triage = Agent(name="triage", instructions="Route the ticket.")

def handle(ticket):
    return Runner.run(triage, ticket)

def handle_bounded(ticket):
    return Runner.run(triage, ticket, max_turns=5)
```

```sh
keryn scan . --rules rules/no-unbounded-agent.yml --verbose | grep -A2 'without max_turns'
```

```text
  [review; unclassified] Runner.run is called without max_turns; bound the agent loop.
    runner.py:7 · pattern · 1 contributing rule(s) · sha256:0bc77901c48683b2553d1da4c5c306472b406258e4fd50538354b5c35a4c5080
    Pattern match [proof 1]
```

`runner.py:7` is the unbounded call; the bounded one on line 11 is not reported. The coverage line of the full output says `1/1 requested rules`: your one rule ran. (Other findings in the list come from Keryn's data-flow engine, which runs in every scan and does not depend on `--rules`.) To run your rule **and** the bundled library, name both:

```sh
keryn scan . --rules rules/no-unbounded-agent.yml,bundled:all
```

`--rules` takes files and bundled packs, comma-separated (not directories).

## 4. Keep it in the configuration

Put the list in the project configuration so every surface (CLI, CI, editors) uses it:

```yaml
# .keryn.yml
apiVersion: keryn.dev/config/v1
rules: ["bundled:all", "rules/no-unbounded-agent.yml"]
```

Use the [rule playground guide](https://keryn.dev/playground/) for a short CLI example. Give your rules an id prefix of your own (`acme.`), so they never collide with Keryn's.

`keryn explain acme.agent-without-max-turns --rules rules/no-unbounded-agent.yml` prints the rule's message and severity, and its edge, confidence and references once you add them as `metadata` ([explain and docs](https://keryn.dev/docs/guides/explain-and-docs/)).

## What you just proved

The engine runs your rule the same way it runs Keryn's, at the proof level its pattern deserves (a pattern matched: rung 1), and it tells you when it could not run part of a rule instead of passing silently. The rule logic of the bundled library stays inside the product; yours stays in your repository. Two rule sets, one gate.

## Next

- Say what a finding means: [explain and docs](https://keryn.dev/docs/guides/explain-and-docs/).
- Gate it in the pipeline: [CI](https://keryn.dev/docs/guides/ci/).
- Accept an exception: [suppressions](https://keryn.dev/docs/guides/suppressions/).
