Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Write your own rules

    View as Markdown

    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.

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

    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/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 snippetExample result
    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

    • warningacme.agent-without-max-turnsline 7proof 1 pattern

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

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

    A clean file prints:

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

    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)
    Terminal window
    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:

    Terminal window
    keryn scan . --rules rules/no-unbounded-agent.yml,bundled:all

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

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

    .keryn.yml
    apiVersion: keryn.dev/config/v1
    rules: ["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).

    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.