-
-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
f9002c3
commit 8a7f78c
Showing
5 changed files
with
608 additions
and
371 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| ## Composition Completeness, "Known Unknowns", and Redactions | ||
| The inventory of components, services, and their relationships to one another can be described through the use of | ||
| compositions. 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. This allows BOM authors | ||
| to describe how complete the BOM is or if there are components in the BOM where completeness is unknown or has been | ||
| redacted. | ||
|
|
||
| | Aggregate | Description | | ||
| |-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | complete | The information is complete. No further relationships including constituent components, services, or dependencies are known to exist. | | ||
| | incomplete | The information is incomplete. | | ||
| | incomplete_first_party_only | The information is incomplete. Only relationships for first-party components, services, or their dependencies are represented. | | ||
| | incomplete_first_party_proprietary_only | The information is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary. | | ||
| | incomplete_first_party_opensource_only | The information is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource. | | ||
| | incomplete_third_party_only | The information is incomplete. Only relationships for third-party components, services, or their dependencies are represented. | | ||
| | incomplete_third_party_proprietary_only | The information is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are proprietary. | | ||
| | incomplete_third_party_opensource_only | The information is incomplete. Only relationships for third-party components, services, or their dependencies are represented, limited specifically to those that are opensource. | | ||
| | redacted | The information has been redacted. | | ||
| | unknown | The information may be complete or incomplete. This usually signifies a 'best-effort' to obtain constituent components, services, or dependencies but the completeness is inconclusive. | | ||
|
|
||
| <div style="page-break-after: always; visibility: hidden"> | ||
| \newpage | ||
| </div> | ||
|
|
||
| The following illustrates how compositions can be used. In this example, there are three compositions. | ||
| 1. In the first object, the component assembly and the dependencies of the application are both complete. | ||
| 2. In the second object, the completeness of the component assembly is unknown. | ||
| 3. In the third object, the component is listed in the BOM, but its information and completeness have been redacted. | ||
|
|
||
| ```json | ||
| "compositions": [ | ||
| { | ||
| "aggregate": "complete", | ||
| "assemblies": [ | ||
| "pkg:maven/partner/[email protected]" | ||
| ], | ||
| "dependencies": [ | ||
| "acme-application-1.0" | ||
| ] | ||
| }, | ||
| { | ||
| "aggregate": "unknown", | ||
| "assemblies": [ | ||
| "pkg:maven/acme/[email protected]" | ||
| ] | ||
| }, | ||
| { | ||
| "aggregate": "redacted", | ||
| "assemblies": [ | ||
| "my-redacted-component" | ||
| ] | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| <div style="page-break-after: always; visibility: hidden"> | ||
| \newpage | ||
| </div> |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -32,6 +32,13 @@ The identity field of the component which the evidence describes. | |
| \newpage | ||
| </div> | ||
|
|
||
| ### Confidence | ||
| Confidence is supported per-technique along with a cumulative of all methods used. The confidence is specified as a decimal, | ||
| from 0 to 1, where 1 is 100% confidence. | ||
|
|
||
| ### Concluded Value | ||
| The value of the field (cpe, purl, etc) that has been concluded based on the aggregate of all methods (if available). | ||
|
|
||
| ### Methods | ||
| Multiple methods may be specified. Each method includes the specific technique used, the confidence of each technique, | ||
| and the value of the evidence that the technique revealed. | ||
|
|
@@ -56,52 +63,88 @@ The technique used in this method of analysis. | |
| \emptyparagraph | ||
| </div> | ||
|
|
||
| ### Confidence | ||
| Confidence is supported per-technique along with a cumulative of all methods used. The confidence is specified as a decimal, | ||
| from 0 to 1, where 1 is 100% confidence. | ||
|
|
||
| ### Tools | ||
| The tools (components or services) which extracted the evidence, performed the analysis, or evaluated the results. | ||
|
|
||
| <div style="page-break-after: always; visibility: hidden"> | ||
| \newpage | ||
| </div> | ||
|
|
||
| ### Example | ||
| ### Example #1 | ||
| The following example illustrates how different methods can be combined to substantiate a component's identity. | ||
|
|
||
| ```json | ||
| "identity": [ { | ||
| "field": "purl", | ||
| "confidence": 1, | ||
| "methods": [ | ||
| "components": [ | ||
| { | ||
| "group": "com.google.code.findbugs", | ||
| "name": "findbugs-project", | ||
| "version": "3.0.0", | ||
| "purl": "pkg:maven/com.google.code.findbugs/[email protected]", | ||
| "evidence": { | ||
| "identity": [ | ||
| { | ||
| "field": "purl", | ||
| "confidence": 1, | ||
| "concludedValue": "pkg:maven/com.google.code.findbugs/[email protected]", | ||
| "methods": [ | ||
| { | ||
| "technique": "filename", | ||
| "confidence": 0.1, | ||
| "value": "findbugs-project-3.0.0.jar" | ||
| }, | ||
| { | ||
| "technique": "hash-comparison", | ||
| "confidence": 0.8, | ||
| "value": "7c547a9d67cc7bc315c93b6e2ff8e4b6b41ae5be454ac249655ecb5ca2a85abf" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| ### Example #2 | ||
| In the following example, two identity objects provide lower-confidence alternate CPEs. Vulnerability databases | ||
| such as the National Vulnerability Database, which rely exclusively on CPE, often have erroneous or data fidelity issues | ||
| that prevent precise reporting on affected products. CycloneDX solves this issue by allowing BOM authors to assert | ||
| component identity, and optionally specify evidence of other possible identifiers to aid in vulnerability identification. | ||
|
|
||
| ```json | ||
| "evidence": { | ||
| "identity": [ | ||
| { | ||
| "technique": "filename", | ||
| "confidence": 0.1, | ||
| "value": "findbugs-project-3.0.0.jar" | ||
| "field": "cpe", | ||
| "confidence": 0.4, | ||
| "concludedValue": "cpe:2.3:a:acme:acme-application:1.0.0:*:*:*:*:*:*:*" | ||
| }, | ||
| { | ||
| "technique": "hash-comparison", | ||
| "confidence": 0.8, | ||
| "value": "7c547a9d67cc7bc315c93b6e2ff8e4b6b41ae5be454ac249655ecb5ca2a85abf" | ||
| } | ||
| "field": "cpe", | ||
| "confidence": 0.4, | ||
| "concludedValue": "cpe:2.3:a:acme-systems:acme-application:1.0.0:*:*:*:*:*:*:*" | ||
| } | ||
| ] | ||
| } ] | ||
| } | ||
| ``` | ||
|
|
||
| ## Recommendations | ||
| ### Technique Confidence Recommendations | ||
| The following are recommendations for tool creators and BOM consumers. Each technique is a general category. Tools | ||
| may employ general purpose or highly specialized rules and analysis, each with varying degrees of confidence. | ||
|
|
||
| | Technique | Confidence | Guidance | | ||
| |----------------------|------------|--| | ||
| | source-code-analysis | 0.3 - 1.0 | Confidence will vary based on rules, type of analyzers used, or 1:1 matching of source with a known good dataset. | | ||
| | binary-analysis | 0.2 - 0.7 | The individual rules, analyzers, and dataset coverage will influence confidence. | | ||
| | manifest-analysis | 0.4 - 0.6 | Manifests have known limitations and abuse cases and have moderate confidence. | | ||
| | ast-fingerprint | 0.3 - 1.0 | Wide range of possible confidence due to source and binary variations, but it has the potential for precise results. | | ||
| | Technique | Confidence | Guidance | | ||
| |----------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | source-code-analysis | 0.3 - 1.0 | Confidence will vary based on rules, type of analyzers used, or 1:1 matching of source with a known good dataset. | | ||
| | binary-analysis | 0.2 - 0.7 | The individual rules, analyzers, and dataset coverage will influence confidence. | | ||
| | manifest-analysis | 0.4 - 0.6 | Manifests have known limitations and abuse cases and have moderate confidence. | | ||
| | ast-fingerprint | 0.3 - 1.0 | Wide range of possible confidence due to source and binary variations, but it has the potential for precise results. | | ||
| | hash-comparison | 0.7 - 1.0 | Can successfully match components given a large dataset. Confidence may vary based on the cryptographic hash function used and its resistance to collisions. | | ||
| | instrumentation | 0.3 - 0.8 | Confidence similar to source-code-analysis with the added benefit of supporting call-stack evidence | | ||
| | dynamic-analysis | 0.2 - 0.6 | Low to moderate confidence due to the "black box" approach of many tools. | | ||
| | filename | 0 - 0.1 | Filename matching is low-confidence | | ||
| | attestation | 0.7 - 1.0 | The testimony of a supplier or trusted third-party, especially when legally binding, may have high confidence. | | ||
| | instrumentation | 0.3 - 0.8 | Confidence similar to source-code-analysis with the added benefit of supporting call-stack evidence | | ||
| | dynamic-analysis | 0.2 - 0.6 | Low to moderate confidence due to the "black box" approach of many tools. | | ||
| | filename | 0 - 0.1 | Filename matching is low-confidence | | ||
| | attestation | 0.7 - 1.0 | The testimony of a supplier or trusted third-party, especially when legally binding, may have high confidence. | | ||
|
|
||
| <div style="page-break-after: always; visibility: hidden"> | ||
| \newpage | ||
| </div> | ||
|
|
||
| ## Occurrences | ||
| CycloneDX provides a mechanism to describe identical components spread across multiple locations. For example, | ||
|
|
||
Oops, something went wrong.