Port 2.x Annexes to 3.0 spec #904

rnjudge · 2024-04-09T22:49:10Z

This commit adds two annexes to the 3.0 spec:

How to include security information using SPDX-3.0
How to comply with various requirements (i.e. NTIA minimums) using
SPDX-3.0

NOTE: This PR is still a work in progress. It is being opened so others can comment - changes are expected. Please do not merge yet. I will remove this note when the PR is ready to review for merge.

docs/annexes/including-security-information-in-SPDX.md

docs/annexes/using-SPDX-to-comply-with-industry-guidance.md

rnjudge · 2024-04-11T17:25:02Z

@puerco do you want to take a look at the security annex? You can view the markdown file easier here: https://github.com/rnjudge/spdx-spec/blob/3.0-annex/docs/annexes/including-security-information-in-SPDX.md. There are some TODOs noted in the file where I have questions.

goneall

Couple of suggestions for consideration on the identifier mappings

goneall · 2024-04-13T02:03:04Z

docs/annexes/using-SPDX-to-comply-with-industry-guidance.md

+| Component Name | [Software/Classes/Package.name](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) inherited from [Core/Classes/Element.name](https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/name/) |
+| Version String | [Software/Classes/Package.packageVersion](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) |
+| Component Hash | [Core/Classes/Element.verifiedUsing](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) | 
+| Unique Identifier | [Software/Classes/SoftwareArtifact.contentIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/SoftwareArtifact/) for SPDX Software Artifacts <br>or [Core/Classes/ExternalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/ExternalIdentifier/) for resources outside the scope of SPDX-3.0 content </br> |


Suggested change

| Unique Identifier | [Software/Classes/SoftwareArtifact.contentIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/SoftwareArtifact/) for SPDX Software Artifacts <br>or [Core/Classes/ExternalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/ExternalIdentifier/) for resources outside the scope of SPDX-3.0 content </br> |

| Unique Identifier | [Software/Classes/SoftwareArtifact.contentIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/SoftwareArtifact/) for SPDX Software Artifacts <br>or [Core/Classes/Element.externalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) for resources outside the scope of SPDX-3.0 content </br> |

Suggest we refer to the property instead of the class

goneall · 2024-04-13T02:05:57Z

docs/annexes/using-SPDX-to-comply-with-industry-guidance.md

+| Component Name | [Software/Classes/Package.name](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) inherited from [Core/Classes/Element.name](https://spdx.github.io/spdx-spec/v3.0/model/Core/Properties/name/) |
+| Version String | [Software/Classes/Package.packageVersion](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) |
+| Component Hash | [Core/Classes/Element.verifiedUsing](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) | 
+| Unique Identifier | [Software/Classes/SoftwareArtifact.contentIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/SoftwareArtifact/) for SPDX Software Artifacts <br>or [Core/Classes/ExternalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/ExternalIdentifier/) for resources outside the scope of SPDX-3.0 content </br> |


There are several member of our community who would like PackageURL's to be included as a potential identifier.

There is some debate as to whether a PackageURL satisfies the uniqueness requirements of an identifier.

One compromise approach would be to add a line something like -
"or Software/Package.packageUrl if the packageUrl is considered to be unique"

puerco

OK, here is a first pass with some comments.

Since folks searching for security data are likely to land on this document, I think we should add a super, super simple vex example and then link it to a larger VEX HOWTO somewhere in the docs.

WDYT @rnjudge?

puerco · 2024-04-13T03:21:26Z

docs/annexes/including-security-information-in-SPDX.md

+```
+
+
+## G.1.3 Linking to a CycloneDX


Suggested change

## G.1.3 Linking to a CycloneDX

## G.1.3 Linking to CycloneDX Security Data

puerco · 2024-04-13T03:25:05Z

docs/annexes/including-security-information-in-SPDX.md

+* cpe22
+* cpe23
+* cve
+* cwe


CWE is not an external identifier. It is an ExtRef, an external reference to an entry in a catalog

Suggested change

* cwe

Good catch, I think I forgot to update when you made this suggestion on my other PR.

docs/annexes/including-security-information-in-SPDX.md

puerco · 2024-04-13T03:27:37Z

docs/annexes/including-security-information-in-SPDX.md

+
+This section provides usage scenarios of how to leverage the Security External References and External Identifiers specified above to refer to external security information. Examples of how to use each category can be found in the [Security/Classes](https://github.com/spdx/spdx-3-model/tree/main/model/Security/Classes) pages. Multiple instances and types of external security information may be included within a SPDX document.
+
+## G.1.1 Linking to an advisory


Let's keep the title case from the first titles

Suggested change

## G.1.1 Linking to an advisory

## G.1.1 Linking to an Advisory

puerco · 2024-04-13T03:31:41Z

docs/annexes/including-security-information-in-SPDX.md

+    },
+    {
+      "type": "ExternalIdentifier",
+      "externalIdentifierType": "securityOther",


I know that this is trying to show examples but this references a very well known advisory source

Suggested change

"externalIdentifierType": "securityOther",

"externalIdentifierType": "securityAdvisory",

I took this from the vulnerability class example -- good catch. I will update the Vulnerability example as well.

puerco · 2024-04-13T04:11:13Z

docs/annexes/including-security-information-in-SPDX.md

+## G.1.5 Linking to an OmniBOR (formerly known as GitBOM)
+
+To reference an [OmniBOR](https://omnibor.io/) (Universal Bill Of Receipts) formatted security information applicable to a package you must first create a Package Element. Then use an External Identifier to link to the OmniBOR document.
+**TODO: Is this gitoid correct? do we need a different example here?**


Gitoids identify the package blob, they are an identifier not a reference to something else.

Regarding the TODO, yes it is correct. The string in the example is the IANA URL scheme for gitoids.

Suggested change

## G.1.5 Linking to an OmniBOR (formerly known as GitBOM)

To reference an [OmniBOR](https://omnibor.io/) (Universal Bill Of Receipts) formatted security information applicable to a package you must first create a Package Element. Then use an External Identifier to link to the OmniBOR document.

**TODO: Is this gitoid correct? do we need a different example here?**

## G.1.5 Identifying a Package with an OmniBOR Gitoid

To identify a Package with an [OmniBOR](https://omnibor.io/) (Universal Bill Of Receipts, formerly known as GitBOM) gitoid, use an External Identifier to add gitoid to the package.

puerco · 2024-04-13T04:12:28Z

docs/annexes/including-security-information-in-SPDX.md

+}
+```
+
+## G.1.6 Linking to a vulnerability disclosure document


What is the difference between this and an advisory? (Especially since the links point to advisory data)

docs/annexes/including-security-information-in-SPDX.md

goneall

Just one minor change requested

docs/annexes/using-SPDX-to-comply-with-industry-guidance.md

kestewart

Changes look good to me.

We may want to be more explicit about the releationships to be specified for dependencies and root, but I don't consider it blocker at this point.

goneall

LGTM

This commit adds two annexes to the 3.0 spec: 1) How to include security information using SPDX-3.0 2) How to comply with various requirements (i.e. NTIA minimums) using SPDX-3.0 Signed-off-by: Rose Judge <[email protected]>

Signed-off-by: Karsten Klein <[email protected]>

This commit adds two annexes to the 3.0 spec: 1) How to include security information using SPDX-3.0 2) How to comply with various requirements (i.e. NTIA minimums) using SPDX-3.0 Signed-off-by: Rose Judge <[email protected]> Signed-off-by: Karsten Klein <[email protected]>

rnjudge · 2024-04-14T20:17:21Z

OK, here is a first pass with some comments.

Since folks searching for security data are likely to land on this document, I think we should add a super, super simple vex example and then link it to a larger VEX HOWTO somewhere in the docs.

WDYT @rnjudge?

Sounds good! I can get started on a VEX example annex to add to 3.0.1. We do have one VEX example in this annex under the CSAF section - linking to a generic VEX would be the same.

bact requested changes Apr 10, 2024

View reviewed changes

docs/annexes/including-security-information-in-SPDX.md Outdated Show resolved Hide resolved

bact reviewed Apr 10, 2024

View reviewed changes

docs/annexes/including-security-information-in-SPDX.md Outdated Show resolved Hide resolved

rnjudge commented Apr 10, 2024

View reviewed changes

docs/annexes/using-SPDX-to-comply-with-industry-guidance.md Outdated Show resolved Hide resolved

rnjudge force-pushed the 3.0-annex branch 3 times, most recently from 351b457 to fa417f8 Compare April 11, 2024 17:24

kestewart requested review from zvr and goneall April 12, 2024 20:50

kestewart added this to the 3.0 milestone Apr 12, 2024

rnjudge force-pushed the 3.0-annex branch from fa417f8 to 4a20ee3 Compare April 12, 2024 23:34

goneall requested changes Apr 13, 2024

View reviewed changes

puerco reviewed Apr 13, 2024

View reviewed changes

rnjudge force-pushed the 3.0-annex branch from 4a20ee3 to 1512d2c Compare April 14, 2024 18:30

goneall requested changes Apr 14, 2024

View reviewed changes

docs/annexes/using-SPDX-to-comply-with-industry-guidance.md Outdated Show resolved Hide resolved

rnjudge force-pushed the 3.0-annex branch 2 times, most recently from 9e14c41 to fee79a2 Compare April 14, 2024 19:04

kestewart approved these changes Apr 14, 2024

View reviewed changes

goneall approved these changes Apr 14, 2024

View reviewed changes

rnjudge and others added 5 commits April 14, 2024 12:23

Port 2.x Annexes to 3.0 spec

ebbe0ca

This commit adds two annexes to the 3.0 spec: 1) How to include security information using SPDX-3.0 2) How to comply with various requirements (i.e. NTIA minimums) using SPDX-3.0 Signed-off-by: Rose Judge <[email protected]>

Adapting structure of annex; adding BSI TR-03183

72069aa

Signed-off-by: Karsten Klein <[email protected]>

Adapting structure of annex; adding BSI TR-03183

4ce89ae

Signed-off-by: Karsten Klein <[email protected]>

Adapting structure of annex; adding BSI TR-03183

2e20504

rnjudge force-pushed the 3.0-annex branch from fee79a2 to 1eb28b3 Compare April 14, 2024 19:25

goneall merged commit 5787559 into spdx:development/v3.0 Apr 14, 2024
1 of 3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Port 2.x Annexes to 3.0 spec #904

Port 2.x Annexes to 3.0 spec #904

rnjudge commented Apr 9, 2024

rnjudge commented Apr 11, 2024

goneall left a comment

goneall Apr 13, 2024

goneall Apr 13, 2024

puerco left a comment

puerco Apr 13, 2024

puerco Apr 13, 2024

rnjudge Apr 14, 2024

puerco Apr 13, 2024

puerco Apr 13, 2024

rnjudge Apr 14, 2024

puerco Apr 13, 2024

puerco Apr 13, 2024

goneall left a comment

kestewart left a comment

goneall left a comment

rnjudge commented Apr 14, 2024

	\| Unique Identifier \| [Software/Classes/SoftwareArtifact.contentIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/SoftwareArtifact/) for SPDX Software Artifacts <br>or [Core/Classes/ExternalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/ExternalIdentifier/) for resources outside the scope of SPDX-3.0 content </br> \|
	\| Unique Identifier \| [Software/Classes/SoftwareArtifact.contentIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/SoftwareArtifact/) for SPDX Software Artifacts <br>or [Core/Classes/Element.externalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) for resources outside the scope of SPDX-3.0 content </br> \|

	## G.1.3 Linking to a CycloneDX
	## G.1.3 Linking to CycloneDX Security Data


		This section provides usage scenarios of how to leverage the Security External References and External Identifiers specified above to refer to external security information. Examples of how to use each category can be found in the [Security/Classes](https://github.com/spdx/spdx-3-model/tree/main/model/Security/Classes) pages. Multiple instances and types of external security information may be included within a SPDX document.

		## G.1.1 Linking to an advisory

	"externalIdentifierType": "securityOther",
	"externalIdentifierType": "securityAdvisory",

Port 2.x Annexes to 3.0 spec #904

Port 2.x Annexes to 3.0 spec #904

Conversation

rnjudge commented Apr 9, 2024

rnjudge commented Apr 11, 2024

goneall left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

puerco left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

goneall left a comment

Choose a reason for hiding this comment

kestewart left a comment

Choose a reason for hiding this comment

goneall left a comment

Choose a reason for hiding this comment

rnjudge commented Apr 14, 2024