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

Jump to bottom

[2.3.1] Annex K - Fix Markdown formatting + JSON code highlight #1115

Open
wants to merge 3 commits into
base: support/2.3.1
Choose a base branch
from
Open

[2.3.1] Annex K - Fix Markdown formatting + JSON code highlight #1115

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b7a2cbf
Fix bullets
bact Sep 7, 2024
f9389ec
Update how-to-use.md
bact Sep 7, 2024
4c0f139
Merge branch 'development/v2.3.1' into fix-annex-k1-bullets-v2.3.1
bact Sep 7, 2024
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
42 changes: 19 additions & 23 deletions chapters/how-to-use.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,24 @@

## K.1 Including security information in a SPDX document

SPDX 2.x has the concept of an External Reference for a Package to "reference an external source of additional information, metadata, enumerations, asset identifiers, or downloadable content believed to be relevant to the Package."
SPDX 2.x has the concept of an External Reference for a Package to "reference an external source of additional information, metadata, enumerations, asset identifiers, or downloadable content believed to be relevant to the Package."

The specification for External Reference identifiers (Annex F) has four defined categories:

* Security: CPE, SWID tag identifier, or reference to security information
* Package-Manager: package identifier and locator
* Persistent-id: identifier which is guaranteed to remain stable (persistent) over time
* Persistent-id: identifier which is guaranteed to remain stable (persistent) over time
* Other: Use if none of the above match your use case

This section provides usage scenarios of how to leverage the Security and Persistent-id category external references specified above to refer to external security information. A complete SPDX document using these can be found in the examples directory within the SPDX code repository. Multiple instances and types of external security information may be included within a SPDX document.

Note that identifiers (e.g. CPE, GitBOM, SWID) are spread throughout Annex F and sometimes locators refer to identifiers.
Note that identifiers (e.g. CPE, GitBOM, SWID) are spread throughout Annex F and sometimes locators refer to identifiers.

### K.1.1 Linking to an advisory

Including a reference to a Common Vulnerabilities and Exposures (CVE) advisory applicable to a package is shown in the example below. A SPDX creator should include current publicly known vulnerabilities at the time of document creation. SPDX consumers should always assume vulnerabilities enumerated by a SPDX creator to be out-of-date.

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://nvd.nist.gov/vuln/detail/CVE-2020-29573",
Expand All @@ -41,7 +41,7 @@ Including a reference to a Common Vulnerabilities and Exposures (CVE) advisory a
To learn how to reference to [CSAF](https://docs.oasis-open.org/csaf/csaf/v2.0/cs01/csaf-v2.0-cs01.html) formatted security information
applicable to a package see the example below, and additional examples here and here.

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/examples/csaf/csaf_vex/2022-evd-uc-01-a-001.json",
Expand All @@ -53,7 +53,7 @@ applicable to a package see the example below, and additional examples here and

To reference to [CycloneDX](https://cyclonedx.org) formatted security information applicable to a package see the example below.

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://raw.githubusercontent.com/CycloneDX/bom-examples/ed522d1f051c364e045b87c20665003a0c4ea777/SBOM/laravel-7.12.0/bom.json",
Expand All @@ -65,7 +65,7 @@ To reference to [CycloneDX](https://cyclonedx.org) formatted security informatio

To learn how to include a reference to [Open Source Vulnerability](https://github.com/google/osv) (OSV) formatted security information applicable to a package see the example below.

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://github.com/github/advisory-database/tree/6b9d5bc96a62bb845ee71e4551a214eb1457e2c6/advisories/github-reviewed/2022/04/GHSA-2gwj-7jmv-h26r/GHSA-2gwj-7jmv-h26r.json",
Expand All @@ -77,7 +77,7 @@ To learn how to include a reference to [Open Source Vulnerability](https://githu

To reference to [GitBOM](https://gitbom.dev) formatted security information applicable to a package see the example below.

```
```json
"externalRefs" : [ {
"referenceCategory" : "PERSISTENT-ID",
"referenceLocator" : "gitoid:blob:sha1:d8bcd58df2b14818b8237bb70c979d62c7df5747",
Expand All @@ -96,7 +96,7 @@ To reference to [GitBOM](https://gitbom.dev) formatted security information appl

To express a reference to a vulnerability disclosure document for a package such Cisco’s response to Apache log4j vulnerability.

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-apache-log4j-qRuKNEbd",
Expand All @@ -106,7 +106,7 @@ To express a reference to a vulnerability disclosure document for a package such

To communicate that a package is not vulnerable to a specific vulnerability it is recommended to reference a web page indicating why given vulnerabilities are not applicable.

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://example.com/product-x/security-info.html",
Expand All @@ -116,7 +116,7 @@ To communicate that a package is not vulnerable to a specific vulnerability it i

To refer to a security disclosure feed, such as the security bulletins from [CERT-EU](https://cert.europa.eu).

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://cert.europa.eu/cert/Data/newsletter/reviewlatest-SecurityBulletins.xml",
Expand All @@ -129,7 +129,7 @@ To refer to a security disclosure feed, such as the security bulletins from [CER
To reference a code fix for a security issue applicable to a package see the example below.
In this example, the link points to a specific code revision containing the fix for [CVE-2020-28498](https://nvd.nist.gov/vuln/detail/CVE-2020-28498).

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://github.com/indutny/elliptic/commit/441b7428b0e8f6636c42118ad2aaa186d3c34c3f",
Expand All @@ -139,7 +139,7 @@ In this example, the link points to a specific code revision containing the fix

A fix reference may point to a configuration change for example the patch file as one of the fixes for [CVE-2022-26499](https://nvd.nist.gov/vuln/detail/CVE-2022-26499).

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://downloads.digium.com/pub/security/AST-2022-002-16.diff",
Expand All @@ -150,7 +150,7 @@ A fix reference may point to a configuration change for example the patch file a
Alternatively, it may also link to a landing page with patches for a variety of products such as
Oracle patch information for [CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228).

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://www.oracle.com/security-alerts/cpujan2022.html",
Expand All @@ -162,7 +162,7 @@ Oracle patch information for [CVE-2021-44228](https://nvd.nist.gov/vuln/detail/C

If you want to reference any security information related to a package but cannot or do not wish to specify its kind, use the `url` referenceType.

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://github.com/christianlundkvist/blog/blob/aa3a69b5e4c06e4435070610c0c4a2b1e8731783/2020_05_26_secp256k1_twist_attacks/secp256k1_twist_attacks.md",
Expand All @@ -172,7 +172,7 @@ If you want to reference any security information related to a package but canno

One can also use it to refer to guidance related to a vulnerability such as CISA guidance for Apache Log4j.

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://www.cisa.gov/uscert/apache-log4j-vulnerability-guidance",
Expand All @@ -188,15 +188,14 @@ This enables a software producer to articulate to software consumers the status

Providing a link to such data at the time the SBOM is published provides a pointer for where to find this relevant vulnerability information without promulgating vulnerability information inside the SBOM. This is advantageous because the vulnerability information has a short shelf-life (it will change frequently) while the SBOM component data isn’t likely to change if the software has not changed.

```
```json
"externalRefs" : [ {
"referenceCategory" : "SECURITY",
"referenceLocator" : "https://github.com/rjb4standards/REA-Products/blob/master/SBOM_and_VDRbaseline/sag-pm-118_VDR.json",
"referenceType" : "advisory"
} ]
```


## K.2 Satisfying NTIA Minimum Elements for an SBOM using SPDX

### K.2.1 US Executive Order 14028 Minimum Elements for an SBOM
Expand All @@ -214,7 +213,6 @@ US Executive Order 14028 in conjunction with the National Telecommunications and
| Relationship | Characterizing the relationship that an upstream component X is included in software Y. |
| Timestamp | Record of the date and time of the SBOM data assembly. |


### K.2.2 Mapping NTIA Minimum Elements to SPDX Fields

The SPDX Specification contains fields able to address each of the NTIA minimum required data fields.
Expand All @@ -230,7 +228,6 @@ The SPDX Specification contains fields able to address each of the NTIA minimum
| Relationship | (11.1) Relationship: `CONTAINS`, `DESCRIBES` <br>The document must `DESCRIBES` at least one package.</br> |
| Timestamp | (6.9) Created |


## K.3 Verifying SPDX Packages

Several use cases for SPDX depend on the consumer being able to verify the provenance and integrity of their software. SPDX can support several different scenarios depending on what information is available to the producer, what information is available to the consumer, and how the SPDX document is delivered. These scenarios are described below along with recommended approaches to verifying the SPDX packages.
Expand All @@ -246,19 +243,19 @@ If a Package represents an artifact that logically binds a number of single file
* If the files bound by the Package are described in the document, `PackageVerificationCode` should be computed by using the files' [SHA1](https://www.rfc-editor.org/rfc/rfc3174) checksums. Additionally, the `FilesAnalyzed` field in the Package **MUST** be set to `true`.
* If the SHA1 checksum of any files bound by the Package is not available or the File needs to be excluded from the computation, it MUST be marked so by appending `(excludes: FileName)` at the end of the package verification code value.


### K.3.2 Examples

#### K.3.2.1 SPDX Package and SPDX Document both contained in Archive File

Examples include: tarball binding one or more files to a SPDX package, installation file which installs the package and extracts SPDX document in the same directory

SPDX Field To Use: [7.9 Package verification code](package-information.md#79-package-verification-code-field-)

Guidance:
* With the SPDX document included in the archive, it is not possible for the SPDX document to include a checksum for the archive itself. Generate a Package verification code and include the SPDX Document file name in the Excluded Files field.


#### K.3.2.2 SPDX Package Delivered as an Archive File Separate from the SPDX Document

Examples include: tarball, installation file

SPDX Field to Use: [7.10 Package checksum](package-information.md#710-package-checksum-field-)
Expand All @@ -277,7 +274,6 @@ Guidance:
* If a [Package download location](package-information.md#77-package-download-location-field-) exists, the Package checksum should be the cryptographic hash of the Package blob at the Package download location specified.
* If the Package download location is not known, not available, or not accessible to the software consumer, the producer should include a Package checksum for the included Package file.


#### K.3.2.4 Directory of Software Represented as a SPDX Package

Examples include: source code, containers
Expand Down