feat: Add support for TLP marking in metadata (fixes #595)

schema/bom-1.7.proto

@@ -514,6 +514,8 @@ message Metadata {
   repeated Lifecycles lifecycles = 9;
   // The organization that created the BOM. Manufacturer is common in BOMs created through automated processes. BOMs created through manual means may have '.authors' instead.
   optional OrganizationalEntity manufacturer = 10;
+  // The Traffic Light Protocol (TLP) classification that controls the sharing and distribution of the component that the BOM describes.
+  optional Tlp distribution = 11;
 }
 
 message Lifecycles {
@@ -675,6 +677,20 @@ message Swid {
   optional string url = 7;
 }
 
+// The Traffic Light Protocol (TLP) classification for the component that the BOM describes. TLP is a classification system for identifying the potential risk associated with artefact, including whether it is subject to certain types of legal, financial, or technical threats. Refer to https://www.first.org/tlp/ for further information. The default classification is `TLP_CLEAR`
+enum Tlp {
+  // buf:lint:ignore ENUM_ZERO_VALUE_SUFFIX -- `TLP_CLEAR` is our fallback, the default.
+  TLP_CLEAR_UNSPECIFIED = 0;
+  // Limited distribution but can be shared within a community.
+  TLP_GREEN = 1;
+  // Limited distribution but can be shared within an organization and with clients
+  TLP_AMBER = 2;
+  // Limited distribution but can be shared within an organization.
+  TLP_AMBER_AND_STRICT = 3;
+  // Restricted distribution to individual recipients and must not be shared.
+  TLP_RED = 4;
+}
+
 // Specifies a tool (manual or automated).
 message Tool {
   // DEPRECATED - DO NOT USE - The vendor of the tool used to create the BOM.

schema/bom-1.7.schema.json

@@ -712,9 +712,34 @@
           "title": "Properties",
           "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.",
           "items": {"$ref": "#/definitions/property"}
+        },
+        "distribution": {
+          "title": "Distribution",
+          "description": "The Traffic Light Protocol (TLP) classification that controls the sharing and distribution of the component that the BOM describes.",
+          "$ref": "#/definitions/tlpClassification"
         }
       }
     },
+    "tlpClassification": {
+      "type" : "string",
+      "default": "CLEAR",
+      "title": "Traffic Light Protocol (TLP) Classification",
+      "description": "The Traffic Light Protocol (TLP) classification for the component that the BOM describes. TLP is a classification system for identifying the potential risk associated with artefact, including whether it is subject to certain types of legal, financial, or technical threats. Refer to [https://www.first.org/tlp/](https://www.first.org/tlp/) for further information. The default classification is CLEAR",
+      "enum": [
+        "AMBER",
+        "AMBER_AND_STRICT",
+        "GREEN",
+        "RED",
+        "CLEAR"
+      ],
+      "meta:enum": {
+        "AMBER": "The BOM is subject to limited disclosure, and recipients can only share the BOM on a need-to-know basis within their organization and with clients.",
+        "AMBER_AND_STRICT": "The BOM is subject to limited disclosure, and recipients can only share the BOM on a need-to-know basis within their organization.",
+        "GREEN": "The BOM is subject to limited disclosure, and recipients can share the BOM within their community but not via publicly accessible channels.",
+        "RED": "The BOM is subject to restricted distribution to individual recipients only and must not be shared.",
+        "CLEAR": "The BOM is not subject to any restrictions as regards the sharing of the information within the BOM."
+      }
+    },
     "tool": {
       "type": "object",
       "title": "Tool",

schema/bom-1.7.xsd

@@ -256,6 +256,12 @@ limitations under the License.
                         Formal registration is optional.</xs:documentation>
                 </xs:annotation>
             </xs:element>
+            <xs:element name="distribution" type="bom:tlpType" minOccurs="0" maxOccurs="1">
+                <xs:annotation>
+                    <xs:documentation>The Traffic Light Protocol (TLP) classification that controls the sharing and distribution
+                        of the component that the BOM describes.</xs:documentation>
+                </xs:annotation>
+            </xs:element>
             <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">
                 <xs:annotation>
                     <xs:documentation>
@@ -390,6 +396,57 @@ limitations under the License.
         </xs:anyAttribute>
     </xs:complexType>
 
+    <xs:simpleType name="tlpType" default="CLEAR">
+        <xs:annotation>
+            <xs:documentation xml:lang="en">
+                The Traffic Light Protocol (TLP) classification for the component that the BOM describes. TLP is a classification
+                system for identifying the potential risk associated with artefact, including whether it is subject to certain
+                types of legal, financial, or technical threats. Refer to https://www.first.org/tlp/ for further information.
+                The default classification is CLEAR.
+            </xs:documentation>
+        </xs:annotation>
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="CLEAR">
+                <xs:annotation>
+                    <xs:documentation>
+                        The BOM is not subject to any restrictions as regards the sharing of the information within the BOM.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:enumeration>
+            <xs:enumeration value="GREEN">
+                <xs:annotation>
+                    <xs:documentation>
+                        The BOM is subject to limited disclosure, and recipients can share the BOM within their community
+                        but not via publicly accessible channels.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:enumeration>
+            <xs:enumeration value="AMBER">
+                <xs:annotation>
+                    <xs:documentation>
+                        The BOM is subject to limited disclosure, and recipients can only share the BOM on a need-to-know
+                        basis within their organization and with clients.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:enumeration>
+            <xs:enumeration value="AMBER_AND_STRICT">
+                <xs:annotation>
+                    <xs:documentation>
+                        The BOM is subject to limited disclosure, and recipients can only share the BOM on a need-to-know
+                        basis within their organization.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:enumeration>
+            <xs:enumeration value="RED">
+                <xs:annotation>
+                    <xs:documentation>
+                        The BOM is subject to restricted distribution to individual recipients only and must not be shared.
+                    </xs:documentation>
+                </xs:annotation>
+            </xs:enumeration>
+         </xs:restriction>
+    </xs:simpleType>
+
     <xs:complexType name="toolType">
         <xs:annotation>
             <xs:documentation>Information about the automated or manual tool used</xs:documentation>

tools/src/test/resources/1.7/invalid-metadata-distribution-1.7.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://cyclonedx.org/schema/bom-1.7.schema.json",
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.7",
+  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
+  "version": 1,
+  "metadata": {
+    "distribution": "Unrestricted"
+  },
+  "components": []
+}

tools/src/test/resources/1.7/invalid-metadata-distribution-1.7.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<bom serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1" xmlns="http://cyclonedx.org/schema/bom/1.7">
+    <metadata>
+        <distribution>Unrestricted</distribution>
+    </metadata>
+    <components />
+</bom>

tools/src/test/resources/1.7/valid-metadata-distribution-1.7.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://cyclonedx.org/schema/bom-1.7.schema.json",
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.7",
+  "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
+  "version": 1,
+  "metadata": {
+    "distribution": "CLEAR"
+  },
+  "components": []
+}

tools/src/test/resources/1.7/valid-metadata-distribution-1.7.textproto

@@ -0,0 +1,9 @@
+# proto-file: schema/bom-1.7.proto
+# proto-message: Bom
+
+spec_version: "1.7"
+version: 1
+serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79"
+metadata {
+  distribution: CLEAR
+}

tools/src/test/resources/1.7/valid-metadata-distribution-1.7.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<bom serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1" xmlns="http://cyclonedx.org/schema/bom/1.7">
+    <metadata>
+        <distribution>CLEAR</distribution>
+    </metadata>
+    <components />
+</bom>