ocibuild_sbom (ocibuild v0.10.4)

View Source

SPDX 2.2 Software Bill of Materials (SBOM) generation.

Generates SPDX 2.2 (ISO/IEC 5962:2021) compliant SBOMs containing:

  • Application name and version
  • All dependencies from lock files (via adapter)
  • ERTS version (if bundled)
  • OTP version
  • Base image reference and digest

Usage

Deps = [#{name => ~"cowboy", version => ~"2.10.0", source => ~"hex"}],
Opts = #{
    app_name => ~"myapp",
    app_version => ~"1.0.0",
    base_image => {~"ghcr.io", ~"myorg/base", ~"v1"},
    base_digest => ~"sha256:abc123...",
    erts_version => ~"14.2",
    otp_version => ~"27.0"
},
{ok, SbomJson} = ocibuild_sbom:generate(Deps, Opts).

SPDX Specification

This module generates SPDX 2.2 JSON format as defined in: https://spdx.github.io/spdx-spec/v2.2.2/

Package URLs (PURLs) follow the specification: https://github.com/package-url/purl-spec

Summary

Types

dependency()
sbom_opts()

Functions

build_referrer_manifest(ArtifactDigest, ArtifactSize, SubjectDigest, SubjectSize)

Build an OCI referrer manifest for attaching the SBOM as an artifact.

generate/2

Generate an SPDX 2.2 SBOM from dependencies and options.

media_type()

Get the media type for SPDX SBOM.

to_purl/1

Generate a Package URL (PURL) for a dependency.

Types

dependency()

-type dependency() :: #{name := binary(), version := binary(), source := binary()}.

sbom_opts()

-type sbom_opts() ::
          #{app_name := binary(),
            app_version => binary() | undefined,
            release_name => binary() | undefined,
            source_url => binary() | undefined,
            base_image => {binary(), binary(), binary()} | none | undefined,
            base_digest => binary() | undefined,
            erts_version => binary() | undefined,
            otp_version => binary() | undefined}.

Functions

build_referrer_manifest(ArtifactDigest, ArtifactSize, SubjectDigest, SubjectSize)

-spec build_referrer_manifest(ArtifactDigest :: binary(),
                              ArtifactSize :: non_neg_integer(),
                              SubjectDigest :: binary(),
                              SubjectSize :: non_neg_integer()) ->
                                 map().

Build an OCI referrer manifest for attaching the SBOM as an artifact.

Creates a manifest following the OCI referrers API specification that links the SBOM artifact to a subject image manifest.

The manifest uses:

  • Empty config blob (OCI spec requirement for artifacts)
  • SBOM layer with application/spdx+json media type
  • Subject reference pointing to the image manifest

Example:

Manifest = ocibuild_sbom:build_referrer_manifest(
    SbomDigest, SbomSize, ImageManifestDigest, ImageManifestSize
).

generate/2

-spec generate([dependency()], sbom_opts()) -> {ok, binary()}.

Generate an SPDX 2.2 SBOM from dependencies and options.

The SBOM includes:

  • Document metadata (name, namespace, creation info)
  • Main application package
  • Dependency packages with PURLs
  • ERTS package (if erts_version provided)
  • Base image package (if base_image provided)
  • Relationships between packages

Example:

Deps = [#{name => ~"cowboy", version => ~"2.10.0", source => ~"hex"}],
Opts = #{app_name => ~"myapp", app_version => ~"1.0.0"},
{ok, SbomJson} = ocibuild_sbom:generate(Deps, Opts).

media_type()

-spec media_type() -> binary().

Get the media type for SPDX SBOM.

Returns the IANA registered media type for SPDX JSON format.

to_purl/1

-spec to_purl(dependency()) -> binary().

Generate a Package URL (PURL) for a dependency.

PURL format depends on the source:

  • Hex packages: pkg:hex/name@version
  • Git repos: pkg:github/owner/repo@version or pkg:generic/name@version
  • Unknown: pkg:generic/name@version

Example:

Dep = #{name => ~"cowboy", version => ~"2.10.0", source => ~"hex"},
~"pkg:hex/cowboy@2.10.0" = ocibuild_sbom:to_purl(Dep).