Skip to content

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

    Software composition analysis (SCA)

    View as Markdown

    Software composition analysis answers four questions about the third-party packages in a project: which packages are there, which of them have published vulnerabilities, whether the version you lock is inside the affected range, and under which licences you use them. This page covers how Keryn does that, where it sends data (only when you ask), how it gates a build, and what it does not cover yet.

    Secrets and agent instruction files are separate checks with their own pages: secrets and agent skill and instruction files.

    • The Keryn CLI (install), or Keryn Web.
    • A repository with a lockfile. A manifest without a lockfile (package.json alone, pyproject.toml) is not resolved.
    • Keryn never uploads your code. Advisory matching sends package names and versions to OSV.dev, and only when you pass --online.
    Comparison keryn scan keryn sca
    What it is A dependency pass inside every source scan A separate command with seven actions, each writing a receipt directory
    Matcher Keryn’s own (Rust, keryn-osv-match) An OSV-Scanner v2 you installed (scan, collect); Keryn’s matcher (deno, assess); none (import, inventory, sbom)
    Advisory data OSV.dev API, with --online only OSV-Scanner’s local database offline, or OSV.dev with --online
    Output Findings in the scan result, SARIF and annotations run.json, the raw report, and when it parses result.json, results.sarif, summary.md
    Use it for Everyday scans and pull requests CI receipts, complete inventories, SBOM checks, gating reports from other tools

    keryn scan reads these lockfiles anywhere in the tree:

    Ecosystem Files
    npm, pnpm, Yarn, Bun package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml, yarn.lock (v1 and Berry), bun.lock
    Python poetry.lock, Pipfile.lock, uv.lock, pdm.lock, requirements*.txt (pinned name==version lines)
    Go go.mod (after replace directives), go.sum
    Rust Cargo.lock
    Ruby Gemfile.lock, gems.locked
    PHP composer.lock
    Java gradle.lockfile; pom.xml as declared only (literal versions and same-file properties, no parent, BOM or transitive resolution)
    .NET packages.lock.json
    Dart, Elixir, Swift, C/C++ pubspec.lock, mix.lock, Package.resolved, conan.lock
    Deno deno.lock; Deno code without one is read as declared, not locked

    bun.lockb is binary and is reported as unreadable, not as empty. A lockfile larger than --max-file-size (1,000,000 bytes by default) is still read for the dependency stage, up to 64 MiB, and never by the pattern or secrets pass; one that cannot be read (binary, over 64 MiB) is named in coverage as Dependency input not read and makes the dependency coverage incomplete.

    For every package Keryn records whether it is direct (true, false or unknown), its scope (prod or dev) and introduced by: the shortest path from the project root to it. Each lockfile also records whether its dependency graph was present, partial, flattened or absent, because some formats (requirements.txt, go.sum) do not carry one. These facts are in each finding’s metadata.dependencyFacts. They inform you; they never change the gate.

    A lockfile in a test, research or vendored folder is labelled with that role and its findings are set aside (counted, not gated), as vendored source is.

    Advisory data is OSV: GitHub Security Advisories, PyPA, RustSec, Go, and the other databases it aggregates.

    Without a flag, a scan makes no network call. It reads the lockfiles and says so on the coverage line: “N lockfiles not checked against vulnerability advisories (offline)”. A clean dependency result from an offline scan means nothing was checked.

    On main (not in 0.5.2) there is a second way to check dependencies with no network: an advisory snapshot installed on the machine. keryn sca db update --from <folder or https address> builds one from OSV’s per-ecosystem export files, and from then on a scan without --online checks every locked package against it and says so: Dependency advisories: checked (snapshot 2026-11-17), with the same date in the result JSON, SARIF and Markdown. An ecosystem the snapshot does not hold stays “not checked” and --require-advisories exits 3 for it; --advisory-max-age <days> makes an old snapshot an incomplete run. keryn sca db status shows what is installed. The step-by-step procedure is in the air-gapped guide.

    Terminal window
    keryn scan . --online

    --online sends, for each locked package, its ecosystem, name and version to https://api.osv.dev/v1/querybatch (up to 1,000 per request), then fetches each matching advisory record by id. Nothing else: no code, no file paths, no credentials, no referrer. Packages without a version, and JSR, deno.land/x and URL modules, are never sent. Records are cached on disk in an advisories folder beside the rescan cache (KERYN_CACHE_DIR moves it), keyed by id and modification time, so a changed advisory is fetched again. In Keryn Web, a report with unchecked lockfiles offers Check dependencies, which does the same on click; the desktop app never makes the call. See local-only.

    keryn sca scan and keryn sca collect are offline by default too, and then need OSV-Scanner’s own local advisory database. --online lets OSV-Scanner query OSV.dev. OSV-Scanner’s manifest resolution and call analysis are switched off, so it does not run your build tools.

    Keryn does not trust a database’s yes or no. For each package it evaluates every advisory’s ranges itself (introduced, fixed, last affected and limit events, as OSV-Scanner does) in the ecosystem’s own version order: SemVer for npm, crates.io, Go and JSR; PEP 440 for PyPI; Maven, RubyGems, Packagist and ConanCenter orders; semver dialects for NuGet, Pub, Hex and Swift. Withdrawn advisories are skipped. GIT ranges count only through an advisory’s explicit version list.

    Each package gets one decision, stored as metadata.assessment:

    Decision When
    affected at least one advisory range contains the locked version
    not affected every range of every advisory was evaluated, and none contains it
    unknown some range could not be decided. The reason is recorded: unresolved_range, unparsable_version, unsupported_ecosystem, no_advisory_source, source_parse_errors or budget_exceeded

    An unknown is never counted as clean: undecided packages are listed in the report’s limitations. By the project’s tests, Keryn’s version ordering agrees with the reference implementation on 42,369 of 42,372 ordering vectors; that measures ordering, not how many vulnerable packages a scan finds.

    keryn sca assess <batch.json> runs the same decision engine on a fixed, offline batch of OSV records and package queries (keryn/sca-assessment-batch/1): exit 1 when a package is affected, 3 when a range could not be decided.

    The result is one finding per vulnerable package per lockfile, citing the lockfile. An advisory published under several ids (a GHSA, a PYSEC id, CVE aliases) counts once. The finding lists every advisory with its severity and the versions that fix it (metadata.advisories[].fixed), and its message says which version to upgrade to, or to replace the package when no fixed version exists.

    Severity is the advisory’s own severity word when it has one. Otherwise it is the base score of its newest CVSS vector, computed locally: v4.0 first, then v3.0 or v3.1, then v2. Critical and high become error, medium warning, low info. CVSS v2 has no critical band, so a v2 score of 7.0 or more is high. Each finding records what set its severity in metadata.severitySource (database_specific, cvss_v4, cvss_v3, cvss_v2 or none), along with metadata.cvss and metadata.cvssVersion.

    Each vulnerable dependency finding says whether the code that uses it was found: reachable (with the file and line), not reachable in the analysed code, or unknown (with the reason). It is a priority signal: it never removes a finding or changes the gate, and keryn export --vex --from result.json turns it into OpenVEX statements (not_affected with vulnerable_code_not_in_execute_path, which always cites what was analysed).

    Ecosystem How Not reachable is said only when
    Go (with --online) the vulnerable symbols of the Go vulnerability database (shipped offline, 1,251 entries) against the symbols your Go code calls, found by the Deep pass no analysed Go file uses a listed symbol
    npm (JavaScript/TypeScript) static import, require, import() and re-exports of the package or a subpath in your own source the package is a direct dependency and no file imports it, or it is imported but none of the functions the advisory lists is named
    PyPI import and from … import of the package’s modules (from a vendored top_level.txt, or a table of known names such as PyYAML → yaml, Pillow → PIL) as for npm, and the module names are known
    Maven (Java, Kotlin, Scala) an import under the package’s groupId never: a groupId is not reliably the Java package prefix, so a missing import is not evidence

    Tests, fixtures, examples and vendored code are not analysed, so a package only tests import counts as not reachable from shipped code. Comments and TypeScript import type are not evidence. Transitive packages, a computed require(name) or importlib.import_module(name) anywhere in scope, and reflection keep the verdict unknown. Calls made by other packages, framework configuration, plugins and generated code are not followed, so not reachable is never not vulnerable. The analysis is measured on an authored corpus published on evaluations (sca-reachability): 30 cases with traps (similar package names, test-only use, type-only and commented-out imports, a groupId that is not the package prefix, dynamic loading); its numbers are not real-world rates.

    The core signals:

    Signal What it means Severity
    malicious_package the name (and version, when listed) is in the OpenSSF malicious-packages data (OSV MAL- records) error
    possible_typosquat an unranked name one edit, separator, repeated letter or scope away from a top-2,000 package warning
    install_script_risk npm preinstall/install/postinstall hooks in your own or vendored package.json, shell or network calls at the top level of setup.py warning
    dependency_confusion_risk an .npmrc private registry that does not map your own scope, or pip extra-index-url with unhashed names that are not public packages warning

    Main adds three P2 content signals (obfuscated or network-and-exec install and build hooks, a new maintainer together with a new hook against --base). It also extends malicious-package data to crates.io, RubyGems, Go and NuGet, and adds source-configuration checks for NuGet, RubyGems and Go. If the data is missing from a build, the report says “supply-chain signals unavailable” instead of passing silently. These are indicators, not proof: a package that matches nothing is not shown to be safe.

    Every scan records the licence of each locked package, offline, in the result JSON under dependencies (no flag; --online is not needed). Keryn reads licences only from what the repository already holds, and never looks them up:

    Source Packages
    package-lock.json, npm-shrinkwrap.json (license, older licenses) npm
    composer.lock (license; several mean any of them) Packagist
    *.dist-info/METADATA, *.egg-info/PKG-INFO in the tree (License-Expression, else a one-line License, else License :: classifiers) PyPI
    vendor/<crate>/Cargo.toml (after cargo vendor) and vendor/<vendor>/<package>/composer.json crates.io, Packagist
    A CycloneDX SBOM’s components[].licenses, through keryn sca inventory any

    Each package carries the licence as declared, its canonical SPDX expression checked against the SPDX License List 3.29 shipped with Keryn, and the file it came from. Declared text that is not an expression is kept as written: a few exact names are mapped (Apache License, Version 2.0 is Apache-2.0), anything else stays unrecognised and is never guessed. A package none of these sources describes is unknown, which is not the same as unlicensed.

    Offline, expect unknowns. pnpm-lock.yaml, yarn.lock, bun.lock, Cargo.lock, poetry.lock, uv.lock, go.sum, Gemfile.lock, Maven, Gradle and NuGet lockfiles record no licence, and node_modules is never read, so those packages are unknown unless their metadata is vendored into the tree. The coverage line says how many.

    With keryn scan --online, Keryn asks deps.dev (Open Source Insights) for the licence the registry declares for each of those packages at that exact version (npm, PyPI, Go, crates.io, Maven, NuGet, RubyGems). Only the ecosystem, name and version are sent, to api.deps.dev and nowhere else; answers are cached on disk; at most 5,000 lookups per scan. Such a licence is recorded with source: registry and the deps.dev URL, and a licence from a lockfile, vendored metadata or an SBOM always wins. The project’s own crates (Cargo.lock entries without a source) are never looked up. A package deps.dev does not know stays unknown.

    Add a licenses: key to your policy:

    apiVersion: keryn.dev/policy/v1
    rules: []
    licenses:
    deny: [GPL-*, AGPL-*, SSPL-1.0] # SPDX ids, Prefix-*, or a full "X WITH Y"
    allow: [MIT, Apache-2.0, BSD-*, ISC] # optional: when given, every licence used must be on it
    unknown: warn # allow | warn | error
    dev: ignore # judge (default) | ignore packages only locked as dev dependencies
    waivers:
    - rule: licenses.deny
    component: "npm:some-gpl-tool" # <ecosystem>:<name>[@<version>]
    reason: build-time only, approved by legal (LEG-12)
    expires: 2027-06-30
    Terminal window
    keryn scan . --policy .keryn/policy.yml

    An expression offers choices: MIT OR GPL-3.0-only can be used under MIT, so it passes a policy that denies GPL; MIT AND GPL-3.0-only cannot. A package fails when none of its choices uses only licences that are not denied and, with an allow list, all allowed. Violations have rule ids licenses.deny and licenses.allow (errors, exit 1) and licenses.unknown (a warning, or an error with unknown: error). Each one names the package, its expression, and the lockfile and line. They are in the result JSON, SARIF, the Markdown summary and the console under Dependency licences, and are waivable like any policy rule.

    In. keryn sca inventory reads an OSV-Scanner JSON report, a CycloneDX JSON SBOM or an SPDX 2.3 JSON document and imports every package, including those with no advisory, keeping where each one came from. Advisories that the SBOM’s producer declared (vulnerabilities[].affects) are imported as declared. keryn sca scan bom.cdx.json hands an SBOM to OSV-Scanner for matching.

    Terminal window
    keryn sca inventory bom.cdx.json --out out/inv --complete

    --complete is your assertion that the SBOM lists everything; without it the inventory is reported as incomplete (exit 3). --snapshot and --as-of record which advisory database the report was made with and how old it is. --bindings records the AI role each package plays (declared by you, not detected).

    Checked against the release. keryn sca sbom compares a release’s CycloneDX SBOM with what its files actually contain: Rust crates from <crate>-<version>/src/ paths in binaries, npm packages from bundler node_modules/<package>/ keys, a bundled Node runtime’s release marker, and the registry packages of a Cargo.lock you pass. It lists undeclared components, other versions, and with --notices the components a NOTICES file does not name. Archives are named, not unpacked. Local only.

    Terminal window
    keryn sca sbom release.cdx.json dist/ --out out/sbom --notices NOTICES.txt

    Out. keryn sbom writes the dependency SBOM: every package the lockfiles lock, as CycloneDX 1.6 JSON (default) or SPDX 2.3 JSON. It reads only the lockfiles and the package metadata that carries licences, runs no rules, and sends nothing. keryn scan --sbom <file> writes the same document from a full scan.

    Terminal window
    keryn sbom . -o sbom.cdx.json
    keryn sbom . --format spdx -o sbom.spdx.json

    Check the two format identifiers in the saved documents:

    Terminal window
    jq -r '.bomFormat + " " + .specVersion' sbom.cdx.json
    jq -r '.spdxVersion' sbom.spdx.json
    CycloneDX 1.6
    SPDX-2.3

    Each package has its purl, version, scope (CycloneDX required for production, optional for development), whether it is direct, the lockfiles that lock it, and its licence: a single SPDX id, an SPDX expression, the declared text as a named licence when it is not SPDX, or nothing when it is unknown. SPDX 2.3 puts the declared licence in licenseDeclared and leaves licenseConcluded as NOASSERTION, because Keryn reads declarations and concludes nothing. The dependency graph is the shortest path each lockfile records: the application depends on the direct packages, and each package depends on the next one on a recorded path (SPDX DEPENDS_ON, DEV_DEPENDENCY_OF for direct development dependencies). A lockfile that records no graph (requirements.txt, go.sum) adds packages and no edges, and its graph status is written into the document so a flat list is not mistaken for a tree. The output is deterministic: the same tree and --timestamp give the same bytes.

    keryn sbom exits 0 when it wrote the SBOM, and 3 when no lockfile was found or a lockfile was too large to read (over 64 MiB): the SBOM is still written, but it is incomplete. The AI-BOM (keryn bom, keryn scan --aibom) is a separate CycloneDX 1.6 document that lists AI components only.

    keryn scan gates dependency findings like any other finding: exit 1 for findings at or above --fail-on (default error), 3 for incomplete coverage, 4 for an internal error. See the CLI exit codes.

    Every keryn sca action writes into a new, empty --out directory and records what it ran in run.json:

    Exit collect, scan, import, deno inventory assess sbom
    0 pass pass no package affected ok
    1 findings at or above --fail-on, or a change gate change gate tripped, or findings a package is affected undeclared, mismatched or missing from notices
    2 usage error or invalid input usage error usage error usage error
    3 incomplete or unknown completion inventory incomplete (no --complete) a range could not be decided nothing observed
    4 execution or normalization failure execution failure execution failure not used

    Two gates are separate on purpose:

    • Vulnerability gate: --fail-on error|warning|info|none (default error).
    • Change gate: keryn sca inventory --base old/inventory.json --fail-on-change fails when a package, an AI binding or the advisory snapshot changed, with or without an advisory. Use it to make every new dependency a reviewed change.

    keryn sca import reads a report someone else produced. Its completion defaults to unknown (exit 3) even when the report has no findings, because an empty report does not show that the scan ran to the end; pass --completion complete when your pipeline knows it did.

    The simplest gate is the scan itself:

    Terminal window
    keryn scan . --online --fail-on error --sarif keryn.sarif

    Add --require-advisories so a run that could not reach the advisory source fails (exit 3) instead of passing with nothing checked.

    For a receipt per stage, keryn ci runs the SCA actions beside the source scan and returns one exit code (precedence 4 > 2 > 3 > 1 > 10 > 0):

    Terminal window
    keryn ci . --out out/ci --sca --sca-online
    keryn ci flag Runs
    --sca keryn sca scan with the installed OSV-Scanner, offline; --sca-online permits advisory requests
    --sca-collect keryn sca collect (every package and advisory)
    --sca-report <report> keryn sca import of a report from another tool (--sca-parser, --sca-completion)
    --sca-inventory <report> keryn sca inventory (--sca-bindings, --sca-inventory-complete)

    An application profile sets sca.mode: online to add --online. Keryn never installs OSV-Scanner; put it on the runner yourself. The general pipeline shapes are in Add Keryn to CI.

    These are common in dedicated SCA products and Keryn does not do them today. Plan around them.

    • Licence texts and notices. Licence files are not read or classified, and no attribution or NOTICES file is generated. Packagist, Pub, Hex, Swift and Conan licences come only from their lockfiles (deps.dev does not cover them).
    • Call-graph reachability outside Go. JavaScript, Python and Java reachability is read from imports (and from the functions an advisory names), not from a call graph; other ecosystems report unknown. OSV-Scanner’s call analysis is switched off.
    • Behavioural malicious-package analysis. Keryn 0.5.2 has no supply-chain checks. Main matches published malicious-package records in six ecosystems and reads install and build hooks statically (supply-chain signals). Package code is never run, so behaviour that only shows at install or run time is not seen. Typosquat checks cover npm and PyPI only, and the content signals’ false-positive rates are not yet measured.
    • Container images from a registry. Keryn 0.5.2 reads no images. On main, keryn sca image reads a Docker save tarball or an OCI layout: dpkg, apk and SQLite RPM databases, plus the language packages inside the image. It needs an advisory snapshot (--advisories) or --online. With --pull it reads the image by reference from its registry (keryn sca image registry.example.com/team/app@sha256:... --pull --platform linux/amd64 --out out/image): the manifest, then the config and layers by digest over HTTPS, with no daemon and no docker, skopeo or crane. Nothing is fetched without --pull. Every layer is checked against its digest, the report records the manifest digest and the platform, and credentials come only from KERYN_REGISTRY_USERNAME and KERYN_REGISTRY_PASSWORD or KERYN_REGISTRY_TOKEN (there is no cloud credential helper: for ECR, GCR or ACR pass a token you obtained). Only the registry you name and the token endpoint it advertises are contacted; registries that redirect layer downloads to a storage host (Docker Hub, GHCR, ECR) need --pull-redirects. In a pipeline: keryn ci --sca-image <reference> --sca-image-pull. It does not talk to a daemon, scan running containers, or read Berkeley DB RPM databases, and keryn scan does not read OS package databases in a source tree. In 0.5.2, gate a Trivy or Grype image report with keryn sca import.
    • Signed or remote VEX. Keryn reads local OpenVEX, CSAF 2.0 VEX and CycloneDX VEX files (--vex) and writes OpenVEX or CycloneDX VEX, but checks no signature and fetches nothing: a statement is an attributed producer claim, not proof. See VEX.
    • Automatic fixes for every dependency. Keryn 0.5.2 only names the fixed versions. On main, keryn sca fix proposes a patch for direct npm, pinned pip, Cargo and Go dependencies in a copy of the tree. It rescans before and after against the same pinned advisories, and with --create-pr it opens a draft pull request in a repository you own. Package managers run only with --run-package-manager. Transitive packages, hash pins, git or local sources, Go major versions and prereleases stay manual.
    • Maven and Gradle without a lockfile. Keryn does not run Maven or Gradle and does not contact Maven Central. On main it reads the resolved list your build can write, like a lockfile. For Maven, run mvn dependency:tree -DoutputType=json -DoutputFile=dependency-tree.json (or the text form into dependency-tree.txt) and commit or generate the file beside the pom.xml: a scan finds it. For Gradle or Maven with the CycloneDX plugin, run gradle cyclonedxBom or mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom and name the result: keryn scan . --dependencies build/reports/bom.json (repeatable; CycloneDX or SPDX JSON named bom.json, sbom.json, *.cdx.json or *.spdx.json). Every direct and transitive package in the list is then matched, with its scope and the path that brought it in when the file records them, and the list replaces the pom.xml or Gradle build of its project in the coverage line. A component whose package URL Keryn cannot read is reported and makes the dependency coverage incomplete; it is never dropped.
    • Resolving manifest-only projects. Keryn resolves nothing. On main, package.json, pyproject.toml, Gradle, Conda environment.yml and pom.xml without a lockfile are read as declared (“Declared range, not resolved”), and only exact versions are checked against advisories. Ranges, transitive dependencies and Maven parents and BOMs stay unknown, and the coverage statement says so. Binary bun.lockb is not read (the run is incomplete; produce bun.lock instead), and Conda packages are not in OSV.

    This page used to also describe secrets and agent instruction files, which are not software composition analysis.

    Now on Secrets.

    Agent skills and instruction files in every scan

    Section titled “Agent skills and instruction files in every scan”

    Now on Agent skill and instruction files.