# Quickstart

> Your first scan, AI-BOM and policy gate in five minutes.

Source: https://keryn.dev/docs/start/quickstart/

> **Tip: Start in your browser**
> [Keryn Web](https://keryn.app) runs in your browser. To follow the CLI and CI steps, use a privately staged CLI package and check [Install](https://keryn.dev/docs/start/install/) for member download availability. See the [editor guide](https://keryn.dev/docs/guides/editors/) for VS Code setup.

## 1. Scan a repository

**CLI**

```sh
cd your-repo
keryn scan .
```

The console leads with the completed verdict, then analysis, policy and approval states, case accounting, component changes and coverage by capability. In the sample repository used for this page there are findings at the `error` level, so the gate fails:

```text
Keryn — Policy blocked (Hold); dependency advisories not checked (offline)
  1 violation(s)/finding(s) at or above 'error'
  dependency advisories not checked (offline): 1 lockfile(s); keryn scan --online checks them
Analysis: complete · Dependency advisories: not checked (offline) · Policy: blocked · 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
  [blocking; unclassified] Text returned by a language model is passed to subprocess with shell=True (or as the program to run). A prompt injection becomes OS command injection with the privileges of this process. Do not let the model compose shell commands. Expose a small set of fixed commands as tools, pass model-chosen values as separate list arguments without shell=True, validate them against an allowlist, and run with least privilege and a timeout.
    agent.py:9 · path-in-file · 7 contributing rule(s) · sha256:3e1d08bdf85a155a6b8f82814b37b6fc8a84657781efac57fd6ccd58b2481d16
Accounting: 22 recorded rule hits; 21 non-case observations; 0 suppressed rule hits; 1 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; 0 excluded
Coverage · dataflow: executed; see the recorded cross-file analysis scope
Coverage · dependency advisories: not checked (offline); 1 lockfile(s) (keryn scan --online checks them, sending package names and versions only)
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: 1 package licence unknown: their lockfiles record none. keryn scan --online looks them up on deps.dev, sending package names and versions only.
  Limitation: 1 lockfile not checked against vulnerability advisories (offline). keryn scan --online checks them, sending package names and versions only.
  Limitation: Maintainer/install-hook transition not checked without --base evidence; a lockfile alone does not record authenticated maintainer history.
  Limitation: 1 npm or PyPI package checked against the shipped malicious-package table (OSV MAL records) and the popularity list; additional ecosystem signals depend on the available data and package contents.
  Limitation: Malicious-package data: PyPI; source date <time>; shipped. Published MAL records are not proof that unlisted packages are safe.
Exit code: 1
counts: 22 rule matches · 22 findings · 17 excluding AI-BOM inventory · 1 blocking before answers
rules: 1,598 rules available · 1,598 supported · 728 applied to the 3 scanned files
errors: 1 confirmed error · 0 unconfirmed (pattern match only)
pattern findings: 3 confirmed by cross-file analysis
```

The findings, each with its proof level, are in the outputs of step 2. The exit code is the gate: `0` pass, `1` findings at or above `--fail-on` (default `error`), `3` incomplete coverage. See [exit codes](https://keryn.dev/docs/reference/cli/#exit-codes).

**Web**

Open [keryn.app](https://keryn.app), drop a folder, paste a public GitHub URL or pick an example from the Demo menu. The scan runs inside your browser tab. A folder is read in the browser and never uploaded; a repository is read from its host, or through api.keryn.app without storage if you choose the fast archive.

The recorded AI-BOM scan below shows a Flask endpoint that calls a hosted model. The result lists the library and model references with their line numbers. Save the example as a Python file in its own folder and use the AI-BOM command in step 2 to scan that folder.

**Scan a small file** (a live example on the page; the engine runs in the browser, nothing is uploaded)

```python
import os
from flask import Flask, request
from openai import OpenAI

app = Flask(__name__)
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

@app.post("/summarize")
def summarize():
    text = request.json["text"]
    reply = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Summarize: " + text}],
    )
    return {"summary": reply.choices[0].message.content}
```

Result, computed when the site was built by the same engine as `keryn scan`:

```text
2 findings · 29 of 29 rules ran on 1 file

info keryn.inv.lib.openai line 3 [proof 0 inventory]
  References the OpenAI SDK.
  Edge: depends_on
  | from openai import OpenAI

info keryn.inv.model.openai line 13 [proof 0 inventory]
  Hard-coded OpenAI model identifier.
  Edge: depends_on
  | model="gpt-4o-mini",

AI-BOM delta: 2 new components vs an empty baseline
  + library openai (openai) · line 3
  + model gpt-4o-mini (openai) · line 13

Agent reach: POST /summarize

Example policy: pass
```

## 2. Write the outputs you need

One run can write several outputs. Keryn recognises its own earlier outputs (by content) and leaves them out of the next scan, and it skips what `.gitignore` lists; coverage reports the checked and excluded scope. A folder such as `keryn-out/` keeps them together:

```sh
keryn scan . --aibom keryn-out/bom.cdx.json --sarif keryn-out/keryn.sarif --json keryn-out/result.json --markdown keryn-out/summary.md
```

| Output | Format | Use it for |
|---|---|---|
| `--aibom` | CycloneDX 1.6 | inventory, Dependency-Track, audits |
| `--sarif` | SARIF 2.1.0 | GitHub code scanning, IDE SARIF viewers |
| `--json` | Keryn result | scripts, evidence bundles |
| `--markdown` | Markdown | a pull or merge request comment |
| `--junit`, `--gitlab-sast`, `--codequality` | JUnit, GitLab | CI test tabs and merge request widgets |

[Formats](https://keryn.dev/docs/reference/formats/) shows real sample files.

## 3. Add a policy

```sh
keryn init                  # writes .keryn.yml and .keryn/policy.yml
keryn policy lint .keryn/policy.yml
keryn scan .                # now gates on the policy too
```

`init` sets `rules: bundled:all`, the same rules `keryn scan` uses with no config (vulnerability, audit and AI-BOM inventory), and prints what is included; narrow it to `bundled:aibom` for the inventory only. Edit `.keryn/policy.yml` to list your approved model providers. [Policies](https://keryn.dev/docs/guides/policies/) explains the format and the templates.

## 4. Gate pull requests

```sh
keryn scan . --base origin/main --fail-on-added
```

This compares against the base branch: new components and new findings are marked, and `--fail-on-added` fails when a change adds an AI component. Wire it into your pipeline with [CI](https://keryn.dev/docs/guides/ci/).
