Skip to content

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

    Explain a rule and read the docs offline

    View as Markdown

    Answer “what does this finding mean?” and “what does this flag do?” from the terminal, in the same words the website uses, without a network connection and without opening a browser.

    • The Keryn CLI (install). Both commands read from the package. They make no request.
    • A rule id from a finding. keryn scan . --verbose prints it in brackets; the rule catalog lists them all.
    Terminal window
    keryn explain seceng.llm05.python-subprocess-shell-true
    seceng.llm05.python-subprocess-shell-true
    subprocess with shell=True is risky if command text can be influenced by model, tool, or workflow output.
    Severity WARNING
    Confidence P1
    FP risk medium
    Kind vuln
    Edge calls (boundary: model->code)
    Languages python
    Technology github-actions
    OWASP LLM LLM05 Improper Output Handling; LLM06 Excessive Agency
    OWASP AgenticASI05 Unexpected Code Execution; ASI02 Tool Misuse and Exploitation
    CWE CWE-78
    Framework ids are references for readers who work in those frameworks, not a compliance claim.

    What the lines say, and where the website says it too:

    Line Meaning Longer explanation
    Severity what the gate uses: ERROR, WARNING or INFO formats
    Confidence, FP risk how sure the rule’s author is (P0 to P3) and how often it fires on code that is fine rule catalog
    Edge, boundary which relationship the rule inspects (calls) and which trust boundary it crosses (model->code) edge kinds, trust boundaries
    OWASP, CWE framework ids, for readers who work in them taxonomies

    A rule’s remediation and references are printed under these lines when it has them. The detection logic is never printed: no pattern, source or sink leaves the monorepo. For a script, --json prints the same fields as an object (id, message, severity, confidence, edge, edgeBoundary, taxa, references, …).

    A mistyped id exits 2 and suggests the nearest:

    Terminal window
    keryn explain seceng.llm05.python-subprocess
    keryn: error: no rule 'seceng.llm05.python-subprocess'; did you mean: seceng.llm05.python-subprocess-shell-true

    Some entries in a scan’s --verbose list, such as seceng/shell_exec, are findings from Keryn’s data-flow engine rather than rule files, so they have no page to explain; the pattern rules that sit next to them do.

    --rules points explain at a rule file or a bundled pack, so a rule you wrote in custom rules explains itself the same way:

    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, ...)
    Terminal window
    keryn explain acme.agent-without-max-turns --rules rules/no-unbounded-agent.yml
    acme.agent-without-max-turns
    Runner.run is called without max_turns; bound the agent loop.
    Severity WARNING
    Languages python

    Add metadata.edge, metadata.confidence and metadata.references to your rule and they appear here.

    Terminal window
    keryn docs | head -8
    Keryn docs (offline pack 0.5.2, source cli-builtin)
    Usage: keryn docs <topic> | keryn docs --list --json
    cmd-agents usage of keryn agents
    cmd-ai-test usage of keryn ai-test
    cmd-api usage of keryn api
    cmd-application usage of keryn application

    With no topic it lists them. A topic is an id or a unique prefix. An ambiguous prefix (cmd-s matches several commands) names the candidates and exits 2, and so does an unknown topic:

    Terminal window
    keryn docs nope
    keryn: error: no docs topic 'nope' (try 'keryn docs --list')

    Today the pack holds the command help (cmd-<command>), commands, options (the flags every scan command shares), exit-codes, formats and edges (the eight edge kinds). Topics print as Markdown, so they pipe into any pager or into an agent:

    Terminal window
    keryn docs edges | sed -n 1,3p
    # Edge kinds
    Trust lives in relationships, so Keryn describes a finding by the edge it sits on. Each rule carries `metadata.edge`, one of the eight kinds below or `none`

    Every page is checked against the pack’s SHA-256 manifest before it is printed, so a damaged pack fails loudly. keryn docs --list --json is the machine-readable index, and KERYN_DOCS_PACK=<directory> reads another pack of the same format, such as one built from this site with npm run docs-pack in its repository.

    A finding says Edge calls (boundary: model->code). keryn docs edges says what calls means, keryn explain says which rule, and the page for the kind and the boundary say what to do about it. The terminal gives you the definition and the website gives you the diagram; both come from the same source.

    The words in a finding are not a private vocabulary of the tool: each one (rule, edge, boundary, exit code) can be looked up from the thing you are holding, offline, with the same definition the docs use. That matters in the places where Keryn runs: a CI runner, an air-gapped network, a train.