Skip to content

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

    Dependency SBOM

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    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.

    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.

    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

    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.

    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.

    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.

    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.