# Dependency SBOM

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> The CycloneDX 1.6 and SPDX 2.3 documents keryn sbom and keryn scan --sbom write, field by field; how the dependency graph and licences are mapped; and the SBOMs Keryn reads.

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

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

The dependency SBOM lists every package the tree's lockfiles lock. It is a separate document from the [AI-BOM](https://keryn.dev/docs/guides/ai-bom/) (`keryn bom`, `--aibom`), which lists AI components only. The how-to is in [software composition analysis](https://keryn.dev/docs/guides/sca/#sboms-cyclonedx-and-spdx).

## Writing one

| Command | What runs | Output |
|---|---|---|
| `keryn sbom [path] [--format cyclonedx\|spdx] [-o <file>]` | only the lockfiles and licence metadata are read: no rules, no advisories, no network | stdout, or `-o` |
| `keryn scan <path> --sbom <file> [--sbom-format cyclonedx\|spdx]` | the full scan, with the SBOM as one more output | the file; `-` is stdout |
| `.keryn.yml`: `outputs.sbom: <file>`, `sbomFormat: cyclonedx\|spdx` | same as the flags | |

`keryn sbom` also takes `--subject <name>` (the root component's name, default the folder name), `--revision <id>` (default `dir`), `--timestamp <iso|now>` (default `SOURCE_DATE_EPOCH`, else a fixed 1970 timestamp), `--no-ignore` (also read lockfiles that `.gitignore` excludes) and `-q`. It reads lockfiles up to 64 MiB. Exit codes: 0 when it wrote the SBOM; 3 when no lockfile was found or one was too large to read (the SBOM is still written, but it is incomplete); 2 for a usage error.

The output is deterministic: the same tree and timestamp give the same bytes. Packages are sorted, and the SPDX namespace is derived from the content.

## Packages

One entry per distinct (ecosystem, name, version). A package locked by several lockfiles appears once, with every lockfile listed. Unpinned Deno imports (no version) are left out.

| Fact | CycloneDX 1.6 | SPDX 2.3 |
|---|---|---|
| identity | `bom-ref` `<ecosystem>:<name>@<version>`, `name`, `version` | `SPDXID` `SPDXRef-Package-…`, `name`, `versionInfo` |
| purl | `purl` | `externalRefs[]` `PACKAGE-MANAGER` / `purl` |
| production or development | `scope`: `required` (prod) or `optional` (dev); absent when the lockfile does not say | `comment`: `scope prod\|dev` |
| direct or transitive | property `keryn:direct`; absent when unknown | `comment`: `direct`, `transitive` or `direct unknown` |
| lockfiles | property `keryn:lockfile`, one per lockfile | `comment`: `lockfiles …` |
| graph status | property `keryn:graph` | `comment`: `graph …` |
| ecosystem | property `keryn:ecosystem` | `comment` |
| package kind | `type: library` | `primaryPackagePurpose: LIBRARY`, `filesAnalyzed: false`, `downloadLocation: NOASSERTION` |

## Licences

From each package's [licence](https://keryn.dev/docs/reference/sca/licenses/):

| Licence | CycloneDX `licenses` | SPDX |
|---|---|---|
| one listed SPDX id (`MIT`) | `[{license: {id: "MIT"}}]` | `licenseDeclared: "MIT"` |
| any other expression (`MIT OR Apache-2.0`, a `WITH` exception, a `LicenseRef-…`) | `[{expression: "MIT OR Apache-2.0"}]` | `licenseDeclared` is the expression; each `LicenseRef-…` gets an entry in `hasExtractedLicensingInfos` holding the declared text |
| declared text that is not SPDX | `[{license: {name: "<declared>"}}]` | `licenseDeclared: NOASSERTION`; the `comment` quotes the declared text |
| unknown | no `licenses`; property `keryn:license` = `unknown` | `licenseDeclared: NOASSERTION`; `comment`: `licence unknown` |

Where the licence came from is the CycloneDX property `keryn:license:source` (`<source> <file or URL>`), or in the SPDX `comment`. SPDX `licenseConcluded` is always `NOASSERTION`: Keryn reads what a package declares and concludes nothing.

## The dependency graph

Each lockfile records how much it knows about the graph (its `graph` status): `present` (root entries and edges), `partial` (edges, with roots inferred), `flattened` (a resolved list, no edges) or `absent` (declared entries only).

- **CycloneDX** `dependencies`: the root component (`keryn:subject:<subject>`) depends on every direct package. Each package depends on the next package along the shortest path from a root that its lockfile recorded. A package with nothing recorded lists an empty `dependsOn`.
- **SPDX** `relationships`: `SPDXRef-DOCUMENT DESCRIBES` the root. The root `DEPENDS_ON` each direct production package. Each direct development package is `DEV_DEPENDENCY_OF` the root. Recorded edges between packages are `DEPENDS_ON`.

This is the shortest-path tree, not every edge in the lockfile. A lockfile whose graph is `flattened` or `absent` (`requirements.txt`, `go.sum`) adds packages and no edges, and its status is written into the document (CycloneDX `metadata.properties` `keryn:lockfile-graph`, SPDX package comments), so a flat list is not mistaken for a tree.

## Document metadata

| Property | CycloneDX 1.6 | SPDX 2.3 |
|---|---|---|
| version | `bomFormat: CycloneDX`, `specVersion: 1.6`, `version: 1` | `spdxVersion: SPDX-2.3`, `dataLicense: CC0-1.0` |
| subject | `metadata.component`: the application, `name` = subject, `version` = revision | the root package `SPDXRef-Package-root`, `primaryPackagePurpose: APPLICATION` |
| tool | `metadata.tools.components[]`: `keryn` and its version | `creationInfo.creators`: `Tool: keryn-<version>` |
| time | `metadata.timestamp` | `creationInfo.created` |
| licence list | property `keryn:spdx-license-list` | `creationInfo.licenseListVersion` |
| other | property `keryn:sbom` = `dependencies` | `documentNamespace` `https://keryn.dev/spdx/<subject>/<revision>/<digest>` |

Both formats are validated in Keryn's tests against the official schemas: CycloneDX `bom-1.6.schema.json` and SPDX 2.3 `spdx-schema.json`.

## Reading SBOMs

| Command | Reads | Does |
|---|---|---|
| `keryn sca inventory <file>` | CycloneDX 1.4–1.6 JSON, SPDX 2.0–2.3 JSON, OSV-Scanner JSON | imports every package (an SPDX document's described subject is left out), its purl and its licence (`licenseDeclared`, else `licenseConcluded`); CycloneDX `vulnerabilities[].affects` become declared advisories |
| `keryn sca scan <sbom>` | what OSV-Scanner reads | matches the SBOM's packages through OSV-Scanner |
| `keryn sca sbom <release.cdx.json> <files…>` | a release's CycloneDX SBOM and the release files | lists components the files contain but the SBOM does not declare, other versions, and (with `--notices`) components a NOTICES file does not name |

The Keryn SBOM round-trips: `keryn sca inventory` reads what `keryn sbom --format spdx` writes.
