Apache CycloneDX Ant Library - componentbom Task

## componentbom Task

The `compomentbom` task creates CycloneDX SBOMs for a component ind the formats supported by the CycloneDX Core (Java) library.

As a minimum a single nested `component` element is required that specifies the component to create an SBOM for.

Components that get "resolved" because they specify an `sbomLink` can add more components to the SBOM than are specified explicitly via the child elements of this task.

It is an error if any component specifies a dependency on a component that is not part of the generated SBOM. The bom-refs of the all components inside the same SBOM file must be unique.

### Attributes

Attribute | Description | Required
--- | --- | ---
specVersion | Version of the CycloneDX specification for the generated SBOM. This can be specified as number (like "1.6") 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.6" 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".
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`.
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 `supplier` child for this task if this is `true`. | No, defaults to `false`.
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 `manufacturer` child for this task if this is `true`. | No, defaults to `false`.

### Nested elements

#### component

Exactly one `component` child element is required - this is the component the SBOM is about.

The structure is the same as of the component type. The `scope` attribute is prohibited for this child element and `isExternal` must not be `true`.

#### manufacturer

At most one nested organization specifies the manufacturer of the SBOM.

This is prohibited if the `useComponentManufacturer` attribute is set to `true`.

#### supplier

At most one nested organization specifies the supplier of the SBOM.

This is prohibited if the `useComponentSupplier` attribute is set to `true`.

#### license

A nested license specifies the license information of the SBOM.

#### additionalComponent

`additionalComponent` child elements specify components that are part of the SBOM but not the main entity. They are required for (transitive) dependencies of the main component but may also be present for different reasons.

#### pureFileComponents

`pureFileComponents` 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 is useful when describing the contents of a tarball for example.

#### toolComponent

`toolComponent` child elements specify components that are added to the `metadata.tools` section of the SBOM. This is meant to be used to add other tools that also participated in the formation of this SBOM (for example by providing component instances).

### Examples

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

        <cdx:componentbom
            bomName="ant-cyclonedx-${artifact.version}-src.tar-cyclonedx"
            outputdirectory="${output}"
            format="all"
            useComponentSupplier="true"
            useComponentManufacturer="true"
            xmlns:cdx="antlib:org.apache.ant.cyclonedx">
          <component
              name="ant-cyclonedx-src.tar"
              version="${artifact.version}"
              description="Apache CycloneDX Antlib Source Distribution"
              publisher="The Apache Software Foundation"
              type="FILE"
              supplierIsManufacturer="true">
            <manufacturer refid="ant-team"/>
            <license refid="apache-2"/>
            <externalReferenceSet refid="antlib-ext-refs"/>
          </component>
          <pureFileComponents>
            <fileset dir="../../..">
              <exclude name="build/"/>
              <exclude name="docs/style.css"/>
              <exclude name="ivy/"/>
              <exclude name="lib/"/>
              <exclude name="target/"/>
              <exclude name="examples/"/>
            </fileset>
          </pureFileComponents>
          <license refid="apache-2"/>
        </cdx:componentbom>