ivyModule ComponentResolver

since CycloneDX Antlib 0.2. The optional Ivy dependency is required when using an ivyModule element.

Using a ivyModule ComponentResolver within a component you can use Apache Ivy to fill in fields from an ivy.xml file and have Ivy provide all (transitive) dependencies of this module to the SBOM.

The ivyModule element is similar to a post resolve task and expects the Ivy module used for the current component to be "resolved" already.

When present the Ivy module will be used to enrich the component it is nested into:

• name, group, version, decription are directly taken from the Ivy module unless the compoment already specifies it explicitly.
• license and "website"-type externalReference are taken from the module's license and homePage if and only if there is no corresponding element in this component element.
• Dependencies of the given module that are included because of the configurations given by the conf attribute are added to the SBOM by the compomentbom task with data taken from their module descriptors. This includes transitive dependencies. The components will have hashes if an Ivy retrieve operation has retrieved them and local files are available prior to running the componentbom task.
  Components specified explicitly in the SBOM take precedence over those found by parsing the module. If there already exists a component as part of the SBOM with the same name and group as one read from the module, the dependencies 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 and is unknown to Ivy. Currently this only applies to Components with pkg:maven/ Package-URLs as bom-ref.

Not all parts of an SBOM component you may want to provide are part of an Ivy module definition and you may want to provide them explicitly. Supplier and manufacturer information, more external references or the publisher are missing for example. The type defaults to "library" and the scope to "required". For the component that contains the ivyModule child element itself, you can use the "normal" attributes and nested element of the component to augment data - for the dependencies identified by the Ivy module you can provide extra data as templateComponent child elements.

Attributes

Nested elements

templateComponent

A nested templateComponent element supports all attributes and nested elements of a component, but neither sbomLink nor ivyModule have any effect.

A templateComponent can be used to enrich a component detected by Ivy as a dependency of the current component. For example by adding more external references or a manufacturer. Template components take precedence over a data detected by Ivy, they are matched to a detected dependency by name and group only, the version is ignored. If the templateComponent has a version attribute, no hashes will be calculated from the resolved file.

The combination of ivyModule, templateComponent and an additionalComponent specified in a compomentbom may be a bit confusing. An additionalComponent is always added to the generated SBOM and any ivyModule dependency or templateComponent that matches the name and group of an additionalComponent is ignored. Apart from that a templateComponent will only show up in the SBOM if a matching dependency is detected by ivyModule. templateComponent and Ivy module dependencies are merged while additionalComponents completely replace Ivy module dependencies.

As an example, assume the ivyModule resolves a module with group "org.example", name "module" and version "1" which has a dependency on a component with group "com.example", name "dependency", version "2" and description "my description".

The following snippet adds two components to the SBOM with bom-refs "pkg:maven/org.example/module@1?type=jar" and "pkg:maven/com.example/dependency@2?type=jar" where the later has a description of "my description" and hashes if the dependency has been retrieved:

      <cdx:componentbom
        <cdx:component>
          <cdx:ivyModule/>
        </cdx:component>
      </cdx:componentbom>
    

The following snippet adds two components to the SBOM with bom-refs "pkg:maven/org.example/module@1?type=jar" and "pkg:maven/com.example/dependency@3?type=jar" where the later has a no description at all and no hashes either.

      <cdx:componentbom
        <cdx:component>
          <cdx:ivyModule/>
        </cdx:component>
        <cdx:additionalComponent
            name="dependency"
            group="com.example"
            version="3"
          />
      </cdx:componentbom>
    

The following snippet adds two components to the SBOM with bom-refs "pkg:maven/org.example/module@1?type=jar" and "pkg:maven/com.example/dependency@2?type=jar" where the later has a description "my description" a publisher "example" and hashes if the dependency has been retrieved.

      <cdx:componentbom
        <cdx:component>
          <cdx:ivyModule>
            <templateComponent
                name="dependency"
                group="com.example"
                publisher="Example"
              />
          </cdx:ivyModule>
        </cdx:component>
      </cdx:componentbom>
    

The following snippet adds two components to the SBOM with bom-refs "pkg:maven/org.example/module@1?type=jar" and "pkg:maven/com.example/dependency@3?type=jar" where the later has a description "another description" but no hashes (as the version doesn't match).

      <cdx:componentbom
        <cdx:component>
          <cdx:ivyModule>
            <templateComponent
                name="dependency"
                group="com.example"
                version="3"
                description="another description"
              />
          </cdx:ivyModule>
        </cdx:component>
      </cdx:componentbom>