Skip to content

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

    Read an attack chain

    View as Markdown

    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.

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

    notes/storage.py
    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)
    notes/agent.py
    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/__init__.py
    """Notes agent."""
    Terminal window
    keryn scan . --include 'notes/**' --verbose
    Keryn — Checks passed (Go)
    Analysis: complete · Policy: checks passed · Approval: not recorded
    base not recorded → analyzed 69a8fd978be3df6646542bac4cd38507eae55067-dirty
    Comparison: not compared: no finding baseline supplied
    Cases: 1 current = 0 new + 0 existing + 1 unclassified; unknown cleared from previous assessment
    Newly 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:9
    Accounting: 11 recorded rule hits; 10 non-case observations; 0 suppressed rule hits; 0 failed checks
    Exceptions: 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 excluded
    Coverage · dataflow: executed; see the recorded cross-file analysis scope
    Coverage · 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: 0
    counts: 11 rule matches · 11 findings · 9 excluding AI-BOM inventory · 0 blocking before answers
    rules: 1,598 rules available · 1,598 supported · 728 applied to the 3 scanned files
    warnings: 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.

    Take the case, reported once at its sink in notes/storage.py:

    1. 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.
    2. propagation, notes/agent.py:15: json.loads(...) turns the reply into a dictionary. The data is still the model’s.
    3. propagation, notes/storage.py:6: the value arrives in save_note as body. 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.
    4. 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.

    model replynotes directorywritesmodel to code
    One edge, one boundary: a model's text is written to disk.

    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 name is model-supplied too (note["name"]) and joined to ROOT. Of the case’s contributing rules, keryn.gaps.joined-path-written-unconfined is the one that speaks about the path:
    Terminal window
    keryn explain keryn.gaps.joined-path-written-unconfined | sed -n 3,12p
    A 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 WARNING
    Confidence P2
    FP risk medium
    Kind vuln
    Edge writes
    Languages python
    Technology python
    OWASP LLM LLM06 Excessive Agency

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

    --json keeps the trace as data, one entry per hop. The sink is the finding’s own location.

    Terminal window
    keryn scan . --include 'notes/**' --json keryn-out/result.json --quiet
    jq -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.

    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 P2 to count P2 rules.
    • Record a decision about it: suppressions.