Skip to content

Commit 6fc0585

Browse files
stevespringettstevespringett
authored
Merge pull request #212 from CycloneDX/v1.5-dev-composition-expansion
Added additional compositions and identity
2 parents b816b76 + db06aba commit 6fc0585

File tree

6 files changed

+131
-12
lines changed

6 files changed

+131
-12
lines changed

‎schema/bom-1.5.proto‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ message Bom {
2929
repeated ExternalReference external_references = 7;
3030
// Provides the ability to document dependency relationships.
3131
repeated Dependency dependencies = 8;
32-
// Provides the ability to document aggregate completeness
32+
// 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.
3333
repeated Composition compositions = 9;
3434
// Vulnerabilities identified in components or services.
3535
repeated Vulnerability vulnerabilities = 10;
@@ -557,18 +557,26 @@ message Property {
557557
}
558558

559559
enum Aggregate {
560-
// Default, no statement about the aggregate completeness is being made
560+
// The relationship completeness is not specified.
561561
AGGREGATE_NOT_SPECIFIED = 0;
562-
// The aggregate composition is complete
562+
// The relationship is complete. No further relationships including constituent components, services, or dependencies are known to exist.
563563
AGGREGATE_COMPLETE = 1;
564-
// The aggregate composition is incomplete
564+
// The relationship is incomplete. Additional relationships exist and may include constituent components, services, or dependencies.
565565
AGGREGATE_INCOMPLETE = 2;
566-
// The aggregate composition is incomplete for first party components, complete for third party components
566+
// The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented.
567567
AGGREGATE_INCOMPLETE_FIRST_PARTY_ONLY = 3;
568-
// The aggregate composition is incomplete for third party components, complete for first party components
568+
// The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented.
569569
AGGREGATE_INCOMPLETE_THIRD_PARTY_ONLY = 4;
570-
// The aggregate composition completeness is unknown
570+
// 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.
571571
AGGREGATE_UNKNOWN = 5;
572+
// The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.
573+
AGGREGATE_INCOMPLETE_FIRST_PARTY_PROPRIETARY_ONLY = 6;
574+
// The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented, limited specifically to those that are opensource.
575+
AGGREGATE_INCOMPLETE_FIRST_PARTY_OPENSOURCE_ONLY = 7;
576+
// The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.
577+
AGGREGATE_INCOMPLETE_THIRD_PARTY_PROPRIETARY_ONLY = 8;
578+
// The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource.
579+
AGGREGATE_INCOMPLETE_THIRD_PARTY_OPENSOURCE_ONLY = 9;
572580
}
573581

574582
message Composition {
@@ -578,6 +586,10 @@ message Composition {
578586
repeated string assemblies = 2;
579587
// The dependencies the aggregate completeness applies to
580588
repeated string dependencies = 3;
589+
// The bom-ref identifiers of the vulnerabilities being described.
590+
repeated string vulnerabilities = 4;
591+
// An optional identifier which can be used to reference the composition elsewhere in the BOM. Every bom-ref MUST be unique within the BOM.
592+
optional string bom_ref = 5;
581593
}
582594

583595
message EvidenceCopyright {

‎schema/bom-1.5.schema.json‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@
8787
"items": {"$ref": "#/definitions/compositions"},
8888
"uniqueItems": true,
8989
"title": "Compositions",
90-
"description": "Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness."
90+
"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."
9191
},
9292
"vulnerabilities": {
9393
"type": "array",
@@ -1524,10 +1524,15 @@
15241524
],
15251525
"additionalProperties": false,
15261526
"properties": {
1527+
"bom-ref": {
1528+
"$ref": "#/definitions/refType",
1529+
"title": "BOM Reference",
1530+
"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."
1531+
},
15271532
"aggregate": {
15281533
"$ref": "#/definitions/aggregateType",
15291534
"title": "Aggregate",
1530-
"description": "Specifies an aggregate type that describe how complete a relationship is."
1535+
"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"
15311536
},
15321537
"assemblies": {
15331538
"type": "array",
@@ -1547,6 +1552,15 @@
15471552
"title": "BOM references",
15481553
"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."
15491554
},
1555+
"vulnerabilities": {
1556+
"type": "array",
1557+
"uniqueItems": true,
1558+
"items": {
1559+
"type": "string"
1560+
},
1561+
"title": "BOM references",
1562+
"description": "The bom-ref identifiers of the vulnerabilities being described."
1563+
},
15501564
"signature": {
15511565
"$ref": "#/definitions/signature",
15521566
"title": "Signature",
@@ -1561,7 +1575,11 @@
15611575
"complete",
15621576
"incomplete",
15631577
"incomplete_first_party_only",
1578+
"incomplete_first_party_proprietary_only",
1579+
"incomplete_first_party_opensource_only",
15641580
"incomplete_third_party_only",
1581+
"incomplete_third_party_proprietary_only",
1582+
"incomplete_third_party_opensource_only",
15651583
"unknown",
15661584
"not_specified"
15671585
]

‎schema/bom-1.5.xsd‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2182,14 +2182,41 @@ limitations under the License.
21822182
</xs:sequence>
21832183
</xs:complexType>
21842184
</xs:element>
2185+
<xs:element name="vulnerabilities" minOccurs="0" maxOccurs="1">
2186+
<xs:annotation>
2187+
<xs:documentation>
2188+
The bom-ref identifiers of the vulnerabilities being described.
2189+
</xs:documentation>
2190+
</xs:annotation>
2191+
<xs:complexType>
2192+
<xs:sequence minOccurs="0" maxOccurs="unbounded">
2193+
<xs:element name="vulnerability" type="bom:bomReferenceType"/>
2194+
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded">
2195+
<xs:annotation>
2196+
<xs:documentation>
2197+
Allows any undeclared elements as long as the elements are placed in a different namespace.
2198+
</xs:documentation>
2199+
</xs:annotation>
2200+
</xs:any>
2201+
</xs:sequence>
2202+
</xs:complexType>
2203+
</xs:element>
21852204
</xs:sequence>
2205+
<xs:attribute name="bom-ref" type="bom:refType">
2206+
<xs:annotation>
2207+
<xs:documentation>
2208+
An optional identifier which can be used to reference the composition elsewhere in the BOM.
2209+
Uniqueness is enforced within all elements and children of the root-level bom element.
2210+
</xs:documentation>
2211+
</xs:annotation>
2212+
</xs:attribute>
21862213
</xs:complexType>
21872214

21882215
<xs:simpleType name="aggregateType">
21892216
<xs:restriction base="xs:string">
21902217
<xs:enumeration value="complete">
21912218
<xs:annotation>
2192-
<xs:documentation>The relationship is complete. No further relationships including constituent components, services, or dependencies exist.</xs:documentation>
2219+
<xs:documentation>The relationship is complete. No further relationships including constituent components, services, or dependencies are known to exist.</xs:documentation>
21932220
</xs:annotation>
21942221
</xs:enumeration>
21952222
<xs:enumeration value="incomplete">
@@ -2202,11 +2229,31 @@ limitations under the License.
22022229
<xs:documentation>The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented.</xs:documentation>
22032230
</xs:annotation>
22042231
</xs:enumeration>
2232+
<xs:enumeration value="incomplete_first_party_proprietary_only">
2233+
<xs:annotation>
2234+
<xs:documentation>The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.</xs:documentation>
2235+
</xs:annotation>
2236+
</xs:enumeration>
2237+
<xs:enumeration value="incomplete_first_party_opensource_only">
2238+
<xs:annotation>
2239+
<xs:documentation>The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource.</xs:documentation>
2240+
</xs:annotation>
2241+
</xs:enumeration>
22052242
<xs:enumeration value="incomplete_third_party_only">
22062243
<xs:annotation>
22072244
<xs:documentation>The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented.</xs:documentation>
22082245
</xs:annotation>
22092246
</xs:enumeration>
2247+
<xs:enumeration value="incomplete_third_party_proprietary_only">
2248+
<xs:annotation>
2249+
<xs:documentation>The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary.</xs:documentation>
2250+
</xs:annotation>
2251+
</xs:enumeration>
2252+
<xs:enumeration value="incomplete_third_party_opensource_only">
2253+
<xs:annotation>
2254+
<xs:documentation>The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource.</xs:documentation>
2255+
</xs:annotation>
2256+
</xs:enumeration>
22102257
<xs:enumeration value="unknown">
22112258
<xs:annotation>
22122259
<xs:documentation>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.</xs:documentation>
@@ -3864,7 +3911,7 @@ limitations under the License.
38643911
</xs:element>
38653912
<xs:element name="compositions" type="bom:compositionsType" minOccurs="0" maxOccurs="1">
38663913
<xs:annotation>
3867-
<xs:documentation>Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness.</xs:documentation>
3914+
<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>
38683915
</xs:annotation>
38693916
</xs:element>
38703917
<xs:element name="properties" type="bom:propertiesType" minOccurs="0" maxOccurs="1">

‎tools/src/test/resources/1.5/valid-compositions-1.5.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,18 @@
4444
]
4545
}
4646
],
47+
"vulnerabilities": [
48+
{
49+
"bom-ref": "vulnerability-1",
50+
"id": "ACME-12345",
51+
"source": {
52+
"name": "Acme Inc"
53+
}
54+
}
55+
],
4756
"compositions": [
4857
{
58+
"bom-ref": "composition-1",
4959
"aggregate": "complete",
5060
"assemblies": [
5161
"pkg:maven/partner/[email protected]"
@@ -59,6 +69,12 @@
5969
"assemblies": [
6070
"pkg:maven/acme/[email protected]"
6171
]
72+
},
73+
{
74+
"aggregate": "incomplete_first_party_only",
75+
"vulnerabilities": [
76+
"vulnerability-1"
77+
]
6278
}
6379
]
6480
}

‎tools/src/test/resources/1.5/valid-compositions-1.5.textproto‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ dependencies {
3939
}
4040
}
4141
compositions {
42+
bom_ref: "composition-1"
4243
aggregate: AGGREGATE_COMPLETE
4344
assemblies: "pkg:maven/partner/[email protected]"
4445
dependencies: "acme-application-1.0"
@@ -47,3 +48,14 @@ compositions {
4748
aggregate: AGGREGATE_UNKNOWN
4849
assemblies: "pkg:maven/acme/[email protected]"
4950
}
51+
compositions {
52+
aggregate: AGGREGATE_INCOMPLETE_FIRST_PARTY_ONLY,
53+
vulnerabilities: "vulnerability-1"
54+
}
55+
vulnerabilities {
56+
bom_ref: "vulnerability-1"
57+
id: "ACME-12345"
58+
source: {
59+
name: "Acme Inc"
60+
}
61+
}

‎tools/src/test/resources/1.5/valid-compositions-1.5.xml‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
</dependency>
3333
</dependencies>
3434
<compositions>
35-
<composition>
35+
<composition bom-ref="composition-1">
3636
<aggregate>complete</aggregate>
3737
<assemblies>
3838
<assembly ref="pkg:maven/partner/[email protected]"/>
@@ -47,5 +47,19 @@
4747
<assembly ref="pkg:maven/acme/[email protected]"/>
4848
</assemblies>
4949
</composition>
50+
<composition>
51+
<aggregate>incomplete_first_party_only</aggregate>
52+
<assemblies>
53+
<assembly ref="vulnerability-1"/>
54+
</assemblies>
55+
</composition>
5056
</compositions>
57+
<vulnerabilities>
58+
<vulnerability bom-ref="vulnerability-1">
59+
<id>ACME-12345</id>
60+
<source>
61+
<name>Acme Inc</name>
62+
</source>
63+
</vulnerability>
64+
</vulnerabilities>
5165
</bom>

0 commit comments

Comments
 (0)