# Integrator: SARIF, CycloneDX, LSP and connectors into your stack

> Read Keryn's outputs the way another system will: SARIF for code scanning, CycloneDX for an inventory, the result file for a tracker, a foreign report into the same gate, the language server for editors, and connectors for a second opinion.

Source: https://keryn.dev/docs/journeys/integrator/

**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](https://keryn.dev/docs/start/install/)), `git`, `jq` and Node 22 or later. The first six steps run offline.

> **Leaves your machine**
> **Nothing.** Steps 1 to 6 read and write files on your machine. Step 7 is the one place something can leave it, and only when you press a button.

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

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

```text
You route support tickets to one queue: billing, outage or other. Answer with the queue name only.
```

```text
anthropic==0.40.0
```

A 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:

```yaml
apiVersion: keryn.dev/config/v1
rules:
  - bundled:all
exclude:
  - keryn-out
  - lsp-probe.mjs
```

```sh
git add -A
git commit -q -m "ticket router"
```

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

```sh
keryn scan . --sarif keryn-out/keryn.sarif --aibom keryn-out/bom.cdx.json --json keryn-out/result.json --verbose
```

```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 443aff354d578ea6fcad59903a6afc921b71819b
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] 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 checks
Exceptions: 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 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: 9 rule matches · 9 findings · 6 excluding AI-BOM inventory · 1 blocking before answers
rules: 1,598 rules available · 1,598 supported · 756 applied to the 4 scanned files
errors: 1 confirmed error · 0 unconfirmed (pattern match only)
pattern findings: 3 confirmed by cross-file analysis
wrote CycloneDX 1.6 AI-BOM -> keryn-out/bom.cdx.json
wrote SARIF -> keryn-out/keryn.sarif
wrote Keryn JSON -> keryn-out/result.json
```

Check the file with a tool that is not Keryn. The version, the driver and the counts are the first things a consumer reads:

```sh
jq '{version, tool: .runs[0].tool.driver.name, rules: (.runs[0].tool.driver.rules | length), results: (.runs[0].results | length)}' keryn-out/keryn.sarif
```

```text
{
  "version": "2.1.0",
  "tool": "keryn-scout",
  "rules": 14,
  "results": 15
}
```

Now one result, the way an upload action sees it:

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

```text
{"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](https://keryn.dev/docs/concepts/proof-ladder/) as a number, so a dashboard can show `proof 2 path-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](https://keryn.dev/docs/journeys/ci/) has the job. [Formats](https://keryn.dev/docs/reference/formats/) shows full sample files.

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

```sh
jq -c '{bomFormat, specVersion, components: [.components[] | {type, name}]}' keryn-out/bom.cdx.json
```

```text
{"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:

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

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:

```js
// 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:

```sh
git switch -q -c fix-queue
```

```python
import logging
import 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 queue
```

```sh
mv keryn-out/result.json keryn-out/before.json
keryn scan . --json keryn-out/after.json -q
node tickets.mjs keryn-out/before.json keryn-out/after.json
```

```text
close  seceng.llm05.taint.model-output-to-os-command-python router/app.py:18 proof 2
0 gating finding(s) now, 1 before
```

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

```sh
node tickets.mjs keryn-out/after.json keryn-out/before.json
```

```text
open   seceng.llm05.taint.model-output-to-os-command-python router/app.py:18 proof 2
1 gating finding(s) now, 0 before
```

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

```json
{
  "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"]}
}
```

```sh
keryn import semgrep-report.json --parser semgrep --sarif keryn-out/imported.sarif
```

```text
imported 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.sarif
coverage: 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

`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](https://keryn.dev/docs/reference/lsp/) 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.

```js
// 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);
```

```sh
git stash -q
node lsp-probe.mjs
git stash pop -q
```

```text
router/app.py:18 seceng.llm05.taint.model-output-to-os-command-python
    taint source
```

The 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

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.

**Web**

![The Connectors tab of Keryn Web settings: models, data stores and issue trackers Keryn may send findings to, each with its own settings; nothing is sent until you press Test or Send.](https://keryn.dev/screens/web-connectors-1280-light.webp)

*Settings, Connectors in Keryn Web. Taken from keryn.app main-DIcUUbkq.js.*

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 Investigate with AI panel of Keryn Web with no model configured: a recorded example review of a pinned public repository, labelled as recorded with no live model run and nothing sent, and a Configure a model button.](https://keryn.dev/screens/web-triage-1280-light.webp)

*Investigate with AI before a model is configured: recorded example reviews, labelled as such, and Configure a model. Nothing is sent.. Taken from keryn.app main-DIcUUbkq.js.*

**CLI**

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.

> **Leaves your machine, only when you press Start triage and confirm the panel:** A model you chose reviews the findings. Each request goes only to the one origin you entered.
>
> - Per finding: id, rule, title, severity, file, line, engine, proof, confidence, taxonomy, untrusted.
> - Unless you untick it, a window of code around the finding with credential-like text masked first.
> - Your key, to the same host.

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](https://keryn.dev/docs/edges/agentic-triage/), and every model and data connector, with its endpoint, key and what leaves the machine, is on the [connector reference](https://keryn.dev/docs/reference/connectors/).

Diagram: findings sends your model, across a you press Triage. The only edge in this page that leaves your machine, and a person starts it.

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

## Next

- Gate pull requests with these outputs: [Platform and CI](https://keryn.dev/docs/journeys/ci/).
- Every flag and exit code: [the CLI reference](https://keryn.dev/docs/reference/cli/).
- Read an attack path before you ticket it: [paths, chains and chokepoints](https://keryn.dev/docs/edges/paths-and-chains/).
