Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added additional compositions and identity #212

Merged
merged 6 commits into from
May 24, 2023
Merged

Added additional compositions and identity #212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
430826a
Added additional composition types, bom-ref, and updated docs.
stevespringett Apr 25, 2023
7e3070f
Corrected JSON docs
stevespringett Apr 25, 2023
f0df2d2
Updating test cases to show that bom-ref for compositions are optional
stevespringett Apr 25, 2023
332a05f
Updated docs
stevespringett Apr 25, 2023
4acfa29
Revert "Updated docs"
stevespringett Apr 25, 2023
db06aba
Added vulnerability composition support to allow for specifying the c…
stevespringett Apr 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 19 additions & 7 deletions schema/bom-1.5.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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 {
Expand All @@ -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 {
Expand Down
22 changes: 20 additions & 2 deletions schema/bom-1.5.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand All @@ -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"
]
Expand Down
51 changes: 49 additions & 2 deletions schema/bom-1.5.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2141,14 +2141,41 @@ 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>
<xs:documentation>
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.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>

<xs:simpleType name="aggregateType">
<xs:restriction base="xs:string">
<xs:enumeration value="complete">
<xs:annotation>
<xs:documentation>The relationship is complete. No further relationships including constituent components, services, or dependencies exist.</xs:documentation>
<xs:documentation>The relationship is complete. No further relationships including constituent components, services, or dependencies are known to exist.</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="incomplete">
Expand All @@ -2161,11 +2188,31 @@ limitations under the License.
<xs:documentation>The relationship is incomplete. Only relationships for first-party components, services, or their dependencies are represented.</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="incomplete_first_party_proprietary_only">
<xs:annotation>
<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>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="incomplete_first_party_opensource_only">
<xs:annotation>
<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>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="incomplete_third_party_only">
<xs:annotation>
<xs:documentation>The relationship is incomplete. Only relationships for third-party components, services, or their dependencies are represented.</xs:documentation>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="incomplete_third_party_proprietary_only">
<xs:annotation>
<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>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="incomplete_third_party_opensource_only">
<xs:annotation>
<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>
</xs:annotation>
</xs:enumeration>
<xs:enumeration value="unknown">
<xs:annotation>
<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>
Expand Down Expand Up @@ -3185,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">
Expand Down
16 changes: 16 additions & 0 deletions tools/src/test/resources/1.5/valid-compositions-1.5.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/[email protected]"
Expand All @@ -59,6 +69,12 @@
"assemblies": [
"pkg:maven/acme/[email protected]"
]
},
{
"aggregate": "incomplete_first_party_only",
"vulnerabilities": [
"vulnerability-1"
]
}
]
}
12 changes: 12 additions & 0 deletions tools/src/test/resources/1.5/valid-compositions-1.5.textproto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ dependencies {
}
}
compositions {
bom_ref: "composition-1"
aggregate: AGGREGATE_COMPLETE
assemblies: "pkg:maven/partner/[email protected]"
dependencies: "acme-application-1.0"
Expand All @@ -47,3 +48,14 @@ compositions {
aggregate: AGGREGATE_UNKNOWN
assemblies: "pkg:maven/acme/[email protected]"
}
compositions {
aggregate: AGGREGATE_INCOMPLETE_FIRST_PARTY_ONLY,
vulnerabilities: "vulnerability-1"
}
vulnerabilities {
bom_ref: "vulnerability-1"
id: "ACME-12345"
source: {
name: "Acme Inc"
}
}
16 changes: 15 additions & 1 deletion tools/src/test/resources/1.5/valid-compositions-1.5.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
</dependency>
</dependencies>
<compositions>
<composition>
<composition bom-ref="composition-1">
<aggregate>complete</aggregate>
<assemblies>
<assembly ref="pkg:maven/partner/[email protected]"/>
Expand All @@ -47,5 +47,19 @@
<assembly ref="pkg:maven/acme/[email protected]"/>
</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>