The dependency SBOM lists every package the tree’s lockfiles lock. It is a separate document from the AI-BOM (keryn bom, --aibom), which lists AI components only. The how-to is in software composition analysis.
Writing one
Section titled “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
Section titled “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
Section titled “Licences”From each package’s licence:
| 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
Section titled “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 emptydependsOn. - SPDX
relationships:SPDXRef-DOCUMENT DESCRIBESthe root. The rootDEPENDS_ONeach direct production package. Each direct development package isDEV_DEPENDENCY_OFthe root. Recorded edges between packages areDEPENDS_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
Section titled “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
Section titled “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.