Quickstart
1. Scan a repository
Section titled “1. Scan a repository”Open 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.
cd your-repokeryn 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:
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 themAnalysis: complete · Dependency advisories: not checked (offline) · Policy: blocked · 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 [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:3e1d08bdf85a155a6b8f82814b37b6fc8a84657781efac57fd6ccd58b2481d16Accounting: 22 recorded rule hits; 21 non-case observations; 0 suppressed rule hits; 1 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; 0 excludedCoverage · dataflow: executed; see the recorded cross-file analysis scopeCoverage · 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: 1counts: 22 rule matches · 22 findings · 17 excluding AI-BOM inventory · 1 blocking before answersrules: 1,598 rules available · 1,598 supported · 728 applied to the 3 scanned fileserrors: 1 confirmed error · 0 unconfirmed (pattern match only)pattern findings: 3 confirmed by cross-file analysisThe 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.
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.
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}2 findings · 29 of 29 rules ran on 1 file
- info
keryn.inv.lib.openailine 3proof 0 inventoryReferences the OpenAI SDK.
Edge depends_on
from openai import OpenAI - info
keryn.inv.model.openailine 13proof 0 inventoryHard-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
Result computed when this page was built. Run an example with the CLI
2. Write the outputs you need
Section titled “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:
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 shows real sample files.
3. Add a policy
Section titled “3. Add a policy”keryn init # writes .keryn.yml and .keryn/policy.ymlkeryn policy lint .keryn/policy.ymlkeryn scan . # now gates on the policy tooinit 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 explains the format and the templates.
4. Gate pull requests
Section titled “4. Gate pull requests”keryn scan . --base origin/main --fail-on-addedThis 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.