Skip to content

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

    Dependency licences

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    The how-to is in software composition analysis. This page lists every source, field and rule.

    Every keryn scan records a licence for each locked package when one of these declares it. The first source that has one wins, in this order:

    Order Source Ecosystems source value at
    1 package-lock.json, npm-shrinkwrap.json: license, or the older {type} and licenses: [{type}] (several mean any of them) npm lockfile the lockfile
    1 composer.lock: license (a list means any of them) Packagist lockfile the lockfile
    2 *.dist-info/METADATA, *.egg-info/PKG-INFO in the tree: License-Expression, else a one-line License (not UNKNOWN), else License :: trove classifiers PyPI package-metadata the metadata file
    2 vendor/<crate>/Cargo.toml (cargo vendor): [package] license crates.io package-metadata the manifest
    2 vendor/<vendor>/<package>/composer.json with a version Packagist package-metadata the manifest
    3 A CycloneDX component’s licenses (keryn sca inventory only): an expression, or license.id / license.name (several entries are joined with AND) any sbom the SBOM file
    4 deps.dev, only with keryn scan --online (below) npm, PyPI, Go, crates.io, Maven, NuGet, RubyGems registry the deps.dev URL of that version

    node_modules is never read. 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. A package that no source describes has license: null: its licence is unknown, which is not the same as unlicensed.

    Each declared text is parsed as an SPDX licence expression against the SPDX License List 3.29.0, which ships inside Keryn (740 licence ids, 86 exceptions).

    Declared Recorded
    mit or apache-2.0 MIT OR Apache-2.0 (list case, single spaces)
    (MIT OR ISC) AND Zlib kept; parentheses only where OR sits inside AND
    GPL-2.0+ GPL-2.0-or-later
    GPL-2.0-only WITH classpath-exception-2.0 GPL-2.0-only WITH Classpath-exception-2.0
    LicenseRef-acme, DocumentRef-x:LicenseRef-y kept as written
    MIT/Apache-2.0, MIT, Apache-2.0 (npm lists) MIT OR Apache-2.0
    Apache License, Version 2.0, Apache 2.0, The MIT License, GPLv3+, PSF … the one SPDX id it names, from a short table of exact names
    License :: OSI Approved :: MIT License (Python classifier) MIT; BSD License names no single licence and is ignored
    UNLICENSED, SEE LICENSE IN <file>, non-standard (deps.dev) no expression; error says why
    anything else, BSD alone included no expression; error: unknown licence identifier …

    Nothing is guessed from a package name.

    In the result JSON (keryn scan --json), under dependencies:

    {
    "spdxList": "3.29.0",
    "licenses": {"packages": 8, "declared": 7, "spdx": 7, "unknown": 1},
    "lockfiles": [{
    "path": "app/package-lock.json", "kind": "package-lock.json", "graph": "present",
    "packages": [{
    "ecosystem": "npm", "name": "express", "version": "4.18.2", "purl": "pkg:npm/express@4.18.2",
    "direct": true, "scope": "prod", "path": ["express"], "line": 6,
    "license": {"declared": "MIT", "expression": "MIT", "source": "lockfile", "at": "app/package-lock.json"}
    }]
    }]
    }
    Field Meaning
    license.declared the text as the source wrote it (a list joined with OR)
    license.expression canonical SPDX expression; absent when declared is not one
    license.error why it is not an expression
    license.source, license.at where it was read (table above)
    licenses.packages distinct packages (ecosystem, name, version)
    licenses.declared, licenses.spdx, licenses.unknown how many of them have a licence, a valid SPDX expression, none

    A vulnerable-dependency finding also carries its package’s licence in metadata.license. keryn sca inventory puts it on each component as license. The dependency SBOM writes it into CycloneDX and SPDX.

    apiVersion: keryn.dev/policy/v1
    rules: []
    licenses:
    deny: [GPL-*, AGPL-*]
    allow: [MIT, Apache-2.0, BSD-*, ISC]
    unknown: warn
    dev: judge
    Key Values Default Meaning
    deny list of patterns none a package whose every choice uses a denied licence is a licenses.deny violation
    allow list of patterns no allow list when set, some choice must use only allowed licences, else licenses.allow
    unknown allow, warn, error warn a package with no licence, or one that is not an SPDX expression: licenses.unknown at that severity (allow: no violation)
    dev judge, ignore judge ignore: packages only ever locked as dev dependencies are not judged

    A pattern is an SPDX id (case does not matter), a prefix with * (GPL-*), or a whole leaf with its exception (GPL-2.0-only WITH Classpath-exception-2.0). An id pattern also matches that id with any exception.

    Choices. An expression offers one choice per OR branch, and AND combines licences inside a choice. MIT OR GPL-3.0-only offers {MIT} and {GPL-3.0-only}, so it passes a policy that denies GPL-*. (MIT OR ISC) AND Zlib offers {MIT, Zlib} and {ISC, Zlib}. A package passes when at least one choice uses no denied licence and, with allow, only allowed ones. An expression that would need more than 256 choices counts as unknown.

    Rule id Severity Message names
    licenses.deny error (exit 1) the package, its expression, the denied licences, where the licence was read
    licenses.allow error (exit 1) the package, its expression, the licences not on the list
    licenses.unknown warning, or error with unknown: error the package and why (none recorded, or the declared text and the parse error)

    Each violation’s component is <ecosystem>:<name>@<version> (npm:left-pad@1.3.0), and its evidence is every lockfile and line that locks it. Violations appear in the result JSON (policy.result.violations), SARIF, the Markdown summary and the console. The console lists them under Dependency licences: violated (N packages, M with no licence recorded; K violations), separately from the AI-component rules.

    Waivers work as for other policy rules: rule is the rule id, component is <ecosystem>:<name>@<version> for one version or <ecosystem>:<name> for every version, and a reason and an unexpired expires are required.

    With keryn scan --online, the packages still without a licence after the sources above are looked up on deps.dev (Open Source Insights):

    • GET https://api.deps.dev/v3/systems/{system}/packages/{name}/versions/{version}, for systems npm, pypi, go, maven, cargo, nuget and rubygems. Packagist, Pub, Hex, Swift, Conan and Deno registries are not covered.
    • Only ecosystem, name and version are sent, through a fetcher that accepts only that origin. It sends no credentials and no referrer, and follows no redirect.
    • Answers, a 404 included, are cached on disk beside the advisory cache. At most 5,000 lookups run per scan.
    • Several licences are joined with AND. non-standard is kept as a licence that is not SPDX.
    • The project’s own crates (Cargo.lock entries without a source) are never looked up.
    • A failed lookup leaves the packages unknown. Coverage then says N package licences not looked up on deps.dev: ….

    Offline, coverage says N package licences unknown: their lockfiles record none. keryn scan --online looks them up on deps.dev, sending package names and versions only. The call is listed in privacy.