Read an attack chain
Read the trace of a finding that spans two files and answer four questions about it: where does the data start, what does it pass through, where does it end, and how much does Keryn actually know. By the end you can tell a chain from a lead.
The AppSec journey finds a chain to a shell and breaks it. This guide takes a different edge, a write, and spends its time on reading.
Before you start
Section titled “Before you start”- The Keryn CLI (install) and
jq. - The words: a chain is an ordered sequence of edges, a source is where untrusted data enters, a sink is where it does something. See paths, chains, graphs and chokepoints and the proof ladder.
1. The code
Section titled “1. The code”A note-taking agent asks a model for a note and stores it. Write the three files in a directory of a repository (an empty one works too):
from pathlib import Path
ROOT = Path("/srv/notes")
def save_note(name: str, body: str) -> None: """Write a note under the notes directory.""" target = ROOT / name target.write_text(body)import json
from openai import OpenAI
from notes.storage import save_note
client = OpenAI()
def remember(conversation: str) -> None: reply = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "Return JSON with name and body of a note: " + conversation}], ) note = json.loads(reply.choices[0].message.content) save_note(note["name"], note["body"])"""Notes agent."""2. Scan it and ask for the flow
Section titled “2. Scan it and ask for the flow”keryn scan . --include 'notes/**' --verboseKeryn — Checks passed (Go)Analysis: complete · Policy: checks passed · Approval: not recordedbase not recorded → analyzed 69a8fd978be3df6646542bac4cd38507eae55067-dirtyComparison: not compared: no finding baseline suppliedCases: 1 current = 0 new + 0 existing + 1 unclassified; unknown cleared from previous assessmentNewly blocking: unknown (no complete base run to compare with)Cases: 1 of 1 shown (limit 20); 0 omitted by display limit [review; unclassified] Untrusted input reaches the path of a file that is written (arbitrary file write). notes/storage.py:9 · path-cross-file · 2 contributing rule(s) · sha256:82b4a10f41571dfb9cec8c08b655356d0c5a791b40c5114c33316fd3e26e0736 Cross-file flow [proof 3] source notes/agent.py:11 (client.chat.completions.create) propagation notes/agent.py:15 (json.loads) propagation notes/storage.py:6 (body) sink notes/storage.py:9Accounting: 11 recorded rule hits; 10 non-case observations; 0 suppressed rule hits; 0 failed checksExceptions: 0 expired suppression entries; changes since the base unknown (no base run with its exceptions)Coverage · source patterns: scanned 3 files; 1598/1598 requested rules; 0 skipped; 3 excludedCoverage · dataflow: executed; see the recorded cross-file analysis scopeCoverage · known-fix matching: executed; see recorded known-fix scope Limitation: Semgrep-compatible SUBSET: no join, no metavariable-pattern/comparison, no cross-file or type inference, no language equivalences/constant propagation; taint is an approximation. Limitation: Structural matching uses the bundled language grammars, including Ruby. Unsupported rule/language combinations are listed in coverage; generic text also supports regex rules. Limitation: Parity is only claimed where proven by differential tests against native Semgrep CE (results: https://keryn.dev/evals/semgrep-ce/). Limitation: Deliberate divergence: each language is matched with its own grammar. Semgrep CE reuses the JavaScript parse of a pattern for every language of a rule that lists javascript, so its Python side never matches keyword arguments, dict literals or eval/require there (reported as a rule warning). Limitation: Maintainer/install-hook transition not checked without --base evidence; a lockfile alone does not record authenticated maintainer history.Exit code: 0counts: 11 rule matches · 11 findings · 9 excluding AI-BOM inventory · 0 blocking before answersrules: 1,598 rules available · 1,598 supported · 728 applied to the 3 scanned fileswarnings: 1 confirmed warning · 0 unconfirmed (pattern match only)pattern findings: 1 confirmed by cross-file analysis--include limits the scan to the sample (the repository this page runs in has other files; they are counted as excluded by globs). The gate passed (exit 0): everything here is a warning, and the default gate fails on errors. A chain does not have to fail the build to be worth reading. Run keryn scan . --include 'notes/**' --fail-on warning to see the gate you would get if you wanted writes like this one to stop a merge.
3. Read it hop by hop
Section titled “3. Read it hop by hop”Take the case, reported once at its sink in notes/storage.py:
- source,
notes/agent.py:11: the model call. What comes back is text that someone can influence through the conversation. This is where untrusted data enters. - propagation,
notes/agent.py:15:json.loads(...)turns the reply into a dictionary. The data is still the model’s. - propagation,
notes/storage.py:6: the value arrives insave_noteasbody. This hop is the import boundary: the flow left one file and entered another. It is why the finding is proof 3path-cross-file and not proof 2path-in-file. - sink,
notes/storage.py:9:target.write_text(body), the call that changes the file system.
The same flow is reported at each end: the first finding at the call that produces the text (agent.py:11), the third at the call that consumes it. They are one path, listed so that you find it from whichever file you are reading. The second finding is a different sink on the same path, the path join on line 8; section 4 comes back to it.
4. Say what is proven, and what is not
Section titled “4. Say what is proven, and what is not”Keryn proved that a value derived from the model call reaches a file write one import away. Three things it did not prove, and that you must supply:
- That the filename stays under the directory. The
nameis model-supplied too (note["name"]) and joined toROOT. Of the case’s contributing rules,keryn.gaps.joined-path-written-unconfinedis the one that speaks about the path:
keryn explain keryn.gaps.joined-path-written-unconfined | sed -n 3,12pA file path is built by joining a base directory with a value and then written, with no check that the result stays under the base, so a value such as `../../.ssh/authorized_keys` writes outside the directory. Resolve the joined path and refuse it unless it starts with the base.
Severity WARNINGConfidence P2FP risk mediumKind vulnEdge writesLanguages pythonTechnology pythonOWASP LLM LLM06 Excessive AgencyThe rule itself is a pattern with medium false-positive risk. Here Deep, the cross-file data-flow pass, confirmed it: the model’s reply reaches the join on line 8 through the same import, so the finding is proof 3path-cross-file with its own trace. (The hop at storage.py:6 is labelled with the function’s parameter body; the trace is per function input, and both arguments come from the same reply.) What Deep does not show is a missing check: the trace proves the value arrives, and only reading save_note tells you that nothing confines it.
- That nothing guards the path elsewhere. A trace shows the hops it found. A check in a middleware Keryn does not follow would not appear in it. Absence of a guard in the trace is a reason to look, not a verdict.
- That the code runs. Static analysis reads references. It does not know this function is called in production.
So this is a chain from a model to a write, at proof 3, and a model-controlled path join on the same chain, also at proof 3, whose missing confinement you confirm by reading one function. That is a precise statement, and it is enough to open the file and decide.
5. The same chain for a script
Section titled “5. The same chain for a script”--json keeps the trace as data, one entry per hop. The sink is the finding’s own location.
keryn scan . --include 'notes/**' --json keryn-out/result.json --quietjq -c '.findings[] | select(.trace) | {ruleId, at: "\(.path):\(.line)", proof: .proof.level, hops: [.trace[] | "\(.kind) \(.path):\(.line)"]}' keryn-out/result.json{"ruleId":"seceng/file_write_path","at":"notes/storage.py:9","proof":3,"hops":["source notes/agent.py:11","propagation notes/agent.py:15","propagation notes/storage.py:6"]}In SARIF the same hops are a codeFlows entry, which code-scanning UIs draw as a path. In Keryn Web each finding shows its proof level and the code around it. When you want the chain drawn with the other edges around it, with boundaries and chokepoints, model it on the Trust Canvas.
What you just proved
Section titled “What you just proved”You followed one edge, from a model to a file write, across a file boundary, and stated its confidence on three levels: the flow is proven (rung 3), the model-controlled path join is proven reachable (rung 3, through Deep), and the missing guard is what you confirm in the code. That is how to read any chain: the trace is what Keryn knows, the rung is how well it knows it, and the gaps are the questions you carry to the code.
- Break a chain and show the finding gone: the AppSec journey.
- Gate on it: CI with
--fail-on, and--gate-confidence P2to count P2 rules. - Record a decision about it: suppressions.