# Dependency licences

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> Where Keryn reads each dependency's licence, how it normalises SPDX expressions, the result fields, the licenses policy key and its rule ids, and the optional registry lookup.

Source: https://keryn.dev/docs/reference/sca/licenses/

> **Caution: Ships in the next release**
> On main; not in Keryn 0.5.2, the latest release.

The how-to is in [software composition analysis](https://keryn.dev/docs/guides/sca/#licences). This page lists every source, field and rule.

## 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

Each declared text is parsed as an [SPDX licence expression](https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/) 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

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

```json
{
  "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](https://keryn.dev/docs/reference/sca/sbom/) writes it into CycloneDX and SPDX.

## The `licenses:` policy key

```yaml
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.

## 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 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](https://keryn.dev/privacy/).
