Integrator: SARIF, CycloneDX, LSP and connectors into your stack
Goal. Connect Keryn to the systems you already run. Take each output the way the consuming system will, check it with a tool that is not Keryn, and find out which parts are stable enough to build on.
Time. 40 minutes. You are a platform or tools engineer wiring a scanner into code scanning, an inventory, a tracker and editors.
You need. The Keryn CLI (install), git, jq and Node 22 or later. The first six steps run offline.
1. A repository to integrate
Section titled “1. A repository to integrate”A support-ticket router. The model picks a queue and the code runs a notification command with the model’s word in it. Written for this page.
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])SYSTEM = open("prompts/system.txt").read()
def route(ticket: str) -> str: """Pick the queue for a support ticket and run its hook.""" reply = client.messages.create( model="claude-sonnet-4-5", max_tokens=50, system=SYSTEM, messages=[{"role": "user", "content": ticket}], ) queue = reply.content[0].text.strip() os.system("notify-queue " + queue) return queueYou route support tickets to one queue: billing, outage or other. Answer with the queue name only.anthropic==0.40.0A configuration that runs every rule pack (the language server reads it too, in step 6) and keeps Keryn’s output directory out of the scan:
apiVersion: keryn.dev/config/v1rules: - bundled:allexclude: - keryn-out - lsp-probe.mjsgit add -Agit commit -q -m "ticket router"2. SARIF for code scanning
Section titled “2. SARIF for code scanning”One run writes every output. The SARIF file is what GitHub code scanning, Azure’s SARIF viewer and most IDE viewers read.
keryn scan . --sarif keryn-out/keryn.sarif --aibom keryn-out/bom.cdx.json --json keryn-out/result.json --verboseKeryn — 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 443aff354d578ea6fcad59903a6afc921b71819bComparison: 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] Model output reaches os.system/os.popen/os.exec*/os.spawn*. These run through a shell or replace the process, so a prompt-injected response becomes command execution; replace with subprocess and a fixed argv plus an allow-list. router/app.py:18 · path-in-file · 7 contributing rule(s) · sha256:366331a2a21410a29a1838bbdfd10eea4fd3b674d84c730503773725007b2ef1 Within-file flow [proof 2]Accounting: 9 recorded rule hits; 8 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 4 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: 9 rule matches · 9 findings · 6 excluding AI-BOM inventory · 1 blocking before answersrules: 1,598 rules available · 1,598 supported · 756 applied to the 4 scanned fileserrors: 1 confirmed error · 0 unconfirmed (pattern match only)pattern findings: 3 confirmed by cross-file analysiswrote CycloneDX 1.6 AI-BOM -> keryn-out/bom.cdx.jsonwrote SARIF -> keryn-out/keryn.sarifwrote Keryn JSON -> keryn-out/result.jsonCheck the file with a tool that is not Keryn. The version, the driver and the counts are the first things a consumer reads:
jq '{version, tool: .runs[0].tool.driver.name, rules: (.runs[0].tool.driver.rules | length), results: (.runs[0].results | length)}' keryn-out/keryn.sarif{ "version": "2.1.0", "tool": "keryn-scout", "rules": 14, "results": 15}Now one result, the way an upload action sees it:
jq -c '.runs[0].results[] | select(.ruleId == "python.code-execution.llm-output-to-os-system") | {ruleId, level, file: .locations[0].physicalLocation.artifactLocation.uri, line: .locations[0].physicalLocation.region.startLine, proof: [.properties.proofLevel, .properties.proofRung], fingerprint_keys: (.partialFingerprints | keys)}' keryn-out/keryn.sarif{"ruleId":"python.code-execution.llm-output-to-os-system","level":"error","file":"router/app.py","line":18,"proof":[2,null],"fingerprint_keys":["keryn/fingerprint/v1"]}Three properties are the ones to build on. level is the severity (error, warning, note). properties.proofLevel carries the proof rung as a number, so a dashboard can show proof 2path-in-file findings apart from pattern matches. partialFingerprints is a stable identity for the finding, which is what code scanning uses to track an alert over time. Upload with github/codeql-action/upload-sarif; the CI journey has the job. Formats shows full sample files.
3. CycloneDX for an inventory
Section titled “3. CycloneDX for an inventory”The AI-BOM is a CycloneDX 1.6 document. Models, libraries and prompt files appear as components with their own types.
jq -c '{bomFormat, specVersion, components: [.components[] | {type, name}]}' keryn-out/bom.cdx.json{"bomFormat":"CycloneDX","specVersion":"1.6","components":[{"type":"data","name":"prompts/system.txt"},{"type":"library","name":"anthropic"},{"type":"machine-learning-model","name":"claude-sonnet-4-5"}]}The model is a machine-learning-model component, the SDK a library, and the system prompt a data component. Any tool that reads CycloneDX 1.6 can take the file. For Dependency-Track:
curl -sS -X POST "$DT_URL/api/v1/bom" -H "X-Api-Key: $DT_KEY" \ -F "autoCreate=true" -F "projectName=ticket-router" -F "projectVersion=main" -F "bom=@keryn-out/bom.cdx.json"The inventory reflects static references. It says what the code names, not what runs in production.
4. The result file for a tracker
Section titled “4. The result file for a tracker”SARIF is for scanners’ consumers. When you need your own logic, such as opening a ticket for a new error and closing it when the finding is gone, read keryn.dev/result/v1. It has the same findings, with the proof level, a fingerprint, and whether the finding gates. Here is a small integrator in Node that compares two results by fingerprint:
// usage: node tickets.mjs <before.json> <after.json>// Prints which gating findings need a ticket and which tickets can close. Matching is by fingerprint.import fs from 'node:fs';
const gating = (file) => new Map(JSON.parse(fs.readFileSync(file, 'utf8')).findings .filter((f) => f.severity === 'ERROR' && f.proof.level >= 1) .map((f) => [f.fingerprint, f]));
const [before, after] = process.argv.slice(2).map(gating);const line = (f) => `${f.ruleId} ${f.path}:${f.line} proof ${f.proof.level}`;for (const [fp, f] of after) if (!before.has(fp)) console.log(`open ${line(f)}`);for (const [fp, f] of before) if (!after.has(fp)) console.log(`close ${line(f)}`);console.log(`${after.size} gating finding(s) now, ${before.size} before`);Make the change a pull request would make, replacing the shell call with a check against a fixed set of queues, and scan it:
git switch -q -c fix-queueimport loggingimport os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])SYSTEM = open("prompts/system.txt").read()QUEUES = {"billing", "outage", "other"}
def route(ticket: str) -> str: """Pick the queue for a support ticket.""" reply = client.messages.create( model="claude-sonnet-4-5", max_tokens=50, system=SYSTEM, messages=[{"role": "user", "content": ticket}], ) queue = reply.content[0].text.strip() if queue not in QUEUES: queue = "other" logging.info("routed to %s", queue) return queuemv keryn-out/result.json keryn-out/before.jsonkeryn scan . --json keryn-out/after.json -qnode tickets.mjs keryn-out/before.json keryn-out/after.jsonclose seceng.llm05.taint.model-output-to-os-command-python router/app.py:18 proof 20 gating finding(s) now, 1 beforeRead in the other direction, the same two files say which tickets to open. The fingerprint is the identity a tracker should key on. A finding keeps it while its rule, file and code stay the same, so an unrelated edit elsewhere does not reopen it.
node tickets.mjs keryn-out/after.json keryn-out/before.jsonopen seceng.llm05.taint.model-output-to-os-command-python router/app.py:18 proof 21 gating finding(s) now, 0 before5. A foreign report into the same gate
Section titled “5. A foreign report into the same gate”A team that already runs another scanner does not need a second gate. keryn import reads a third-party report locally, in one of 97 formats, and gates, writes and annotates it like a scan. Here is a Semgrep report written for this page:
{ "version": "1.99.0", "results": [ { "check_id": "acme.hardcoded-queue-name", "path": "router/app.py", "start": {"line": 18, "col": 5, "offset": 0}, "end": {"line": 18, "col": 45, "offset": 0}, "extra": {"message": "The queue name is concatenated into a shell command.", "severity": "ERROR", "metadata": {"cwe": ["CWE-78: OS Command Injection"]}, "lines": "os.system(\"notify-queue \" + queue)"} } ], "errors": [], "paths": {"scanned": ["router/app.py"]}}keryn import semgrep-report.json --parser semgrep --sarif keryn-out/imported.sarifimported 1 findings from semgrep (Semgrep JSON Report) · 1 observations · <n> ms also claimed by: api_sonarqube, apkleaks, bandit, checkmarx, checkmarx_one, checkov, crunch42, kubelinter, mozilla_observatory, promptfoo, sonarqube, terrascan (pass --parser to use one of them)wrote SARIF -> keryn-out/imported.sarifcoverage: 1 observations imported from semgrep (Semgrep JSON Report); 1 report file read; no rules executed.result: FAIL (exit 1) - 1 violation(s)/finding(s) at or above 'error'Name the parser when you know it. Without --parser the format is detected from the bytes and has to be unambiguous, and several formats claim a Semgrep-shaped file. The import runs no rules and makes no AI-BOM. It gives the same exit codes, outputs and annotations, so one pipeline step can gate on both.
6. The language server for editors
Section titled “6. The language server for editors”keryn lsp --stdio speaks the Language Server Protocol, with diagnostics that carry the rule id as code, severity and, for a finding with a flow, every hop as relatedInformation. The protocol lists the capabilities. This script plays an editor: it starts the server, waits for the first scan and prints the errors it would show in the Problems panel.
// Starts `keryn lsp --stdio`, opens the workspace, waits for the first scan and prints the errors an editor would show.import { spawn } from 'node:child_process';import { pathToFileURL } from 'node:url';
const root = pathToFileURL(process.cwd()).href;const server = spawn('keryn', ['lsp', '--stdio'], { stdio: ['pipe', 'pipe', 'inherit'] });let buf = Buffer.alloc(0);const send = (msg) => { const body = JSON.stringify({ jsonrpc: '2.0', ...msg }); server.stdin.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`); };const diagnostics = new Map();
server.stdout.on('data', (chunk) => { buf = Buffer.concat([buf, chunk]); for (;;) { const end = buf.indexOf('\r\n\r\n'); if (end < 0) return; const len = Number(/Content-Length: (\d+)/i.exec(buf.subarray(0, end).toString())[1]); if (buf.length < end + 4 + len) return; const msg = JSON.parse(buf.subarray(end + 4, end + 4 + len).toString()); buf = buf.subarray(end + 4 + len); if (msg.id === 1) send({ method: 'initialized', params: {} }); if (msg.method === 'textDocument/publishDiagnostics') diagnostics.set(msg.params.uri, msg.params.diagnostics); if (msg.method === 'keryn/scanFinished') finish(); }});
function finish() { for (const [uri, list] of [...diagnostics].sort()) { for (const d of list.filter((x) => x.severity === 1)) { console.log(`${uri.replace(root + '/', '')}:${d.range.start.line + 1} ${d.code}`); for (const r of d.relatedInformation ?? []) console.log(` ${r.message}`); } } send({ id: 2, method: 'shutdown' }); setTimeout(() => send({ method: 'exit' }), 200);}server.on('exit', (code) => process.exit(code === 0 ? 0 : 1));send({ id: 1, method: 'initialize', params: { processId: process.pid, rootUri: root, capabilities: {} } });setTimeout(() => { console.error('no scan result after 60 s'); server.kill(); }, 60000);git stash -qnode lsp-probe.mjsgit stash pop -qrouter/app.py:18 seceng.llm05.taint.model-output-to-os-command-python taint sourceThe two lines are the two error diagnostics on the shell call, run on the version of the file from main. The taint source entry is the first hop of the flow. Nothing was sent anywhere: the server is a local process and the protocol uses its stdin and stdout.
7. Connectors for a second opinion and a place to put results
Section titled “7. Connectors for a second opinion and a place to put results”Everything above is deterministic: the same input gives the same bytes. A model is not, and Keryn keeps it on the far side of a button. A connector is a place Keryn may send something when you press Triage or Send: a model that reviews findings, or a store that receives them. Connectors are set up in Keryn Web, under Settings, then Connectors.


Choose a model, such as a local Ollama, which needs no key and keeps the traffic on your machine. After a scan, Triage names the model, the host and the number of findings and waits for you to confirm:


The CLI has no connectors. It writes files, and a connector is a button in the page that sends a file somewhere you named. To take the result into a graph database without the page, export the graph as Cypher from Send, or read result.json as in step 4.
A verdict comes back for each finding: upheld, refuted, needs context, unsupported or declined. It is recorded next to the finding. It never changes its proof rung, severity or the gate, so a pipeline that reads result.json sees the same exit code with or without triage. The bounds are on agentic triage, and every model and data connector, with its endpoint, key and what leaves the machine, is on the connector reference.
What you just proved
Section titled “What you just proved”- Each output is a contract you can test. SARIF carries level, proof and a stable fingerprint. CycloneDX carries the inventory by type. The result file carries both, for your own logic.
- Identity survives edits. A tracker keyed on fingerprint opens and closes tickets from two results, as step 4 did in both directions.
- One gate for several scanners, by importing a foreign report with the same exit codes and outputs.
- Editors see the same rule ids and flows as the CLI, from a local process.
- Where the trust boundary is. Everything before the connector runs on your machine, deterministically. The connector is the one edge that leaves it, and it is a button.
What this does not do: it does not tell you that a SARIF alert is a vulnerability, that an inventory is complete, or that a model’s verdict is right. Those are the consumer’s judgement, and each output says how much evidence stands behind it.
- Gate pull requests with these outputs: Platform and CI.
- Every flag and exit code: the CLI reference.
- Read an attack path before you ticket it: paths, chains and chokepoints.