document SBOM external references

CycloneDX · Jan 19, 2024 · aae4a13 · aae4a13
1 parent 98d4384
commit aae4a13
Show file tree

Hide file tree

Showing 7 changed files with 129 additions and 5 deletions.
diff --git a/src/main/java/org/cyclonedx/maven/BaseCycloneDxMojo.java b/src/main/java/org/cyclonedx/maven/BaseCycloneDxMojo.java
@@ -215,8 +215,19 @@ public abstract class BaseCycloneDxMojo extends AbstractMojo {
     private String outputTimestamp;
 
     /**
-     * External references to be added to <code>$.metadata.component.externalReferences[]</code>.
+     * <a href="https://cyclonedx.org/docs/1.5/json/#metadata_component_externalReferences_items_type">External references</a>
+     * to be added to the component the BOM describes <code>$.metadata.component.externalReferences[]</code>:
+     * <pre>
+     * &lt;externalReferences&gt;
+     *   &lt;externalReference&gt;
+     *     &lt;type>EXTERNAL_REFERENCE_TYPE&lt;/type&gt;&lt;-- constant id corresponding to "external-reference-type" SBOM type --&gt;
+     *     &lt;url>https://...&lt;/url&gt;
+     *     &lt;comment>(optional) comment&lt;/comment&gt;
+     *   &lt;/externalReference&gt;
+     * &lt;/externalReferences&gt;
+     * </pre>
      *
+     * @see <a href="https://cyclonedx.github.io/cyclonedx-core-java/org/cyclonedx/model/ExternalReference.Type.html">ExternalReference.Type constants</a>
      * @since 2.7.11
      */
     @Parameter

diff --git a/src/main/java/org/cyclonedx/maven/ProjectDependenciesConverter.java b/src/main/java/org/cyclonedx/maven/ProjectDependenciesConverter.java
@@ -38,6 +38,10 @@ public interface ProjectDependenciesConverter {
     /**
      * Check consistency between BOM components and BOM dependencies, and cleanup: drop components found while walking the
      * Maven dependency resolution graph but that are finally not kept in the effective dependencies list.
+     *
+     * @param metadata the SBOM metadata
+     * @param components the SBOM components
+     * @param dependencies the SBOM dependencies
      */
     void cleanupBomDependencies(Metadata metadata, Map<String, Component> components, Map<String, Dependency> dependencies);
 

diff --git a/src/site/markdown/external-references.md b/src/site/markdown/external-references.md
@@ -0,0 +1,57 @@
+External References
+===================
+
+Components described in SBOMs generated by the CycloneDX Maven Plugin contain a few fields and external
+references that are extracted from [Maven effective POMs][maven-model]:
+
+- of the current built `pom.xml` (with inheritance) for SBOM [`metadata.component`][metadata-component] = the component that the BOM describes,
+- of the Maven dependencies for SBOM [`components`][components].
+
+## SBOM Fields extracted from POM
+
+3 SBOM fields are deducted from effective POM (= after POM inheritance from parents):
+
+- `component.publisher` is filled with POM's `project.organisation.name`,
+- `component.description` is filled with POM's `project.description`,
+- `component.licenses[]` is filled with POM's `project.licenses[]`.
+
+## External References extracted from POM
+
+| [POM field][maven-model]                        | [External Reference type][external-reference-type]
+|-------------------------------------------------|--------------
+| `project.url`                                   | `website`
+| `project.scm.url`                               | `vcs`
+| `project.ciManagement.url`                      | `build-system`
+| `project.issueManagement.url`                   | `issue-tracker`
+| `project.mailingLists[].archive` or `subscribe` | `mailing-list`
+| `project.distributionManagement.repository.url` | `distribution`
+
+
+## Additional External References for `metadata.component`
+
+You can add more external references the component that the BOM describes by plugin configuration:
+
+```
+<plugin>
+  <groupId>org.cyclonedx</groupId>
+  <artifactId>cyclonedx-maven-plugin</artifactId>
+  <configuration>
+    <externalReferences>
+      <externalReference>
+        <type>EXTERNAL_REFERENCE_TYPE</type><-- for "external-reference-type"-->
+        <url>... value ...</url>
+        <comment>(optional) comment</comment>
+      </externalReference>
+    </externalReferences>
+  </configuration>
+</plugin>
+```
+
+Notice that the type value in the plugin configuration refers to a [CycloneDX Core (Java) library constant name][external-reference-type-constants]
+corresponding to [CycloneDX type][external-reference-type].
+
+[maven-model]: https://maven.apache.org/ref/current/maven-model/maven.html
+[metadata-component]: https://cyclonedx.org/docs/1.5/json/#metadata_component
+[components]: https://cyclonedx.org/docs/1.5/json/#components
+[external-reference-type]: https://cyclonedx.org/docs/1.5/json/#metadata_component_externalReferences_items_type
+[external-reference-type-constants]: https://cyclonedx.github.io/cyclonedx-core-java/org/cyclonedx/model/ExternalReference.Type.html
diff --git a/src/site/site.xml b/src/site/site.xml
@@ -41,6 +41,7 @@
           <!-- item name="Usage" href="usage.html"/>
           <item name="FAQ" href="faq.html"/ -->
           <item name="Javadoc" href="apidocs/index.html"/>
+          <item name="External References" href="external-references.html"/>
         </menu>
         <menu ref="reports"/>
     </body>

diff --git a/src/test/java/org/cyclonedx/maven/BomDependenciesTest.java b/src/test/java/org/cyclonedx/maven/BomDependenciesTest.java
@@ -215,7 +215,7 @@ private void checkTopLevelTestComponentsAsCompile(final File projDir) throws Exc
 
     /**
      * This test ensures that any <i>compile</i> dependencies hidden by excluded types are included in the BOM if they are visible dependencies
-     * @throws Exception
+     * @throws Exception if something unexpected happens
      */
     @Test
     public void testTypeExcludes() throws Exception {

diff --git a/src/test/java/org/cyclonedx/maven/Issue314OptionalTest.java b/src/test/java/org/cyclonedx/maven/Issue314OptionalTest.java
@@ -40,6 +40,7 @@ public Issue314OptionalTest(MavenRuntimeBuilder runtimeBuilder) throws Exception
     /**
      * Validate the bytecode analysis components.
      * - No component should be marked as optional
+     * @throws Exception if something unexpected happens
      */
     @Test
     public void testBytecodeDependencyTree() throws Exception {
@@ -78,6 +79,7 @@ public void testBytecodeDependencyTree() throws Exception {
      * Validate the maven optional components.
      * - com.example.issue_314:dependency_C:1.0.0 and com.example.issue_314:dependency_D:1.0.0 *should* be marked as optional
      * because dependency_A declares dependency_C as optional, which depends on dependency_D
+     * @throws Exception if something unexpected happens
      */
     @Test
     public void testMavenOptionalDependencyTree() throws Exception {

diff --git a/src/test/resources/external-reference/pom.xml b/src/test/resources/external-reference/pom.xml
@@ -10,13 +10,57 @@
     <packaging>pom</packaging>
     <version>${revision}</version>
 
-    <licenses>
+    <url>https://cyclonedx.org/acme</url><!-- automatically converted to "website" external reference -->
+    <description>description of the project</description><!-- automatically converted to component.description -->
+
+    <organization>
+        <name>OWASP Foundation</name><!-- automatically converted to component.publisher -->
+        <url>https://owasp.org/</url>
+    </organization>
+
+    <licenses><!-- automatically converted to component.licenses[] -->
         <license>
             <name>Apache-2.0</name>
             <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
         </license>
     </licenses>
 
+    <mailingLists><!-- automatically converted to "mailing-list" external references -->
+        <mailingList>
+            <name>dev ML</name>
+            <archive>https://dev.ml.cyclonedx.org/archive</archive>
+            <subscribe>https://dev.ml.cyclonedx.org/subscribe</subscribe>
+        </mailingList>
+        <mailingList>
+            <name>user ML</name>
+            <subscribe>https://user.ml.cyclonedx.org/subscribe</subscribe>
+        </mailingList>
+    </mailingLists>
+
+    <scm>
+        <connection>scm:git:git@github.com:CycloneDX/cyclonedx-maven-plugin.git</connection>
+        <url>https://github.com/CycloneDX/cyclonedx-maven-plugin.git</url><!-- automatically converted to "vcs" external reference -->
+        <developerConnection>scm:git:git@github.com:CycloneDX/cyclonedx-maven-plugin.git</developerConnection>
+        <tag>HEAD</tag>
+    </scm>
+
+    <issueManagement><!-- automatically converted to "issue-tracker" external reference -->
+        <system>GitHub</system>
+        <url>https://github.com/CycloneDX/cyclonedx-maven-plugin/issues</url>
+    </issueManagement>
+
+    <ciManagement><!-- automatically converted to "build-system" external reference -->
+        <system>GitHub</system>
+        <url>https://github.com/CycloneDX/cyclonedx-maven-plugin/actions</url>
+    </ciManagement>
+
+    <distributionManagement>
+        <repository><!-- automatically converted to "distribution" external reference -->
+            <id>ossrh</id>
+            <url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</url>
+        </repository>
+    </distributionManagement>
+
     <properties>
         <revision>1.0.0</revision>
         <maven.compiler.source>8</maven.compiler.source>
@@ -44,10 +88,15 @@
                         <phase>verify</phase>
                         <configuration>
                             <outputFormat>json</outputFormat>
-                            <externalReferences>
+                            <externalReferences><!-- additional configured external references -->
                                 <externalReference>
-                                    <type>CHAT</type>
+                                    <type>CHAT</type><!-- Java ExternalReference.Type constant for "chat" CycloneDX external reference type -->
                                     <url>https://acme.com/parent</url>
+                                    <comment>optional comment</comment>
+                                </externalReference>
+                                <externalReference>
+                                    <type>RELEASE_NOTES</type><!-- Java ExternalReference.Type constant for "release-notes" CycloneDX external reference type -->
+                                    <url>https://github.com/CycloneDX/cyclonedx-maven-plugin/releases</url>
                                 </externalReference>
                             </externalReferences>
                         </configuration>