# AppSec engineer

> Ten minutes in your browser: scan a small AI agent, read why the release is held, follow the flow from the user's prompt to a shell, and take SARIF home.

Source: https://keryn.dev/docs/start/appsec-engineer/

**You get:** a release decision with its evidence, a cross-file flow you can follow step by step, and a SARIF file for your code-scanning tool. **You need:** a current browser. Nothing is installed and no account is needed; the scan runs in your tab.

## 1. Scan the sample (2 minutes)

1. Download [helpdesk.zip](https://keryn.dev/samples/helpdesk.zip), a 1 KB help-desk agent that asks Claude for a shell command and runs it. Its code is [shown below](#the-samples-code).
2. Open [keryn.app](https://keryn.app). Under **Scan**, choose **File** and drop the zip on the box.

The scan runs in the tab: local files are never uploaded. When it finishes, Keryn Web opens the release decision.

## 2. Read the decision (2 minutes)

![The release decision of Keryn Web for helpdesk.zip: Policy blocked (Hold), the gate and policy, two Holds with their cross-file flows into a shell, and the coverage line.](https://keryn.dev/screens/role-appsec-decision-1280-light.webp)

*The release decision for helpdesk.zip: Policy blocked (Hold), with two Holds, each a cross-file flow into a shell. Taken from keryn.app main-5g3Rr4q1.js.*

The default gate fails on errors that Keryn has evidence for. Two hold the release:

- **seceng/shell_exec**: the user's prompt reaches the agent in `helpdesk/agent.py`, and from there a shell.
- **python-model-output-to-system-shell**: the model's answer reaches `subprocess` in `helpdesk/tools.py:7`.

**Cross-file flow** is the evidence level: Keryn traced the data across files, not just matched a pattern. The coverage line says all 1,592 rules ran on the 3 files.

## 3. Follow the flow (3 minutes)

Open **Findings**. There are 10: 2 errors, 3 warnings and 5 info. Choose **Cross-file flow or stronger** to keep the two that matter, and open **How the data gets here** on the first one:

![The first finding of helpdesk.zip with How the data gets here open: four steps from the model call in agent.py to the shell in tools.py.](https://keryn.dev/screens/role-appsec-trace-1280-light.webp)

*The four steps from the model call in agent.py to the shell in tools.py. Taken from keryn.app main-5g3Rr4q1.js.*

1. **source** `helpdesk/agent.py:13`: the model's reply comes back from `client.messages.create`.
2. **propagation** `helpdesk/agent.py:19`: it becomes `command`.
3. **propagation** `helpdesk/tools.py:5`: it is passed to the tool.
4. **sink** `helpdesk/tools.py:7`: it runs with `shell=True`.

**Open evidence** shows the lines themselves. The fix is not in the sink alone: the model should never choose the command.

## 4. Take the results home (2 minutes)

Choose **Share and export**. Under **Download (generated in this tab)**, take **SARIF 2.1.0** for GitHub code scanning or any SARIF viewer, or **Result JSON** for your own tools. **Record decision** on a Hold writes `.keryn/decisions.yml` for your repository; nothing is pushed from the page.

## 5. Scan your own code

Under **Scan**, choose **Repo** and type `owner/repo` (public repositories need nothing; a private one needs a read-only connection in **Settings**), or **Folder** for a checkout on your disk.

## The sample's code

These are the files in `helpdesk.zip`, from the [AppSec journey](https://keryn.dev/docs/journeys/appsec/), which takes the same agent through a fix.

```python
import subprocess
import urllib.request

def run_command(command: str) -> str:
    """Run a shell command for the agent and return what it printed."""
    done = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=30)
    return done.stdout

def fetch_page(url: str) -> str:
    """Download a page so the agent can read it."""
    with urllib.request.urlopen(url, timeout=10) as resp:
        return resp.read().decode("utf-8", "replace")
```

```python
import os

from anthropic import Anthropic

from helpdesk.tools import run_command

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

SYSTEM = "You are a help desk agent. Reply with one shell command that diagnoses the ticket."

def handle_ticket(ticket_text: str) -> str:
    reply = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=200,
        system=SYSTEM,
        messages=[{"role": "user", "content": ticket_text}],
    )
    command = reply.content[0].text
    return run_command(command)
```

```text
anthropic==0.40.0
```

## With the CLI (pre-release builds)

The CLI is in pre-release for [design partners](https://keryn.dev/partners/design-partner/). With it, the same scan gates a pull request; these commands run against the sample in this page's tests:

```sh
keryn scan . --sarif keryn.sarif -q
```

```sh
jq -r '.runs[0].results[] | select(.level == "error") | "\(.ruleId) \(.locations[0].physicalLocation.artifactLocation.uri):\(.locations[0].physicalLocation.region.startLine)"' keryn.sarif | sort
```

```text
seceng.llm04.python-model-output-to-system-shell helpdesk/tools.py:7
seceng/shell_exec helpdesk/tools.py:7
```

Exit 1 is the gate: the job fails until the Holds are fixed or answered. The [CI journey](https://keryn.dev/docs/journeys/ci/) wires this into GitHub Actions, GitLab and the rest.

## Next

- [How evidence levels work](https://keryn.dev/docs/concepts/proof-ladder/), and [what Keryn does not do](https://keryn.dev/docs/concepts/limits/).
- [The AppSec journey](https://keryn.dev/docs/journeys/appsec/): fix the flow, rescan, and record the decision.
