Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Language server protocol

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    Audience: authors of editor plugins (JetBrains, Zed, Neovim, Helix, Sublime, anything with an LSP client).

    keryn lsp --stdio
    • Transport: stdio, standard LSP framing (Content-Length: N\r\n\r\n + UTF-8 JSON-RPC 2.0). stdout carries only framed messages; stderr is silent in normal operation, except one line at start-up when the installation has no Deep engine (keryn lsp: Deep unavailable (<reason>); Keryn pattern rules only).
    • No network access, ever. No telemetry.
    • Requires Node.js 22 or later for the npm package; the single binary and the container need nothing else.
    • Exit code: 0 after shutdown + exit (or stdin EOF), 1 for exit without shutdown or a framing error, 2 for bad arguments.
    • Languages to attach to: none are required. The server analyses the whole workspace (Python, TypeScript/JavaScript, Java, C#, Rust, PHP, Go, Kotlin, Swift, Ruby, C, C++, Scala, Solidity, OCaml, Bash sources, Dockerfiles, JSON/YAML configuration, Terraform, package.json, requirements*.txt, etc.), so register it for every file type you want diagnostics in, or attach it per project root without a file-type filter.

    Standard initialize / initialized / shutdown / exit. The workspace root is workspaceFolders[0].uri, else rootUri, else rootPath; one root per server process (start one server per project). Requests before initialize fail with -32002.

    initialize result:

    {
    "capabilities": {
    "positionEncoding": "utf-16",
    "textDocumentSync": {"openClose": true, "change": 1, "save": {"includeText": false}},
    "executeCommandProvider": {"commands": ["keryn.scan", "keryn.aibom"]},
    "codeActionProvider": {"codeActionKinds": ["quickfix"]},
    "experimental": {"keryn": {"protocol": 1, "requests": ["keryn/aibom", "keryn/sarif", "keryn/bundle", "keryn/scan"], "notifications": ["keryn/scanFinished"]}}
    },
    "serverInfo": {"name": "keryn", "version": "0.0.1 (keryn-scout-engine/0.1.0 ...)"}
    }

    initializationOptions (all optional):

    Option Default Meaning
    diagnostics "workspace" "workspace": publish diagnostics for every file with a hit. "open": only for open documents.
    scanOnStart true Scan once after initialized.
    debounceMs 400 Delay after didChange/watched-file events before rescanning.
    deltaBase "" Base every automatic scan diffs against (VS Code keryn.delta.base): "" = none, "merge-base", a git ref or a CycloneDX .json path. Order: the request’s base, then deltaBase, then .keryn.yml base. Changed later with workspace/didChangeConfiguration {"settings": {"keryn": {"deltaBase": "..."}}}.
    deep true Run Deep (the Rust engine compiled to WASM) after Keryn pattern analysis on every scan, when the server has it; see “Deep” below. Changed later with workspace/didChangeConfiguration {"settings": {"keryn": {"deep": false}}}.
    symlinks "skip" Reserved; symlinks are skipped (never followed outside the root).

    Text sync is full (change: 1): send the whole document in contentChanges[0].text. Positions are UTF-16 code units (the only encoding offered).

    Source: textDocument/publishDiagnostics, pushed per file URI after every scan; superseded scans are discarded, and files that stop having hits receive an empty array.

    Field Value
    source "keryn"
    code the rule id (keryn.inv.lib.openai) or policy rule id (approved-llm-providers)
    message rule message / policy violation text, always citing the component
    severity Semgrep ERROR->1 Error, WARNING->2 Warning, INFO->3 Information; policy error/warning/info likewise
    range rule findings: exact start/end (0-based line, UTF-16 character). Policy violations: the evidence line, full line width. Deep findings without a line (metadata.granularity: "file") sit at the top of their file and their message ends in (file-level finding).
    relatedInformation the finding’s flow, when the engine has one: the taint source ("taint source"), and for a finding proven at rung 3 or higher every hop ("flow step N (<text>)"), each a clickable location.

    Every finding’s message ends in [proof N: <rung>], the proof-ladder rung it is proven at (0 inventory .. 5 reproduced; independent of the rule’s confidence tier), then the rule ids keryn-core folded into it, if any. Deep findings carry the code seceng/<findingClass>.

    Inventory rules (the AI-BOM pack) report Information-level diagnostics: “this line references component X”. Policy violations are Error/Warning according to the policy file. Editors that show Information noisily can filter on source == "keryn" and severity <= 2.

    Scans cover the on-disk tree overlaid with the editor’s unsaved buffers (didOpen/didChange), honouring .keryn.yml in the root (rules, policy, include/exclude, limits). A broken .keryn.yml raises one window/showMessage (type Error) and the default configuration is used until it is fixed.

    All custom methods require initialize first. Parameters are ignored today (reserved: send {}).

    Deep (Keryn pattern analysis first, Deep merged)

    Section titled “Deep (Keryn pattern analysis first, Deep merged)”

    The server runs Deep itself (there is no request for it). Every scan runs Keryn pattern analysis, then its facts (keryn.dev/ir-facts/v1), then the Rust engine compiled to WASM, then the D-4 merge rule (a Deep pattern hit is dropped where a Keryn pattern rule of the same class already reports in that file), then the same collapse, roles, suppression and keryn-core identity as the pattern findings. Deep findings have engine: "seceng", the code seceng/<findingClass>, metadata.granularity: "file" | "line", and a proof rung and trace like every other finding. Deep starts 1.5 s after pattern analysis finishes, and a rescan aborts a running Deep, so typing never queues one Deep run per keystroke.

    A client sees two publishes per scan: pattern diagnostics as soon as Keryn pattern analysis is done, with a keryn/scanFinished carrying deepPending: true, then the whole report (Keryn pattern analysis + Deep) replacing them, with the final keryn/scanFinished. keryn/aibom, keryn/sarif and keryn/bundle wait for the whole report. The summary gains deep: {returned, kept, shadowed, corroborated, noPath, ms, error?} (corroborated: pattern findings Deep proved a flow to, whose message ends “confirmed by Deep”; noPath: flow-dependent pattern findings Deep found no flow to, published at Information severity with “needs review: Deep found no data flow to it”); error means the Deep run failed and the pattern findings stand (the scan never fails because of Deep). deep: false in initializationOptions, or workspace/didChangeConfiguration {"settings": {"keryn": {"deep": false}}}, makes every scan Keryn pattern analysis without Deep (one publish, no deep in the summary); so does an installation without the Deep engine (one stderr line at start-up).

    keryn/deepFindings (a client pushing Deep’s JSON findings into the server) was removed with this change without a protocol bump: no client outside this repository used it, and the 0.3.1 VS Code extension that did is replaced together with its server. A client that still sends it gets -32601.

    Returns the CycloneDX 1.6 BOM object for the workspace as it is now (it waits for a pending debounced rescan, so it reflects unsaved buffers). The BOM validates against the CycloneDX 1.6 JSON schema; its timestamp is the fixed epoch 1970-01-01T00:00:00Z, so identical inputs give identical bytes. Coverage statement and the “absence is not evidence of absence” caveat are in metadata.properties (keryn:coverage.rules, keryn:coverage.files, keryn:caveat). Component evidence is in components[].evidence.occurrences[] (location, line); services carry keryn:occurrences (path:line;...).

    Returns the SARIF 2.1.0 log object of the current report: exactly what keryn scan --sarif writes (driver keryn-scout, partialFingerprints["keryn/fingerprint/v1"], suppressed results with suppressions, taint codeFlows). Inventory-only findings are not SARIF results.

    params: {timestamp?: string} (RFC 3339). Returns the evidence bundle (seceng.evidence_bundle.v2) that keryn-core builds from the result document, the SARIF and the CycloneDX of the current report: a SHA256SUMS over the embedded documents and a content digest on every anchored finding. Given the same timestamp the bytes are identical; without one createdAt is the server’s clock. A timestamp that does not parse is -32602. keryn verify-bundle <file> checks a saved bundle.

    For every diagnostic in context.diagnostics that is a rule finding of the current report (same code, same first line; policy diagnostics and file-level Deep findings are skipped) the server returns one quickfix titled Suppress with nosemgrep: <ruleId> whose edit inserts the language’s nosemgrep: <ids> comment on the line above the finding at its indentation. The comment lists the rules keryn-core collapsed into the finding (alsoMatched) too, so the next scan drops all of them into suppressed.

    keryn/scan (request) and workspace/executeCommand

    Section titled “keryn/scan (request) and workspace/executeCommand”

    keryn/scan and workspace/executeCommand {command: "keryn.scan"} force a fresh scan, publish diagnostics, and return the summary:

    {"subject": "my-repo", "components": 13, "findings": 16, "violations": 3, "policyPass": false,
    "core": "keryn-core/0.3.1", "fingerprints": {"n": 16, "sha256": "…"},
    "coverage": "29/29 rules executed (0 unsupported, 0 partial, 0 timed out); 4 files scanned, 0 skipped.",
    "complete": true, "deep": {"returned": 3, "kept": 2, "shadowed": 1, "ms": 1810}, "elapsedMs": 42}

    core is the keryn-core version that fingerprinted the scan and fingerprints the count and SHA-256 of the sorted fingerprints (what the cross-shell receipts compare); deep is present only when Deep ran (see “Deep”).

    workspace/executeCommand {command: "keryn.aibom"} returns the same BOM as keryn/aibom. Unknown commands fail with -32602; unknown methods with -32601.

    Diff against a base (keryn/scan {base}, .keryn.yml base)

    Section titled “Diff against a base (keryn/scan {base}, .keryn.yml base)”

    keryn/scan accepts {"base": "<git ref | path/to/bom.json>"}. The server reads the ref from the local clone (never fetches; a shallow clone yields a logged window/logMessage and the scan runs without a diff) or the CycloneDX file inside the workspace, scans the base with the same rules, and the summary gains

    "diff": {"components": {"added": [{"key": "library:ollama", "kind": "library", "name": "ollama", "category": "local-inference"}], "removed": []}, "findings": {"added": 1, "removed": 0}}

    Findings the base did not have are published with their message prefixed [new] , so an editor’s Problems view shows what this change introduced. A base of merge-base is resolved by the server: the common ancestor of HEAD and origin’s default branch (refs/remotes/origin/HEAD, else origin/main, origin/master, main, master; local refs only, nothing fetched; none found = a logged window/logMessage and no diff). components.changed (prompts and models whose content or id changed, T5 WP7) is [{"key", "change": "prompt|model", "reason", "name", "from", "riskScore"?}], and findings.items lists the added findings (at most 500; findings.added is the full count), in report order:

    "findings": {"added": 1, "removed": 0, "items": [{"id": "<keryn-fp/v1 fingerprint>", "ruleId": "...", "path": "src/a.py", "line": 12, "endLine": 12, "severity": "error", "message": "...", "proof": "proof 3 (path-cross-file)"}]}

    id is the finding’s identity (its fingerprint, else rule + file + matched text); line/endLine are 1-based; proof is the shared proofText line and is absent without a proof. .keryn.yml base: makes every automatic scan a diff. VS Code: “Keryn: AI components added by this change”; the Keryn change Explorer view (keryn.delta, shown while keryn.delta.base is set) lists components added / removed / changed, the added findings and prompt / model changes.

    keryn/scanFinished (notification, server -> client)

    Section titled “keryn/scanFinished (notification, server -> client)”

    Sent after every published scan with the same summary object as above; when Deep runs, once after the pattern-analysis publish with deepPending: true and once with the whole report. Use it for a status-bar item (“13 AI components, 3 violations · Deep 2”) and to refresh a BOM view by then calling keryn/aibom.

    textDocument/didOpen, didChange, didSave, didClose, workspace/didChangeWatchedFiles, workspace/didChangeConfiguration (rescan; a boolean settings.keryn.deep switches Deep), initialized, exit. Anything else (including $/...) is ignored.

    JSON-RPC error objects {code, message}: -32002 not initialized, -32601 method not found, -32602 invalid params (bad command, no workspace root, workspace cannot be opened), -32603 internal (scan failed; also logged via window/logMessage type 1). Scan failures never kill the server.

    Neovim (0.10+):

    vim.lsp.start({
    name = 'keryn',
    cmd = {'node', '/path/to/keryn/bin/keryn.mjs', 'lsp', '--stdio'}, -- or {'keryn', 'lsp', '--stdio'} once packaged
    root_dir = vim.fs.root(0, {'.keryn.yml', '.git'}),
    init_options = {diagnostics = 'workspace'},
    })
    -- BOM: vim.lsp.get_clients({name = 'keryn'})[1].request_sync('keryn/aibom', {}, 20000)

    Helix languages.toml:

    [language-server.keryn]
    command = "keryn"
    args = ["lsp", "--stdio"]

    Zed (extension language_server_command) and Sublime LSP ("command": ["keryn", "lsp", "--stdio"], "selector": "source") are the same command line. JetBrains (2023.2+ LSP API / LSP4IJ): ProjectWizardServerDescriptor with GeneralCommandLine("keryn", "lsp", "--stdio"); for the BOM tool window send the custom request keryn/aibom through the plugin’s LSP request API.

    The shapes above are protocol version 1 (experimental.keryn.protocol). New optional fields and new methods may appear; existing ones change only with a protocol bump, announced in the same experimental.keryn capability.