Skip to main content

atmos.sbom

The atmos.sbom function runs atmos sbom through the current Atmos executable. Use it to generate CycloneDX or SPDX software bills of materials from Atmos lock files and attach them to a build or release from automation.

Usage​

atmos.sbom(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Subcommands​

Pass the subcommand and any positional arguments as strings before the keyword arguments. The call atmos.sbom("generate") runs atmos sbom generate.

SubcommandPurpose
generateGenerate a CycloneDX or SPDX SBOM from project lock files.

See the atmos sbom command reference for the complete list of subcommands and flags.

Arguments​

*positionals

(Optional) Strings placed on the command line right after sbom, in order: the subcommand and its positional arguments. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. A bare key such as "format" becomes --format, and registered shorthands resolve to their long form. For generate, useful keys include "format" (cyclonedx-json or spdx-json ), "scope" (terraform or dependencies ), "mode" (provenance or ntia ), "output" (a file to write instead of standard output), and "upload".

args
(Optional) A list or tuple of strings appended after the flags.
working_directory, env, output, check

(Optional) See atmos.run for process options and defaults. The output keyword argument controls how the function handles process output; it is separate from an "output" key inside flags, which becomes the --output flag of atmos sbom generate.

Options other than the positionals are keyword-only.

Returns​

A result with stdout, stderr, and exit_code. See atmos.run for output and error behavior.

Examples​

Write an SBOM to a file​

atmos.sbom("generate", flags = {"format": "spdx-json", "output": "build/sbom.spdx.json"})

This runs atmos sbom generate --format=spdx-json --output=build/sbom.spdx.json.

Inspect the components in the document​

Without an output file, the SBOM goes to standard output. Capture it and decode it to work with the components in a script.

result = atmos.sbom("generate", flags = {"scope": "dependencies"}, output = "capture")
bom = json.decode(result.stdout)
ui.info("The SBOM lists " + str(len(bom["components"])) + " components.")

Generate an NTIA-conformant SBOM​

The ntia mode requires the subject name, supplier, and version.

atmos.sbom(
    "generate",
    flags = {
        "mode": "ntia",
        "subject-name": "platform",
        "subject-supplier": "Example Corp",
        "subject-version": "1.4.0",
        "output": "sbom.cdx.json",
    },
)

Notes​

note

The atmos sbom command is experimental. The wrappers keep the command's native behavior, so the experimental notice appears on standard error.

Related​