# Read an attack chain

> Follow a finding that crosses files from a model reply to a file write, say what each hop proves, and tell a chain from a lead.

Source: https://keryn.dev/docs/guides/attack-chain/

## Goal

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](https://keryn.dev/docs/journeys/appsec/) 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

- The Keryn CLI ([install](https://keryn.dev/docs/start/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](https://keryn.dev/docs/edges/paths-and-chains/) and the [proof ladder](https://keryn.dev/docs/concepts/proof-ladder/).

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

```python
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)
```

```python
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"])
```

```python
"""Notes agent."""
```

## 2. Scan it and ask for the flow

```sh
keryn scan . --include 'notes/**' --verbose
```

```text
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.

## 3. Read it hop by hop

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 3 path-cross-file` and not `proof 2 path-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.

Diagram: model reply writes notes directory, across a model to code. One edge, one boundary: a model's text is written to disk.

## 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 `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:

```sh
keryn explain keryn.gaps.joined-path-written-unconfined | sed -n 3,12p
```

```text
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 3 path-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

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

```sh
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
```

```text
{"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](https://keryn.dev/docs/guides/web-app/) 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](https://keryn.dev/docs/guides/trust-canvas/).

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

## Next

- Break a chain and show the finding gone: the [AppSec journey](https://keryn.dev/docs/journeys/appsec/).
- Gate on it: [CI](https://keryn.dev/docs/guides/ci/) with `--fail-on`, and `--gate-confidence P2` to count P2 rules.
- Record a decision about it: [suppressions](https://keryn.dev/docs/guides/suppressions/).
