archivebom Task

since CycloneDX Antlib 0.2

The archivebom task is a speciailization of the componentbom task tailored to SBOMs created for zips or tarballs of software distributions. It creates a nested component of the SBOM based on some extra attibutes and expects contents that are turned into componentbom's pureFileComponents.

Some defaults differ from those of componentbom, the component type will by "file" for example. The task also assumes you will at least specify a supplier of the archive component via the nested additionalComponentChildren element and want to use that as manufacturer of the component as well as both the supplier and manufacturer of the SBOM itself. If this is not what you intend, you may need to explicitly set useComponentSupplier, useComponentManufacturer or supplierIsManufacturer.

The component of the SBOM requires archiveVersion as well as purl - the later is also used as the component's name. The group of the archive component will not be set.

Attributes

Attribute Description Required
specVersion Version of the CycloneDX specification for the generated SBOM. This can be specified as number (like "1.7") or one of the enum constants of the org.cyclonedx.Version type (i.e. like "VERSION_16").
The supported values depend on the CycloneDX Core (Java) library version used. 		No, defaults to "1.7" in the current version of the Ant library but this may change in future versions.
format The format of the SBOM(s) to write. May be "json", "xml" (or rather the enum constants of the org.cyclonedx.Format type and their file extensions) or the special value "all".
For spec version 1.2 and later "all" means both "json" and "xml" (so the task will create two files), for "1.0" and "1.1" it is equivalent to "xml".
The supported values depend on the CycloneDX Core (Java) library version used. 		No, defaults to "json".
serialNumber Serial Number of the BOM created. Value must be a valid RFC 4122 UUID URN.
The spec recommends each BOM generated to have a unique serial number, even if the rest of the content doesn't change. This is what this task does by default (i.e. when the attribute is not set).
In the context of reproducible builds you may want to have more control and this is a way to set a fixed serial number.
The special value "random" can be used to explicitly trigger the task's default behavior.
 No, defaults to a random UUID URN. Don't set this attribute unless you know why.
bomName The base name of the generated SBOM file. The full file name will be bomName.format. No, defaults to "bom".
outputDirectory Sets the directory where the SBOM file(s) will be written to. Relative paths are relative to the project's base directory No, defaults to the project's basedir.
componentType The type of the component. Valid types are defined by the CycloneDX specification. No, the default is "file"
archiveVersion The version of the component. Yes
purl The Package-URL (purl) of the component. Will also be used as the component's name. Yes.
description The description of the component. Yes
publisher The publisher of the component. Yes
archiveLocation File location of the archive that the SBOM is created for. Will be used to calculate hashes. No
useComponentSupplier If set to true the supplier of the SBOM's main component will be used for the SBOM itself.
If this is true the main component must specify a supplier. Also you must not use a nested additionalBomContent/supplier child for this task if this is true.		 No, defaults to true.
useComponentManufacturer If set to true the manufacturer of the SBOM's main component will be used for the SBOM itself.
If this is true the main component must specify a manufacturer. Also you must not use a nested additionalBomContent/manufacturer child for this task if this is true.		 No, defaults to true.
supplierIsManufacturer Whether the nested component's supplier shall be used as manufacturer as well. No - defaults to true. Must not be true if a nested additionalComponentChildren/manufacturer exists.

Nested elements

archiveContent

At least one nested archiveContent nested element is required.

archiveContent is a container for arbitrary resources or resource collections. Only file-system resources are allowed.

Each file contained in the nested children will be added as component of type file to the SBOM. The name will be the (relative) file name and hashes are calculated.

This maps to componentbom's pureFileComponents.

additionalComponentChildren

Is a container for arbitrary nested elements a component supports. The nested element specified here are added to the SBOM's main component.

additionalBomContent

Is a container for arbitrary nested elements the componentbom task supports..

Examples

The following task could be used to create the SBOM of the source tarball of this Ant library:

    <cdx:archivebom
        bomName="ant-cyclonedx-${artifact.version}-src.tar.cdx"
        outputdirectory="${output}"
        format="all"
        purl="ant-cyclonedx-src.tar"
        archiveVersion="${artifact.version}"
        description="Apache CycloneDX Antlib Source Distribution"
        publisher="The Apache Software Foundation"
        xmlns:cdx="antlib:org.apache.ant.cyclonedx">
      <additionalComponentChildren>
        <manufacturer refid="ant-team"/>
        <license refid="apache-2"/>
        <externalReferenceSet refid="antlib-ext-refs"/>
      </additionalComponentChildren>
      <archiveContent>
        <fileset dir="../../..">
          <exclude name="build/"/>
          <exclude name="docs/style.css"/>
          <exclude name="ivy/"/>
          <exclude name="lib/"/>
          <exclude name="target/"/>
          <exclude name="examples/"/>
        </fileset>
      </archiveContent>
      <additionalBomContent>
        <license refid="apache-2"/>
      </additionalBomContent>
    </cdx:archivebom>