The how-to is in software composition analysis. This page lists every source, field and rule.
Sources
Section titled “Sources”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.
SPDX normalisation
Section titled “SPDX normalisation”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.
Result fields
Section titled “Result fields”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.
The licenses: policy key
Section titled “The licenses: policy key”apiVersion: keryn.dev/policy/v1rules: []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.
Registry lookup (--online)
Section titled “Registry lookup (--online)”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 systemsnpm,pypi,go,maven,cargo,nugetandrubygems. 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-standardis 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.