Apache CycloneDX Ant Library

component

Components are central to CycloneDX SBOMs. There is the component the whole SBOM is about - and there are more components specified inside the SBOM as (transitive) dependencies or parts of the other components.

The component elements can be used as top-level elements and be given an id so they can be later referred to via the refid attribute - see the Ant manual. The can also be referred to by a dependency of another component via componentRef.

Attributes

Attribute	Description	Required
name	The name of the component.	Yes
type	The type of the component. Valid types are defined by the CycloneDX specification.	No, the default is "library"
group	The group of the component.	No
version	The version of the component.	No
purl	The Package-URL (purl) of the component.	No - if not set but `name`, `group` and `version` are present an implicit purl is calculated as `pkg:maven` jar purl from these values.
bomRef	The bom-ref of the component.	No - if not set, the component's - potentially calculated - purl will be used.
scope	The scope of the component. Valid scopes are defined by the CycloneDX specification.	No, `scope` is prohibited for the main component of the SBOM.
isExternal	Whether the component is external. The CycloneDX Specification says: An external component is one that is not part of an assembly, but is expected to be provided by the environment, regardless of the component's scope. This attribute doesn't have any effect as long as CycloneDX Core doesn't support version 1.7 of the specification.	No, `isExternal` must not be `true` for the main component of the SBOM.
description	The description of the component.	No
publisher	The publisher of the component.	No
copyright	The copyright of the component.	No
mimetype	The MIME-type of the component.	No
manufacturerIsSupplier	Whether the nested manufacturer shall be used as supplier as well.	No - defaults to `false`. Must not be `true` if a nested supplier exists.
unknownDependencies	Whether the dependencies of this component are unknown. If set to `false` then a component without any nested dependency elements is treated as having no dependencies at all.	No - defaults to `false`.

Nested elements

any file-system resource

At most one nested resource specifies the file the component describes. This is required if you want to include hashes for the component in your SBOM.

sbomLink

At most one resource can be specified as sbomLink. When present the referenced resource is read as CycloneDX SBOM and:

type, name, group, version, purl, bomRef, scope, decription, publisher, copright, mimeType and manufacturer are taken from the SBOM's metadata component unless they are explicitly specified on the component element itself.
supplier is taken from the SBOM's metadata component unless it is explicitly specified on the component element itself or manufacturerissupplier is true.
Tags are merged wiht those of the SBOM's metadata component.
authors, licenses, exteranlReferences, dependencys and nested components are taken from the SBOM's metadata component if and only if there is no corresponding element in this component element.
Hashes of the linked SBOM are ignored completely.
Other components specified in the linked SBOM are also added to the SBOM created by the compomentbom task if they are direct dependencies of the current component element. And their dependencies are set to "unknown" as handling of transitive dependencies is beyond the scope of this library.
Components specified explicitly in the SBOM take precedence over those found by parsing an SBOM link. If there already exists a component as part of the SBOM with the same name and group as one read from the linked SBOM, the linked component will be ignored. Here the version is ignored, it is assumed the component explicitly specified is the result of a process that resolved conflicts in dependency versions.

The CycloneDX Core (Java) library is used to read the linked SBOM.

manufacturer

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

supplier

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

author

Adds an author to the component.

Attributes

Attribute	Description	Required
bomRef	The bom-ref of the author.	No
name	The name of the author.	No
email	The email of the author.	No
phone	The phone of the author.	No

tag

Adds a tag to the component. Tags haven't got any attributes or nested elements, the nested text is used as tag.

property

Adds a property to the component.

Attributes

Attribute	Description	Required
name	The name of the property.	No
value	The value of the property.	No

license

A nested license specifies the license information of the component.

externalReference

A nested externalReference specifies an external reference for the component.

externalReferenceSet

A nested externalreferenceset specifies external references for the component.

dependency

Adds a dependency to the component.

Inside the SBOM both the dependee and the dependency side are identified by their bom-ref. Therefore nested dependency children are only allowed in components that provide a bom-ref - either via an explicit bomRef attribute or an explicit or calculated purl.

Attributes

Attribute	Description	Required
bomRef	References the dependency by its `bom-ref`.	Exactly one of the two.
componentRef	References the dependency by its Ant `id` attribute. The referenced component must have a `bom-ref`.	Exactly one of the two.

component

Adds a nested component to the component.

Nested components can be used to represent a hierarchy of components into sub-components and so on.

Components can be added as full elements or via the refid attribute as references to components defined elsewhere in the build file. Ant verifies this doesn't cause a circular dependency between a component and one higher up in the hierarchy.

Examples

Below is a component that could describe this Antlib.

      <cdx:component
          name="ant"
          group="org.apache.ant"
          version="1.10.17"
          isExternal="true"
          unknownDependencies="true"
          id="ant"
          xmlns:cdx="antlib:org.apache.ant.cyclonedx">
        <manufacturer refid="ant-team"/>
        <license refid="apache-2"/>
        <externalReference
            type="VCS"
            url="https://github.com/apache/ant"/>
        <externalReference
            type="WEBSITE"
            url="https://ant.apache.org/"/>
      </cdx:component>
      <cdx:component
          name="ant-cyclonedx"
          group="org.apache.ant"
          version="0.1"
          description="Apache CycloneDX Antlib"
          publisher="The Apache Software Foundation"
          manufacturerIsSupplier="true"
          xmlns:cdx="antlib:org.apache.ant.cyclonedx">
        <file file="ant-antlibs-cyclonedx-0.1.jar"/>
        <manufacturer refid="ant-team"/>
        <license refid="apache-2"/>
        <externalReferenceSet refid="antlib-ext-refs"/>
        <dependency componentRef="ant"/>
        <dependency bomRef="pkg:maven/org.cyclonedx/cyclonedx-core-java@12.2.0?type=jar"/>
      </cdx:component>