diff --git a/schema/bom-1.5.proto b/schema/bom-1.5.proto index 50f5ada5..e84ce7ba 100644 --- 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; @@ -545,18 +545,26 @@ message Property { } enum Aggregate { - // Default, no statement about the aggregate completeness is being made + // The relationship completeness is not specified. AGGREGATE_NOT_SPECIFIED = 0; - // The aggregate composition is complete + // The relationship is complete. No further relationships including constituent components, services, or dependencies are known to exist. AGGREGATE_COMPLETE = 1; - // The aggregate composition is incomplete + // The relationship is incomplete. Additional relationships exist and may include constituent components, services, or dependencies. AGGREGATE_INCOMPLETE = 2; - // The aggregate composition is incomplete for first party components, complete for third party components + // The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented. AGGREGATE_INCOMPLETE_FIRST_PARTY_ONLY = 3; - // The aggregate composition is incomplete for third party components, complete for first party components + // The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented. AGGREGATE_INCOMPLETE_THIRD_PARTY_ONLY = 4; - // The aggregate composition completeness is unknown + // The relationship may be complete or incomplete. This usually signifies a 'best-effort' to obtain constituent components, services, or dependencies but the completeness is inconclusive. AGGREGATE_UNKNOWN = 5; + // The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are proprietary. + AGGREGATE_INCOMPLETE_FIRST_PARTY_PROPRIETARY_ONLY = 6; + // The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are opensource. + AGGREGATE_INCOMPLETE_FIRST_PARTY_OPENSOURCE_ONLY = 7; + // The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary. + AGGREGATE_INCOMPLETE_THIRD_PARTY_PROPRIETARY_ONLY = 8; + // The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource. + AGGREGATE_INCOMPLETE_THIRD_PARTY_OPENSOURCE_ONLY = 9; } message Composition { @@ -566,6 +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 = 5; } message EvidenceCopyright { diff --git a/schema/bom-1.5.schema.json b/schema/bom-1.5.schema.json index c72e5e42..fd19641e 100644 --- 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", @@ -1511,10 +1511,15 @@ ], "additionalProperties": false, "properties": { + "bom-ref": { + "$ref": "#/definitions/refType", + "title": "BOM Reference", + "description": "An optional identifier which can be used to reference the composition elsewhere in the BOM. Every bom-ref MUST be unique within the BOM." + }, "aggregate": { "$ref": "#/definitions/aggregateType", "title": "Aggregate", - "description": "Specifies an aggregate type that describe how complete a relationship is." + "description": "Specifies an aggregate type that describe how complete a relationship is.\n\n* __complete__ = The relationship is complete. No further relationships including constituent components, services, or dependencies are known to exist.\n* __incomplete__ = The relationship is incomplete. Additional relationships exist and may include constituent components, services, or dependencies.\n* __incomplete_first_party_only__ = The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented.\n* __incomplete_first_party_proprietary_only__ = The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.\n* __incomplete_first_party_opensource_only__ = The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are opensource.\n* __incomplete_third_party_only__ = The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented.\n* __incomplete_third_party_proprietary_only__ = The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.\n* __incomplete_third_party_opensource_only__ = The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource.\n* __unknown__ = The relationship may be complete or incomplete. This usually signifies a 'best-effort' to obtain constituent components, services, or dependencies but the completeness is inconclusive.\n* __not_specified__ = The relationship completeness is not specified.\n" }, "assemblies": { "type": "array", @@ -1534,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", @@ -1548,7 +1562,11 @@ "complete", "incomplete", "incomplete_first_party_only", + "incomplete_first_party_proprietary_only", + "incomplete_first_party_opensource_only", "incomplete_third_party_only", + "incomplete_third_party_proprietary_only", + "incomplete_third_party_opensource_only", "unknown", "not_specified" ] diff --git a/schema/bom-1.5.xsd b/schema/bom-1.5.xsd index bd7c708d..7a981583 100644 --- a/schema/bom-1.5.xsd +++ b/schema/bom-1.5.xsd @@ -2141,14 +2141,41 @@ limitations under the License. + + + + The bom-ref identifiers of the vulnerabilities being described. + + + + + + + + + Allows any undeclared elements as long as the elements are placed in a different namespace. + + + + + + + + + + An optional identifier which can be used to reference the composition elsewhere in the BOM. + Uniqueness is enforced within all elements and children of the root-level bom element. + + + - The relationship is complete. No further relationships including constituent components, services, or dependencies exist. + The relationship is complete. No further relationships including constituent components, services, or dependencies are known to exist. @@ -2161,11 +2188,31 @@ limitations under the License. The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented. + + + The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary. + + + + + The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource. + + The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented. + + + The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary. + + + + + The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource. + + The relationship may be complete or incomplete. This usually signifies a 'best-effort' to obtain constituent components, services, or dependencies but the completeness is inconclusive. @@ -3185,7 +3232,7 @@ limitations under the License. - Compositions describe constituent parts (including components, services, and dependency relationships) and their 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. 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 index 551834e0..11c8a001 100644 --- 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,8 +44,18 @@ ] } ], + "vulnerabilities": [ + { + "bom-ref": "vulnerability-1", + "id": "ACME-12345", + "source": { + "name": "Acme Inc" + } + } + ], "compositions": [ { + "bom-ref": "composition-1", "aggregate": "complete", "assemblies": [ "pkg:maven/partner/shaded-library@1.0" @@ -59,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 index d29b94fe..bc542cf4 100644 --- a/tools/src/test/resources/1.5/valid-compositions-1.5.textproto +++ b/tools/src/test/resources/1.5/valid-compositions-1.5.textproto @@ -39,6 +39,7 @@ dependencies { } } compositions { + bom_ref: "composition-1" aggregate: AGGREGATE_COMPLETE assemblies: "pkg:maven/partner/shaded-library@1.0" dependencies: "acme-application-1.0" @@ -47,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 index 82c16c55..99204878 100644 --- a/tools/src/test/resources/1.5/valid-compositions-1.5.xml +++ b/tools/src/test/resources/1.5/valid-compositions-1.5.xml @@ -32,7 +32,7 @@ - + complete @@ -47,5 +47,19 @@ + + incomplete_first_party_only + + + + + + + ACME-12345 + + Acme Inc + + +