Software composition analysis (SCA)
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.
Before you start
Section titled “Before you start”- The Keryn CLI (install), or Keryn Web.
- A repository with a lockfile. A manifest without a lockfile (
package.jsonalone,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.
Two ways to run SCA
Section titled “Two ways to run SCA”| 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 |
Inventory: direct and transitive packages
Section titled “Inventory: direct and transitive packages”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 matching with OSV
Section titled “Advisory matching with OSV”Advisory data is OSV: GitHub Security Advisories, PyPA, RustSec, Go, and the other databases it aggregates.
Offline by default
Section titled “Offline by default”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.
--online: what is sent
Section titled “--online: what is sent”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.
Affected, not affected, unknown
Section titled “Affected, not affected, unknown”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.
One finding per vulnerable package
Section titled “One finding per vulnerable package”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.
Reachability
Section titled “Reachability”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.
Supply-chain signals
Section titled “Supply-chain signals”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.
Licences
Section titled “Licences”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.
Licence policy
Section titled “Licence policy”Add a licenses: key to your policy:
apiVersion: keryn.dev/policy/v1rules: []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 dependencieswaivers: - rule: licenses.deny component: "npm:some-gpl-tool" # <ecosystem>:<name>[@<version>] reason: build-time only, approved by legal (LEG-12) expires: 2027-06-30keryn scan . --policy .keryn/policy.ymlAn 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.
SBOMs (CycloneDX and SPDX)
Section titled “SBOMs (CycloneDX and SPDX)”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.
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.
keryn sca sbom release.cdx.json dist/ --out out/sbom --notices NOTICES.txtOut. 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.
keryn sbom . -o sbom.cdx.jsonkeryn sbom . --format spdx -o sbom.spdx.jsonCheck the two format identifiers in the saved documents:
jq -r '.bomFormat + " " + .specVersion' sbom.cdx.jsonjq -r '.spdxVersion' sbom.spdx.jsonCycloneDX 1.6SPDX-2.3Each 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.
Gates and exit codes
Section titled “Gates and exit codes”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(defaulterror). - Change gate:
keryn sca inventory --base old/inventory.json --fail-on-changefails 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:
keryn scan . --online --fail-on error --sarif keryn.sarifAdd --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):
keryn ci . --out out/ci --sca --sca-onlinekeryn 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.
Not covered yet
Section titled “Not covered yet”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 imagereads 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--pullit 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 fromKERYN_REGISTRY_USERNAMEandKERYN_REGISTRY_PASSWORDorKERYN_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, andkeryn scandoes not read OS package databases in a source tree. In 0.5.2, gate a Trivy or Grype image report withkeryn 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 fixproposes 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-prit 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 intodependency-tree.txt) and commit or generate the file beside thepom.xml: a scan finds it. For Gradle or Maven with the CycloneDX plugin, rungradle cyclonedxBomormvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBomand name the result:keryn scan . --dependencies build/reports/bom.json(repeatable; CycloneDX or SPDX JSON namedbom.json,sbom.json,*.cdx.jsonor*.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 thepom.xmlor 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, Condaenvironment.ymlandpom.xmlwithout 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. Binarybun.lockbis not read (the run is incomplete; producebun.lockinstead), and Conda packages are not in OSV.
Related
Section titled “Related”- Every field and rule: licences, dependency SBOM, severity and CVSS, VEX, supply-chain signals.
- Report from a scanner you already run: import other scanners’ reports.
- Code that an advisory’s fix removed, rather than a vulnerable version: known-fix matching.
- Source code: static analysis. Compiled files: binary analysis.
- Every flag:
keryn sca collect,scan,import,inventory,assess,deno,sbom,malicious.
Moved from this page
Section titled “Moved from this page”This page used to also describe secrets and agent instruction files, which are not software composition analysis.
Secrets in every scan
Section titled “Secrets in every scan”Now on Secrets.