Write your own rules
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
Section titled “Before you start”- The Keryn CLI (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
Section titled “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.
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.
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
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, ...)1 finding · 1 of 1 rules ran on 1 file
- warning
acme.agent-without-max-turnsline 7proof 1 patternRunner.run is called without max_turns; bound the agent loop.
return Runner.run(triage, ticket)
Result computed when this page was built. Run an example with the CLI
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
Section titled “2. Lint it”keryn rules lint rules/no-unbounded-agent.yml # structure, and what this engine can runA clean file prints:
rules/no-unbounded-agent.yml: 1 rule(s)0 error(s), 0 warning(s)3. Run it on your code
Section titled “3. Run it on your code”Put the same two functions in a file of the repository:
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)keryn scan . --rules rules/no-unbounded-agent.yml --verbose | grep -A2 'without max_turns' [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:
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
Section titled “4. Keep it in the configuration”Put the list in the project configuration so every surface (CLI, CI, editors) uses it:
apiVersion: keryn.dev/config/v1rules: ["bundled:all", "rules/no-unbounded-agent.yml"]Use the rule playground guide 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).
What you just proved
Section titled “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.
- Say what a finding means: explain and docs.
- Gate it in the pipeline: CI.
- Accept an exception: suppressions.