Added vulnerability composition support to allow for specifying the completeness and aggregate of vulnerabilities defined in a BOM. Updated test cases.

stevespringett · stevespringett · commit db06aba7e934 · 2023-04-25T12:58:35.000-05:00
Signed-off-by: Steve Springett &lt;steve@springett.us&gt;
diff --git a/schema/bom-1.5.proto b/schema/bom-1.5.proto
@@ -29,7 +29,7 @@ message Bom {
   repeated ExternalReference external_references = 7;
   // Provides the ability to document dependency relationships.
   repeated Dependency dependencies = 8;
-  // Provides the ability to document aggregate completeness
+  // Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness. The completeness of vulnerabilities expressed in a BOM may also be described.
   repeated Composition compositions = 9;
   // Vulnerabilities identified in components or services.
   repeated Vulnerability vulnerabilities = 10;
@@ -574,8 +574,10 @@ message Composition {
   repeated string assemblies = 2;
   // The dependencies the aggregate completeness applies to
   repeated string dependencies = 3;
+  // The bom-ref identifiers of the vulnerabilities being described.
+  repeated string vulnerabilities = 4;
   // An optional identifier which can be used to reference the composition elsewhere in the BOM. Every bom-ref MUST be unique within the BOM.
-  optional string bom_ref = 4;
+  optional string bom_ref = 5;
 }
 
 message EvidenceCopyright {
diff --git a/schema/bom-1.5.schema.json b/schema/bom-1.5.schema.json
@@ -87,7 +87,7 @@
       "items": {"$ref": "#/definitions/compositions"},
       "uniqueItems": true,
       "title": "Compositions",
-      "description": "Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness."
+      "description": "Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness. The completeness of vulnerabilities expressed in a BOM may also be described."
     },
     "vulnerabilities": {
       "type": "array",
@@ -1539,6 +1539,15 @@
           "title": "BOM references",
           "description": "The bom-ref identifiers of the components or services being described. Dependencies refer to a relationship whereby an independent constituent part requires another independent constituent part. References do not cascade to transitive dependencies. References are explicit for the specified dependency only."
         },
+        "vulnerabilities": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string"
+          },
+          "title": "BOM references",
+          "description": "The bom-ref identifiers of the vulnerabilities being described."
+        },
         "signature": {
           "$ref": "#/definitions/signature",
           "title": "Signature",
diff --git a/schema/bom-1.5.xsd b/schema/bom-1.5.xsd
@@ -2141,6 +2141,25 @@ limitations under the License.
                     </xs:sequence>
                 </xs:complexType>
             </xs:element>
+            <xs:element name="vulnerabilities" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>
+                        The bom-ref identifiers of the vulnerabilities being described.
+                    </xs:documentation>
+                </xs:annotation>
+                <xs:complexType>
+                    <xs:sequence minOccurs="0" maxOccurs="unbounded">
+                        <xs:element name="vulnerability" type="bom:bomReferenceType"/>
+                        <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">
+                            <xs:annotation>
+                                <xs:documentation>
+                                    Allows any undeclared elements as long as the elements are placed in a different namespace.
+                                </xs:documentation>
+                            </xs:annotation>
+                        </xs:any>
+                    </xs:sequence>
+                </xs:complexType>
+            </xs:element>
         </xs:sequence>
         <xs:attribute name="bom-ref" type="bom:refType">
             <xs:annotation>
@@ -3213,7 +3232,7 @@ limitations under the License.
                 </xs:element>
                 <xs:element name="compositions" type="bom:compositionsType" minOccurs="0" maxOccurs="1">
                     <xs:annotation>
-                        <xs:documentation>Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness.</xs:documentation>
+                        <xs:documentation>Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness. The completeness of vulnerabilities expressed in a BOM may also be described.</xs:documentation>
                     </xs:annotation>
                 </xs:element>
                 <xs:element name="properties" type="bom:propertiesType" minOccurs="0" maxOccurs="1">
diff --git a/tools/src/test/resources/1.5/valid-compositions-1.5.json b/tools/src/test/resources/1.5/valid-compositions-1.5.json
@@ -44,6 +44,15 @@
       ]
     }
   ],
+  "vulnerabilities": [
+    {
+      "bom-ref": "vulnerability-1",
+      "id": "ACME-12345",
+      "source": {
+        "name": "Acme Inc"
+      }
+    }
+  ],
   "compositions": [
     {
       "bom-ref": "composition-1",
@@ -60,6 +69,12 @@
       "assemblies": [
         "pkg:maven/acme/library@3.0"
       ]
+    },
+    {
+      "aggregate": "incomplete_first_party_only",
+      "vulnerabilities": [
+        "vulnerability-1"
+      ]
     }
   ]
 }
diff --git a/tools/src/test/resources/1.5/valid-compositions-1.5.textproto b/tools/src/test/resources/1.5/valid-compositions-1.5.textproto
@@ -48,3 +48,14 @@ compositions {
   aggregate: AGGREGATE_UNKNOWN
   assemblies: "pkg:maven/acme/library@3.0"
 }
+compositions {
+  aggregate: AGGREGATE_INCOMPLETE_FIRST_PARTY_ONLY,
+  vulnerabilities: "vulnerability-1"
+}
+vulnerabilities {
+  bom_ref: "vulnerability-1"
+  id: "ACME-12345"
+  source: {
+    name: "Acme Inc"
+  }
+}
diff --git a/tools/src/test/resources/1.5/valid-compositions-1.5.xml b/tools/src/test/resources/1.5/valid-compositions-1.5.xml
@@ -47,5 +47,19 @@
                 <assembly ref="pkg:maven/acme/library@3.0"/>
             </assemblies>
         </composition>
+        <composition>
+            <aggregate>incomplete_first_party_only</aggregate>
+            <assemblies>
+                <assembly ref="vulnerability-1"/>
+            </assemblies>
+        </composition>
     </compositions>
+    <vulnerabilities>
+        <vulnerability bom-ref="vulnerability-1">
+            <id>ACME-12345</id>
+            <source>
+                <name>Acme Inc</name>
+            </source>
+        </vulnerability>
+    </vulnerabilities>
 </bom>

Original file line number	Diff line number	Diff line change
`@@ -44,6 +44,15 @@`
`44`	`44`	`]`
`45`	`45`	`}`
`46`	`46`	`],`
	`47`	`+ "vulnerabilities": [`
	`48`	`+ {`
	`49`	`+ "bom-ref": "vulnerability-1",`
	`50`	`+ "id": "ACME-12345",`
	`51`	`+ "source": {`
	`52`	`+ "name": "Acme Inc"`
	`53`	`+ }`
	`54`	`+ }`
	`55`	`+ ],`
`47`	`56`	`"compositions": [`
`48`	`57`	`{`
`49`	`58`	`"bom-ref": "composition-1",`
`@@ -60,6 +69,12 @@`
`60`	`69`	`"assemblies": [`
`61`	`70`	`"pkg:maven/acme/[email protected]"`
`62`	`71`	`]`
	`72`	`+ },`
	`73`	`+ {`
	`74`	`+ "aggregate": "incomplete_first_party_only",`
	`75`	`+ "vulnerabilities": [`
	`76`	`+ "vulnerability-1"`
	`77`	`+ ]`
`63`	`78`	`}`
`64`	`79`	`]`
`65`	`80`	`}`