Explain a rule and read the docs offline
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.
Before you start
Section titled “Before you start”- The Keryn CLI (install). Both commands read from the package. They make no request.
- A rule id from a finding.
keryn scan . --verboseprints it in brackets; the rule catalog lists them all.
1. Explain a rule
Section titled “1. Explain a rule”keryn explain seceng.llm05.python-subprocess-shell-trueseceng.llm05.python-subprocess-shell-true
subprocess with shell=True is risky if command text can be influenced by model, tool, or workflow output.
Severity WARNINGConfidence P1FP risk mediumKind vulnEdge calls (boundary: model->code)Languages pythonTechnology github-actionsOWASP LLM LLM05 Improper Output Handling; LLM06 Excessive AgencyOWASP AgenticASI05 Unexpected Code Execution; ASI02 Tool Misuse and ExploitationCWE 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:
keryn explain seceng.llm05.python-subprocesskeryn: error: no rule 'seceng.llm05.python-subprocess'; did you mean: seceng.llm05.python-subprocess-shell-trueSome 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.
Your own rules
Section titled “Your own rules”--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, ...)keryn explain acme.agent-without-max-turns --rules rules/no-unbounded-agent.ymlacme.agent-without-max-turns
Runner.run is called without max_turns; bound the agent loop.
Severity WARNINGLanguages pythonAdd metadata.edge, metadata.confidence and metadata.references to your rule and they appear here.
2. Read the docs that ship in the CLI
Section titled “2. Read the docs that ship in the CLI”keryn docs | head -8Keryn 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 applicationWith 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:
keryn docs nopekeryn: 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:
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.
3. Use them together
Section titled “3. Use them together”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.
What you just proved
Section titled “What you just proved”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.
- Write your own rule and explain it: custom rules.
- Everything the CLI accepts: CLI reference.
- Run with no network at all: air-gapped use.