From 2284117da822f3b1cd52c647a5a1a4473aa022dd Mon Sep 17 00:00:00 2001 From: "Alexios Zavras (zvr)" Date: Mon, 17 Jun 2024 13:44:57 +0200 Subject: [PATCH] Deployed 5f08fb9 with MkDocs version: 1.6.0 --- 404.html | 16 +- ISO_foreword/index.html | 16 +- .../index.html | 87 +- .../index.html | 761 ++++++--- annexes/SPDX-license-expressions/index.html | 52 +- .../index.html | 469 +++--- .../diffs-from-previous-editions/index.html | 777 ++++++++- annexes/getting-started/index.html | 1440 +++++++++++++++++ .../index.html | 474 ++++-- .../index.html | 21 +- .../index.html | 145 +- bibliography/index.html | 22 +- conformance/index.html | 20 +- images/model AI.png | Bin 0 -> 832402 bytes images/model Build.png | Bin 0 -> 741485 bytes images/model Core+Software.png | Bin 0 -> 1516434 bytes images/model Dataset.png | Bin 0 -> 575626 bytes images/model Extension.png | Bin 0 -> 695205 bytes images/model Licensing.png | Bin 0 -> 907543 bytes images/model Security.png | Bin 0 -> 979272 bytes index.html | 40 +- introduction/index.html | 16 +- .../index.html | 39 +- .../index.html | 28 +- model/AI/AI/index.html | 16 +- model/AI/Classes/AIPackage/index.html | 16 +- model/AI/Classes/EnergyConsumption/index.html | 16 +- .../EnergyConsumptionDescription/index.html | 16 +- model/AI/Properties/autonomyType/index.html | 16 +- model/AI/Properties/domain/index.html | 16 +- .../Properties/energyConsumption/index.html | 16 +- model/AI/Properties/energyQuantity/index.html | 16 +- model/AI/Properties/energyUnit/index.html | 16 +- .../finetuningEnergyConsumption/index.html | 16 +- model/AI/Properties/hyperparameter/index.html | 16 +- .../inferenceEnergyConsumption/index.html | 16 +- .../informationAboutApplication/index.html | 16 +- .../informationAboutTraining/index.html | 16 +- model/AI/Properties/limitation/index.html | 16 +- model/AI/Properties/metric/index.html | 16 +- .../metricDecisionThreshold/index.html | 16 +- .../modelDataPreprocessing/index.html | 16 +- .../Properties/modelExplainability/index.html | 16 +- .../safetyRiskAssessment/index.html | 16 +- .../Properties/standardCompliance/index.html | 16 +- .../trainingEnergyConsumption/index.html | 16 +- model/AI/Properties/typeOfModel/index.html | 16 +- .../index.html | 16 +- .../AI/Vocabularies/EnergyUnitType/index.html | 16 +- .../SafetyRiskAssessmentType/index.html | 16 +- model/Build/Build/index.html | 16 +- model/Build/Classes/Build/index.html | 16 +- .../Build/Properties/buildEndTime/index.html | 16 +- model/Build/Properties/buildId/index.html | 16 +- .../Properties/buildStartTime/index.html | 16 +- model/Build/Properties/buildType/index.html | 16 +- .../Properties/configSourceDigest/index.html | 16 +- .../configSourceEntrypoint/index.html | 16 +- .../Properties/configSourceUri/index.html | 16 +- model/Build/Properties/environment/index.html | 16 +- model/Build/Properties/parameters/index.html | 16 +- model/Core/Classes/Agent/index.html | 16 +- model/Core/Classes/Annotation/index.html | 16 +- model/Core/Classes/Artifact/index.html | 16 +- model/Core/Classes/Bom/index.html | 16 +- model/Core/Classes/Bundle/index.html | 16 +- model/Core/Classes/CreationInfo/index.html | 16 +- model/Core/Classes/DictionaryEntry/index.html | 16 +- model/Core/Classes/Element/index.html | 16 +- .../Core/Classes/ElementCollection/index.html | 16 +- .../Classes/ExternalIdentifier/index.html | 16 +- model/Core/Classes/ExternalMap/index.html | 16 +- model/Core/Classes/ExternalRef/index.html | 16 +- model/Core/Classes/Hash/index.html | 16 +- model/Core/Classes/IntegrityMethod/index.html | 16 +- .../LifecycleScopedRelationship/index.html | 16 +- model/Core/Classes/NamespaceMap/index.html | 16 +- model/Core/Classes/Organization/index.html | 16 +- .../PackageVerificationCode/index.html | 16 +- model/Core/Classes/Person/index.html | 16 +- .../Classes/PositiveIntegerRange/index.html | 16 +- model/Core/Classes/Relationship/index.html | 16 +- model/Core/Classes/SoftwareAgent/index.html | 16 +- model/Core/Classes/SpdxDocument/index.html | 16 +- model/Core/Classes/Tool/index.html | 16 +- model/Core/Core/index.html | 16 +- model/Core/Datatypes/DateTime/index.html | 16 +- model/Core/Datatypes/MediaType/index.html | 16 +- model/Core/Datatypes/SemVer/index.html | 16 +- .../Individuals/NoAssertionElement/index.html | 16 +- model/Core/Individuals/NoneElement/index.html | 16 +- model/Core/Properties/algorithm/index.html | 16 +- .../Core/Properties/annotationType/index.html | 16 +- .../Properties/beginIntegerRange/index.html | 16 +- model/Core/Properties/builtTime/index.html | 16 +- model/Core/Properties/comment/index.html | 16 +- model/Core/Properties/completeness/index.html | 16 +- model/Core/Properties/contentType/index.html | 16 +- model/Core/Properties/context/index.html | 16 +- model/Core/Properties/created/index.html | 16 +- model/Core/Properties/createdBy/index.html | 16 +- model/Core/Properties/createdUsing/index.html | 16 +- model/Core/Properties/creationInfo/index.html | 16 +- model/Core/Properties/dataLicense/index.html | 16 +- .../Properties/definingArtifact/index.html | 16 +- model/Core/Properties/description/index.html | 16 +- model/Core/Properties/element/index.html | 16 +- .../Properties/endIntegerRange/index.html | 16 +- model/Core/Properties/endTime/index.html | 16 +- model/Core/Properties/extension/index.html | 16 +- .../Properties/externalIdentifier/index.html | 16 +- .../externalIdentifierType/index.html | 16 +- model/Core/Properties/externalRef/index.html | 16 +- .../Properties/externalRefType/index.html | 16 +- .../Core/Properties/externalSpdxId/index.html | 16 +- model/Core/Properties/from/index.html | 16 +- model/Core/Properties/hashValue/index.html | 16 +- model/Core/Properties/identifier/index.html | 16 +- .../Properties/identifierLocator/index.html | 16 +- model/Core/Properties/imports/index.html | 16 +- .../Properties/issuingAuthority/index.html | 16 +- model/Core/Properties/key/index.html | 16 +- model/Core/Properties/locationHint/index.html | 16 +- model/Core/Properties/locator/index.html | 16 +- model/Core/Properties/name/index.html | 16 +- model/Core/Properties/namespace/index.html | 16 +- model/Core/Properties/namespaceMap/index.html | 16 +- model/Core/Properties/originatedBy/index.html | 16 +- .../index.html | 16 +- model/Core/Properties/prefix/index.html | 16 +- .../Properties/profileConformance/index.html | 16 +- .../Properties/relationshipType/index.html | 16 +- model/Core/Properties/releaseTime/index.html | 16 +- model/Core/Properties/rootElement/index.html | 16 +- model/Core/Properties/scope/index.html | 16 +- model/Core/Properties/spdxId/index.html | 16 +- model/Core/Properties/specVersion/index.html | 16 +- model/Core/Properties/standardName/index.html | 16 +- model/Core/Properties/startTime/index.html | 16 +- model/Core/Properties/statement/index.html | 16 +- model/Core/Properties/subject/index.html | 16 +- model/Core/Properties/summary/index.html | 16 +- model/Core/Properties/suppliedBy/index.html | 16 +- model/Core/Properties/supportLevel/index.html | 16 +- model/Core/Properties/to/index.html | 16 +- .../Core/Properties/validUntilTime/index.html | 16 +- model/Core/Properties/value/index.html | 16 +- .../Core/Properties/verifiedUsing/index.html | 16 +- .../Vocabularies/AnnotationType/index.html | 16 +- .../ExternalIdentifierType/index.html | 16 +- .../Vocabularies/ExternalRefType/index.html | 16 +- .../Vocabularies/HashAlgorithm/index.html | 16 +- .../LifecycleScopeType/index.html | 16 +- .../Core/Vocabularies/PresenceType/index.html | 16 +- .../ProfileIdentifierType/index.html | 16 +- .../RelationshipCompleteness/index.html | 16 +- .../Vocabularies/RelationshipType/index.html | 16 +- .../Core/Vocabularies/SupportType/index.html | 16 +- .../Dataset/Classes/DatasetPackage/index.html | 16 +- model/Dataset/Dataset/index.html | 16 +- .../anonymizationMethodUsed/index.html | 16 +- .../confidentialityLevel/index.html | 16 +- .../dataCollectionProcess/index.html | 16 +- .../Properties/dataPreprocessing/index.html | 16 +- .../Properties/datasetAvailability/index.html | 16 +- .../Properties/datasetNoise/index.html | 16 +- .../Dataset/Properties/datasetSize/index.html | 16 +- .../Dataset/Properties/datasetType/index.html | 16 +- .../datasetUpdateMechanism/index.html | 16 +- .../index.html | 16 +- .../Dataset/Properties/intendedUse/index.html | 16 +- model/Dataset/Properties/knownBias/index.html | 16 +- model/Dataset/Properties/sensor/index.html | 16 +- .../ConfidentialityLevelType/index.html | 16 +- .../DatasetAvailabilityType/index.html | 16 +- .../Vocabularies/DatasetType/index.html | 16 +- .../Classes/ConjunctiveLicenseSet/index.html | 16 +- .../Classes/CustomLicense/index.html | 16 +- .../Classes/CustomLicenseAddition/index.html | 16 +- .../Classes/DisjunctiveLicenseSet/index.html | 16 +- .../Classes/ExtendableLicense/index.html | 16 +- .../IndividualLicensingInfo/index.html | 16 +- .../Classes/License/index.html | 16 +- .../Classes/LicenseAddition/index.html | 16 +- .../Classes/ListedLicense/index.html | 16 +- .../Classes/ListedLicenseException/index.html | 16 +- .../Classes/OrLaterOperator/index.html | 16 +- .../Classes/WithAdditionOperator/index.html | 16 +- .../ExpandedLicensing/index.html | 16 +- .../Individuals/NoAssertionLicense/index.html | 16 +- .../Individuals/NoneLicense/index.html | 16 +- .../Properties/additionText/index.html | 16 +- .../Properties/deprecatedVersion/index.html | 16 +- .../isDeprecatedAdditionId/index.html | 16 +- .../isDeprecatedLicenseId/index.html | 16 +- .../Properties/isFsfLibre/index.html | 16 +- .../Properties/isOsiApproved/index.html | 16 +- .../Properties/licenseXml/index.html | 16 +- .../Properties/listVersionAdded/index.html | 16 +- .../Properties/member/index.html | 16 +- .../Properties/obsoletedBy/index.html | 16 +- .../Properties/seeAlso/index.html | 16 +- .../standardAdditionTemplate/index.html | 16 +- .../standardLicenseHeader/index.html | 16 +- .../standardLicenseTemplate/index.html | 16 +- .../Properties/subjectAddition/index.html | 16 +- .../subjectExtendableLicense/index.html | 16 +- .../Properties/subjectLicense/index.html | 16 +- .../Classes/CdxPropertiesExtension/index.html | 16 +- .../Classes/CdxPropertyEntry/index.html | 16 +- model/Extension/Classes/Extension/index.html | 16 +- model/Extension/Extension/index.html | 16 +- .../Properties/cdxPropName/index.html | 16 +- .../Properties/cdxPropValue/index.html | 16 +- .../Properties/cdxProperty/index.html | 16 +- model/Licensing/Licensing/index.html | 16 +- model/Lite/Lite/index.html | 16 +- .../index.html | 16 +- .../index.html | 16 +- .../index.html | 16 +- .../EpssVulnAssessmentRelationship/index.html | 16 +- .../index.html | 16 +- .../SsvcVulnAssessmentRelationship/index.html | 16 +- .../index.html | 16 +- .../index.html | 16 +- .../index.html | 16 +- .../index.html | 16 +- .../VexVulnAssessmentRelationship/index.html | 16 +- .../VulnAssessmentRelationship/index.html | 16 +- .../Security/Classes/Vulnerability/index.html | 16 +- .../Properties/actionStatement/index.html | 16 +- .../Properties/actionStatementTime/index.html | 16 +- .../Properties/assessedElement/index.html | 16 +- .../Properties/catalogType/index.html | 16 +- .../Properties/decisionType/index.html | 16 +- .../Security/Properties/exploited/index.html | 16 +- .../Properties/impactStatement/index.html | 16 +- .../Properties/impactStatementTime/index.html | 16 +- .../Properties/justificationType/index.html | 16 +- model/Security/Properties/locator/index.html | 16 +- .../Properties/modifiedTime/index.html | 16 +- .../Security/Properties/percentile/index.html | 16 +- .../Properties/probability/index.html | 16 +- .../Properties/publishedTime/index.html | 16 +- model/Security/Properties/score/index.html | 16 +- model/Security/Properties/severity/index.html | 16 +- .../Properties/statusNotes/index.html | 16 +- .../Properties/vectorString/index.html | 16 +- .../Security/Properties/vexVersion/index.html | 16 +- .../Properties/withdrawnTime/index.html | 16 +- model/Security/Security/index.html | 16 +- .../Vocabularies/CvssSeverityType/index.html | 16 +- .../ExploitCatalogType/index.html | 16 +- .../Vocabularies/SsvcDecisionType/index.html | 16 +- .../VexJustificationType/index.html | 16 +- .../Classes/AnyLicenseInfo/index.html | 16 +- .../Classes/LicenseExpression/index.html | 16 +- .../Classes/SimpleLicensingText/index.html | 16 +- .../Properties/customIdToUri/index.html | 16 +- .../Properties/licenseExpression/index.html | 16 +- .../Properties/licenseListVersion/index.html | 16 +- .../Properties/licenseText/index.html | 16 +- .../SimpleLicensing/index.html | 16 +- .../Classes/ContentIdentifier/index.html | 16 +- model/Software/Classes/File/index.html | 16 +- model/Software/Classes/Package/index.html | 16 +- model/Software/Classes/Sbom/index.html | 16 +- model/Software/Classes/Snippet/index.html | 16 +- .../Classes/SoftwareArtifact/index.html | 16 +- .../Properties/additionalPurpose/index.html | 16 +- .../Properties/attributionText/index.html | 16 +- .../Software/Properties/byteRange/index.html | 16 +- .../Properties/contentIdentifier/index.html | 16 +- .../contentIdentifierType/index.html | 16 +- .../contentIdentifierValue/index.html | 16 +- .../Properties/contentType/index.html | 16 +- .../Properties/copyrightText/index.html | 16 +- .../Properties/downloadLocation/index.html | 16 +- model/Software/Properties/fileKind/index.html | 16 +- model/Software/Properties/homePage/index.html | 16 +- .../Software/Properties/lineRange/index.html | 16 +- .../Software/Properties/packageUrl/index.html | 16 +- .../Properties/packageVersion/index.html | 16 +- .../Properties/primaryPurpose/index.html | 16 +- model/Software/Properties/sbomType/index.html | 16 +- .../Properties/snippetFromFile/index.html | 16 +- .../Software/Properties/sourceInfo/index.html | 16 +- model/Software/Software/index.html | 16 +- .../ContentIdentifierType/index.html | 16 +- .../Vocabularies/FileKindType/index.html | 16 +- .../Software/Vocabularies/SbomType/index.html | 16 +- .../Vocabularies/SoftwarePurpose/index.html | 16 +- normative-references/index.html | 16 +- scope/index.html | 18 +- search.html | 16 +- search/search_index.json | 2 +- serializations/index.html | 891 ++++++++++ terms-and-definitions/index.html | 64 +- 298 files changed, 6715 insertions(+), 3003 deletions(-) rename annexes/{external-repository-identifiers => SPDX-Lite}/index.html (72%) rename annexes/{how-to-use => cross-reference}/index.html (67%) create mode 100644 annexes/getting-started/index.html rename annexes/{file-tags => including-security-information-in-SPDX}/index.html (51%) rename annexes/{using-SPDX-lite => using-SPDX-to-comply-with-industry-guidance}/index.html (85%) create mode 100644 images/model AI.png create mode 100644 images/model Build.png create mode 100644 images/model Core+Software.png create mode 100644 images/model Dataset.png create mode 100644 images/model Extension.png create mode 100644 images/model Licensing.png create mode 100644 images/model Security.png rename licenses/{cc-by-3.0-unported => CC-BY-3.0}/index.html (96%) rename licenses/{community-spec => Community-Spec-1.0}/index.html (97%) create mode 100644 serializations/index.html diff --git a/404.html b/404.html index d58df1e..5546e80 100644 --- a/404.html +++ b/404.html @@ -54,7 +54,7 @@

annexes

-
    @@ -756,10 +756,10 @@

annexes

-
    +

    licenses

    @@ -797,7 +803,8 @@
      • -
    • Annex K: How To Use SPDX in Different Scenarios
      • +
    • annexes
      • +
    • Cross-referencing in SPDX 3
    @@ -806,284 +813,214 @@
    -

    Annex K: How To Use SPDX in Different Scenarios

    -

    TODO: re-write for SPDXv3

    -

    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."

    -

    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 -- 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.

    -

    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.

    -
    "externalRefs" : [ {
- "referenceCategory" : "SECURITY",
- "referenceLocator" : "https://nvd.nist.gov/vuln/detail/CVE-2020-29573",
- "referenceType" : "advisory"
-}, {
- "referenceCategory" : "SECURITY",
- "referenceLocator" : "https://nvd.nist.gov/vuln/detail/CVE-2020-6096",
- "referenceType" : "advisory"
-}, {
-}, {
- "referenceCategory" : "SECURITY",
- "referenceLocator" : "https://nvd.nist.gov/vuln/detail/CVE-2020-3326",
- "referenceType" : "advisory"
-} ]
-
    - -

    K.1.2 Linking to a CSAF

    -

    To learn how to reference to CSAF formatted security information -applicable to a package see the example below, and additional examples here and here.

    -
    "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",
-  "referenceType" : "advisory"
-} ]
+                
    Annex I: Cross referencing in SPDX 3 (Informative)
    
+
    This document will walk though how to refer to SPDX Elements across documents
+(e.g. cross reference).
    
+
    If you do would like to construct the complete example documents from this
+Markdown file, use the following command:
    
+
    cat cross-reference.md | awk 'BEGIN{flag=0} /^```json/, $0=="```" { if (/^---$/){flag++} else if ($0 !~ /^```.*/ ) print $0 > "doc-" flag ".spdx.json"}'
 
    
 
-
    K.1.3 Linking to a CycloneDX
    
-
    To reference to CycloneDX formatted security information applicable to a package see the example below.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "SECURITY",
-  "referenceLocator" : "https://raw.githubusercontent.com/CycloneDX/bom-examples/ed522d1f051c364e045b87c20665003a0c4ea777/SBOM/laravel-7.12.0/bom.json",
-  "referenceType" : "advisory"
-} ]
+
    Linking via spdxId
    
+
    It is frequently desired (and necessary) to reference an SPDX 3
+Element that lives in one document from another. Since SPDX
+documents are valid JSON-LD documents, linking elements together can
+be as simple as referencing the spdxId of one element from another (in the same
+way that doing so within a document links Elements together. For example,
+assume we have this document that contains a Person we want to
+reference in another document:
    
+
    {
+    "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld",
+    "@graph": [
+        {
+            "type": "Person",
+            "spdxId": "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f",
+            "creationInfo": "_:creationinfo",
+            "name": "Joshua Watt",
+            "externalIdentifier": [
+                {
+                    "type": "ExternalIdentifier",
+                    "externalIdentifierType": "email",
+                    "identifier": "JPEWhacker@gmail.com"
+                }
+            ]
+        },
+        {
+            "type": "CreationInfo",
+            "@id": "_:creationinfo",
+            "specVersion": "3.0.0",
+            "createdBy": [
+                "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f"
+            ],
+            "created": "2024-03-06T00:00:00Z"
+        },
+        {
+            "type": "SpdxDocument",
+            "spdxId": "https://spdx.org/spdxdocs/Document1-7bd25aaf-64b7-4ccc-aa85-84695cef4c17",
+            "creationInfo": "_:creationinfo",
+            "profileConformance": [
+                "core"
+            ],
+            "rootElement": [
+                "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f"
+            ]
+        }
+    ]
+}
 
    
 
-
    K.1.4 Linking to an OSV
    
-
    To learn how to include a reference to Open Source Vulnerability (OSV) formatted security information applicable to a package see the example below.
    
-
    "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",
-  "referenceType" : "advisory"
-} ]
+
    Now, in our new document we can reference the "Joshua Watt" person by simply
+referring to it by its spdxId. For example, to indicate that this new document
+was also written by the same person, we can reference it in the creation info
+(note the createdBy property):
    
+
    ---
+{
+    "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld",
+    "@graph": [
+        {
+            "type": "CreationInfo",
+            "@id": "_:creationinfo1",
+            "specVersion": "3.0.0",
+            "createdBy": [
+                "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f"
+            ],
+            "created": "2024-05-08T00:00:00Z"
+        },
 
    
 
-
    K.1.5 Linking to a GitBOM
    
-
    To reference to GitBOM formatted security information applicable to a package see the example below.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "PERSISTENT-ID",
-  "referenceLocator" : "gitoid:blob:sha1:d8bcd58df2b14818b8237bb70c979d62c7df5747",
-  "referenceType" : "gitbom"
-  "referenceComment" : "GitBOM Object Id for the HeartBleed fix in ssl/d1_both.c"
-} ,
-{
-  "referenceCategory" : "PERSISTENT-ID",
-  "referenceLocator" : "gitoid:blob:sha1:bcb99b819dadaebdf2c8f88d92ee9024c45f9df3",
-  "referenceType" : "gitbom"
-  "referenceComment" : "GitBOM Object Id for the HeartBleed fix in ssl/t1_lib.c"
-} ]
+
    Imports
    
+
    This is sufficient to link documents in JSON-LD, but it is missing some useful
+information that SPDX requires you to specify. Namely, since spdxIds are not
+necessarily resolvable URLs, this gives no indication as to where the
+Person can be found. In order to provide this information, SPDX
+requires that all externally referenced spdxIds be enumerated in the
+imports property of the local
+SpdxDocument. Lets start by writing the preamble for the
+SpdxDocument:
    
+
            {
+            "type": "SpdxDocument",
+            "spdxId": "https://spdx.org/spdxdocs/Document2-72d52ac3-3642-47be-9f83-8fbef6a962b4",
+            "creationInfo": "_:creationinfo1",
+            "profileConformance": [
+                "core",
+                "software"
+            ],
+            "imports": [
 
    
 
-
    K.1.6 Linking to a vulnerability disclosure document
    
-
    To express a reference to a vulnerability disclosure document for a package such Cisco’s response to Apache log4j vulnerability.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "SECURITY",
-  "referenceLocator" : "https://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-apache-log4j-qRuKNEbd",
-  "referenceType" : "advisory"
-} ]
+
    The imports property is a list of
+ExternalMap objects, one for each external spdxId being
+referenced. The class has one required property called
+externalSpdxId which is the external spdxId being
+described:
    
+
                    {
+                    "type": "ExternalMap",
+                    "externalSpdxId": "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f",
 
    
 
-
    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.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "SECURITY",
-  "referenceLocator" : "https://example.com/product-x/security-info.html",
-  "referenceType" : "advisory"
-} ]
+
    In addition to this, there are a few optional fields. The first is the
+locationHint property which is a URI that indicates
+where the document that contains the external spdxId may be located. Since this
+is an actual resolvable URI, consumers of the document can use locate the
+unresolved spdxId. While optional, this field is recommended:
    
+
                        "locationHint": "http://downloads.example.com/Document1.spdx.json",
 
    
 
-
    To refer to a security disclosure feed, such as the security bulletins from CERT-EU.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "SECURITY",
-  "referenceLocator" : "https://cert.europa.eu/cert/Data/newsletter/reviewlatest-SecurityBulletins.xml",
-  "referenceType" : "advisory"
-} ]
+
    In addition to the location, the verifiedUsing
+property indicates how a user can verify the integrity of the external document
+to ensure it has not been tampered with. It can be 0 or more
+IntegrityMethod objects. While also optional, it is
+recommended to include at least one:
    
+
                        "verifiedUsing": [{
+                        "type": "Hash",
+                        "algorithm": "sha256",
+                        "hashValue": "3ba8c249c1ba1b6fe20582de88a5123b317632a5a94ba27199d01724df4eb149"
+                    }],
 
    
 
-
    K.1.7 Linking to a code fix for a security issue
    
-
    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.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "SECURITY",
-  "referenceLocator" : "https://github.com/indutny/elliptic/commit/441b7428b0e8f6636c42118ad2aaa186d3c34c3f",
-  "referenceType" : "fix"
-} ]
+
    Finally, the definingArtifact allows a much richer
+expression of information about the document that contains the external spdxId
+by linking to a complete Artifact element. This field is also
+optional, but if you need the impressive expressive power of the Artifact
+class, it is also recommended:
    
+
                        "definingArtifact": "https://spdx.org/spdxdocs/Artifact-4762f4c5-3362-47e9-9595-5182235ef577"
 
    
 
-
    A fix reference may point to a configuration change for example the patch file as one of the fixes for CVE-2022-26499.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "SECURITY",
-  "referenceLocator" : "https://downloads.digium.com/pub/security/AST-2022-002-16.diff",
-  "referenceType" : "fix"
-} ]
+
    It should be noted that it is reasonable for the definingArtifact itself to
+be an external spdxId, as long as it also has the relevant entry in imports.
    
+
    We also need to add an import for the SpdxDocument that
+contains the author, as we will be referencing it later, so lets do that now:
    
+
                    },
+                {
+                    "type": "ExternalMap",
+                    "externalSpdxId": "https://spdx.org/spdxdocs/Document1-7bd25aaf-64b7-4ccc-aa85-84695cef4c17",
+                    "locationHint": "http://downloads.example.com/Document1.spdx.json",
+                    "verifiedUsing": [{
+                        "type": "Hash",
+                        "algorithm": "sha256",
+                        "hashValue": "3ba8c249c1ba1b6fe20582de88a5123b317632a5a94ba27199d01724df4eb149"
+                    }],
+                    "definingArtifact": "https://spdx.org/spdxdocs/Artifact-4762f4c5-3362-47e9-9595-5182235ef577"
+                }
 
    
 
-
    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.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "SECURITY",
-  "referenceLocator" : "https://www.oracle.com/security-alerts/cpujan2022.html",
-  "referenceType" : "fix"
-} ]
+
    And that is it! By providing this information you are explaining to consumer of
+the document how they can resolve the external spdxIds.
    
+
    Lets close out our SpdxDocument
    
+
                ]
+        },
 
    
 
-
-
    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.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "SECURITY",
-  "referenceLocator" : "https://github.com/christianlundkvist/blog/blob/aa3a69b5e4c06e4435070610c0c4a2b1e8731783/2020_05_26_secp256k1_twist_attacks/secp256k1_twist_attacks.md",
-  "referenceType" : "url"
-} ]
+
    Since we are using an Artifact that describes the SpdxDocument
+containing the external spdxId, we need to write that now:
    
+
            {
+            "type": "software_File",
+            "spdxId": "https://spdx.org/spdxdocs/Artifact-4762f4c5-3362-47e9-9595-5182235ef577",
+            "creationInfo": "_:creationinfo1",
+            "software_fileKind": "file",
+            "software_primaryPurpose": "file",
+            "software_contentType": "application/spdx+json",
+            "verifiedUsing": [{
+                "type": "Hash",
+                "algorithm": "sha256",
+                "hashValue": "3ba8c249c1ba1b6fe20582de88a5123b317632a5a94ba27199d01724df4eb149"
+            }],
+            "originatedBy": [
+                "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f"
+            ],
+            "suppliedBy": "https://spdx.org/spdxdocs/Person/JoshuaWatt-0ef7e15a-5628-4bd9-8485-a3eace6dcc4f",
+            "releaseTime": "2024-03-06T00:00:00Z",
+            "builtTime": "2024-03-06T00:00:00Z"
+        },
 
    
 
-
    One can also use it to refer to guidance related to a vulnerability such as CISA guidance for Apache Log4j.
    
-
    "externalRefs" : [ {
-  "referenceCategory" : "SECURITY",
-  "referenceLocator" : "https://www.cisa.gov/uscert/apache-log4j-vulnerability-guidance",
-  "referenceType" : "url"
-} ]
+
    Finally, since we are using an Artifact, we need to add a
+Relationship with type serailizedInArtifact to link the
+artifact and the serialized SpdxDocument. Note that this
+is where the spdxId of the SpdxDocument is referenced which is why we
+needed to import it earlier:
    
+
            {
+            "spdxId": "https://spdx.org/spdxdocs/Relationship/serializedInArtifact-141ec767-40f2-4aad-9658-ac2703f3a7d9",
+            "type": "Relationship",
+            "creationInfo": "_:creationinfo1",
+            "relationshipType": "serializedInArtifact",
+            "from": "https://spdx.org/spdxdocs/Document1-7bd25aaf-64b7-4ccc-aa85-84695cef4c17",
+            "to": [
+                "https://spdx.org/spdxdocs/Artifact-4762f4c5-3362-47e9-9595-5182235ef577"
+            ]
+        }
+    ]
+}
 
    
 
-
    K.1.9 Linking to an SBOM vulnerability report for a Software Product (per NIST Executive Order 14028)
    
-
    The National Institute of Standards and Technology (NIST) describes the concept of correlating vulnerability and SBOM information for a software product at the component level in “Software Security in Supply Chains: Software Bill of Materials (SBOM)”. Use the ExternalRefs SECURITY category and advisory referenceType to report on vulnerabilities related to the components contained in a software product’s SBOM.
    
-
    This enables a software producer to articulate to software consumers the status of vulnerabilities contained in the software product, by means of reporting vulnerability information at either the SBOM document or component level.
    
-
    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.
    
-
    "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
    
-
    US Executive Order 14028 in conjunction with the National Telecommunications and Information Administration (NTIA) outlined minimum elements for an SBOM. The minimum elements are detailed in NTIA's Framing Software Component Transparency: Establishing a Common Software Bill of Maternials and The Minimum Elements for a SBOM documents and summarized below:
    
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
    SBOM Minimum FieldDescription
    Author NameAuthor of the SBOM entry (this may not always be the supplier).
    Supplier NameName or identity of the supplier of the component in the SBOM entry.
    Component NameDesignation assigned to a unit of software defined by the original supplier.
    Version StringVersion used to identify a component.
    Component HashA cryptographic hash to uniquely identify a component.
    Unique IdentifierA unique identifier to help identify components or serve as a look-up key for relevant databases.
    RelationshipCharacterizing the relationship that an upstream component X is included in software Y.
    TimestampRecord 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.
    
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
    NTIA SBOM Minimum FieldSatisfying SPDX field
    Author Name(6.8) Creator
    Supplier Name(7.5) Package Supplier
    Component Name(7.1) Package Name
    Version String(7.3) Package Version
    Component Hash(7.10) Package Checksum
    Unique Identifier(7.2) Package SPDX Identifier 
    (6.5) SPDX Document Namespace
    Relationship(11.1) Relationship: CONTAINS, DESCRIBES 
    The document must DESCRIBES at least one package.
    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.
    
-
    K.3.1 General Guidance
    
-
    If a Package can be represented as a single blob of bytes, such as a tar archive:
-  * PackageChecksum must be computed by applying one of the supported hashing algorithms to the package blob.
-  * PackageDownloadLocation should be a download locator that retrieves the package blob.
-  * A supplier can define a PackageChecksum in a Package without providing a PackageDownloadLocation. This lets consumers perform an offline verification of private blobs.
    
-
    If a Package represents an artifact that logically binds a number of single files together (such as a zip file or a directory):
-  * If the files bound by the Package are described in the document, PackageVerificationCode should be computed by using the files' SHA1 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
    
-
    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
    
-
    Guidance: 
-  * Generate a checksum for the archive file and include it in the SPDX Package checksum field. The archive file name should also be included in the Package file name field.
-  * If source files for the Package are included in the Package distribution archive, the Package verification code for that Package should also be included in the SPDX document and the Files analyzed field should be set to true.
    
-
    K.3.2.3 A Single File Represented as a SPDX Package
    
-
    Examples include: tarball, binary image, single executable
    
-
    SPDX Field To Use: 7.10 Package checksum
    
-
    Guidance: 
-  * If a Package download location 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
    
-
    SPDX Field To Use: 7.9 Package verification code
    
-
    Guidance:
-  * Include File name field in the SPDX document for every file in the directory, include each file’s cryptographic hash as a File checksum, create a CONTAINS relationship between the Package and the files, and set Files analyzed to true on the Package. Note: if Files analyzed is set to false you cannot provide a Package verification code.
    
+
    Happy Linking!
    
               
             
    
           
    
diff --git a/annexes/diffs-from-previous-editions/index.html b/annexes/diffs-from-previous-editions/index.html
index f6cc3dc..97a1ecc 100644
--- a/annexes/diffs-from-previous-editions/index.html
+++ b/annexes/diffs-from-previous-editions/index.html
@@ -61,7 +61,7 @@

licenses

@@ -809,10 +809,745 @@
-

Annex I Differences from previous editions (Informative)

-

TODO: re-write for SPDXv3

-

I.1 Differences between V2.3 and V2.2.2

-

V2.3 has added new fields to improve the ability to capture security related information and to improve interoperabiility with other SBOM formats.

+

Annex A: Differences from previous editions (Informative)

+

A.1 Differences between V3.0 and V2.3

+

Structural Differences

+

These are the most significant breaking changes requiring a change in logic to handle a different model or structure for the information. Each structural difference will describe the change, describe an approach to translate from 2.3 to 3.0, and provide a rationale for the change.

+

External Document Reference

+

Description of Change

+

The purpose of the SPDX 2.3 structure “ExternalDocumentRef” is now covered by two separate structures:

+
    +
  • NamespaceMap which maps short identifiers used in serializations to full namespace URI’s to support terseness in serialization of element identifiers
    • +
  • ExternalMap which maps an element identifier for an element defined externally to verification and location information
    • +
+

The externalDocumentRef property on the SpdxDocument has been replaced by import property and namespace property.

+

Another change is the SPDX document checksum field has been replaced with a “verifiedUsing” property on the ElementCollection. The “verifiedUsing” which has 0 or more “IntegrityMethod” which should be the checksum of the SPDX document.

+

Translating from 2.3 to 3.0

+

Each ExternalDocumentRef instance will translate as follows:

+
    +
  • An entry would be created in the Namespace map for the external document namespace
      +
    • The value of the DocumentRef-[idstring] would be used for the prefix property in the NamespaceMap.
      • +
    • The value of the documentNamespace appended with a “#” would be used for the namespace in the NamespaceMap.
      • +
    +
    • +
  • An entry would be created in the ExternalMap for the external document ref
      +
    • A string identifier consisting of the DocumentRef-[idstring] (the same value as the prefix in the NamespaceMap) concatenated with a “:” and then concatenated with “SPDXRef-DOCUMENT” would be used for the externalSpdxId in the ExternalMap.
      • +
    • An integrity method of “Hash” will be created with the same information as the checksum property and will be referenced using the “verifiedUsing” property on the ExternalMap entry.
      • +
    +
    • +
  • An entry would be created in the ExternalMap for each element referenced in the current SpdxDocument that is originally specified in the referenced SpdxDocument.
      +
    • A string identifier consisting of the DocumentRef-[idstring] (the same value as the prefix in the NamespaceMap) concatenated with a “:” and then concatenated with the local portion of the element identifier would be used for the externalSpdxId in the ExternalMap
      • +
    • A “definingDocument” property would be specified containing a string identifier consisting of the DocumentRef-[idstring] concatenated with a “:” and then concatenated with “SPDXRef-DOCUMENT”. This is a shortcut linkage to tie the referenced element to its defining SpdxDocument for verification and location information.
      • +
    +
    • +
+

Rationale

+

A key difference between SPDX 2.3 and SPDX 3.0 is that in SPDX 2.3 elements are always expressed within or referenced in relation to a single enclosing SpdxDocument while in SPDX 3.0 a key design principle is that all elements may be expressed and referenced independent of any other element including SpdxDocument. This independence is required to support a variety of content exchange and analysis use cases.

+

For example, in SPDX 2.3 if you wish to express even a single package you specify it within an SpdxDocument and its identifier namespace is restricted to the namespace of the SpdxDocument. In SPDX 3.0 you could specify a single package within an SpdxDocument element (or any other subclass of ElementCollection such as Bundle, Bom, Sbom, etc.) but you could also simply specify it on its own without any enclosing collection element. In addition, in SPDX 3.0 the identifier of the package may share a namespace with an enclosing collection element such as SpdxDocument if desired but it is equally valid for it to have any namespace desired unconstrained by any other element namespace whether it is expressed within a collection element such as SpdxDocument or not.

+

In this example, in SPDX 2.3 if you referenced the package within the same SpdxDocument that it is defined in you would utilize the local portion of its identifier and presume that the namespace is the same as the SpdxDocument namespace. If you referenced it from an SpdxDocument other than the one it is defined in you would use an ExternalDocumentRef to specify a prefix name for the other SpdxDocument to be used within the current SpdxDocument, the URI namespace/identifier for the other SpdxDocument, and a checksum for the other SpdxDocument. To reference the package you would then use an identifier combining the external document ref prefix and the local portion of the identifier.

+

The ExternalDocumentRef structure in SPDX 2.3 is based on the presumptions that elements are always defined within SpdxDocuments, that external elements can always be referenced via a containing SpdxDocument and that element identifiers have a namespace from their original containing SpdxDocument. None of these three presumptions hold true for SPDX 3.0 so a slightly modified structure is necessary to support the two use cases previously covered by ExternalDocumentRef in SPDX 2.3: 1) the ability to specify identifier namespace prefixes and accompanying namespaces for SPDX elements to support more terse serialized expression of content with integrity across serialization forms, 2) the ability to specify which elements in the current subclass of ElementCollection (e.g., SpdxDocument) are only referenced from that collection and defined elsewhere, along with details regarding their verification and location.

+

The Namespace map structure in SPDX 3.0 fully supports the namespace prefixing use case for SpdxDocuments previously covered by ExternalDocumentRef but also equally covers the same use case capability for all element types and for any number of element identifier namespaces (in SPDX 3.0 all elements within an SpdxDocument are not required to have the same namespace and can actually be any desired mix of namespaces) to support this capability required in SPDX 3.0.

+

The ExternalMap structure in SPDX 3.0 fully supports the external element (including SpdxDocument elements) referencing use case for SpdxDocuments previously covered by ExternalDocumentRef but also equally covers the same use case capability for any elements whether they were originally defined within an SpdxDocument or not to support this capability required in SPDX 3.0. The ExternalMap structure in SPDX 3.0 provides the ability to specify verification and location details for any element, not just SpdxDocuments, if appropriate but also provides simple linkage, using the “definingDocument'' property, from element entries in the ExternalMap to SpdxDocument entries in the ExternalMap where the elements were defined within the SpdxDocument and verification of the elements can be achieved via proxy to the SpdxDocument “verifiedUsing” information (this is how the SPDX 2.3 ExternalDocumentRef structure currently works).

+

Agent

+

Description of Change

+

The creator property in SPDX 2.3 has been replaced by createdBy and createdUsing properties with a type Agent and Tool resp. The supplier property has been replaced by a property suppliedBy with a type Agent. Additional suppliers can be provided with a a relationship to an availableFrom relationship. The originator property type has been replaced with the originatedBy property with a type Agent.

+

An Agent can be a Person, Organization, or Software Agent. It can also just be an Agent if it is not known what specific type an Agent is.

+

Translating from 2.3 to 3.0

+

The SPDX 2.3 creator string would be parsed and the appropriate Person, Organization or Tool would be created depending on if the prefix is “Person: ”, “Organization:” or “Tool: ” resp. The required createdBy field for Agent or Tool may point to itself if no other information is available. The createdUsing property would be used for Tool whereas the createdBy property would be used for Person and Organization. The name would map to the “name” property. If an email address is present, it would translate to an external identifier.

+

Note that in 3.0 the createdBy is a required field. There will be situations where only a Tool is provided. In that case, createdBy should point to a SoftwareAgent should be created using the same information as the Tool.

+

Rationale

+

The 3.0 format is more machine readable and structured (e.g. you do not need to parse the type from the string value). It is also more flexible in that an Agent can be used even if it is not known what the Agent type is.

+

File Type

+

Description of Change

+

The FileType enumeration has been replaced by two fields, the media type string as maintained by IANA for the content of the file and an enumeration of SoftwarePurpose for the purpose of the file.

+

The property name fileType has been replaced by a property name contentType.

+

Translating from 2.3 to 3.0

+

Rationale

+

One of the things that we identified is that FileType was being used for two things:

+
    +
  1. Describing the purpose of the file.
    2. +
  2. Describing the type of content in the file.
    3. +
+

For SPDX 3.0 we split this into two properties:

+
    +
  • SoftwarePurpose to capture the purpose (which is of type SoftwarePurpose).
    • +
  • ContentType to capture the type of content (which is of type MediaType).
    • +
+

The name ContentType was chosen to mirror the Content-Type header in HTTP (which is also of type MediaType) and to express that this is describing the type of content (as opposed to metadata, headers, or something else). For example, if (and not saying we would) we extended File in the future to be able to capture the type of executable header a file has (e.g. ELF), that could also be of type MediaType but the property name might be ExecutableHeaderType.

+

An example conversion table from SPDX 2.3 FileType to SPDX 3.0 ContentType or SoftwarePurpose can look like this:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SPDX 2 File TypeSPDX 3 Software PurposeSPDX 3 Content Type
ARCHIVEArchive
BINARYapplication/octet-stream
SOURCESource
TEXTtext/plain
APPLICATIONApplication
AUDIOaudio/*
IMAGEimage/*
VIDEOvideo/*
DOCUMENTATIONDocumentation
SPDXtext/spdx
OTHEROther
+

Package File Name

+

Description of Change

+

The packageFileName property and packageChecksum property has been replaced by a relationship from a Package to a File. A relationship type of hasDistributionArtifact should be used.

+

Translating from 2.3 to 3.0

+

Create an SPDX File with the name from the packageFileName and a verifiedUsing value from the packageChecksum for a single file. If the packageFileName is a directory, then the SPDX File is created with the directory name and is verified using the contentIdentifier property on the File and a fileKind of directory. Create a hasDistributionArifact relationship from the SPDX Package to the SPDX File.

+

Rationale

+

Providing a File relationship to the download location will include more detailed and complete information about the package file name used.

+

External Identifiers

+

Description of Change

+

In SPDX 3.0, a properties externalIdentifier and contentIdentifier with types ExternalIdentifier and ContentIdentifier were introduced. This is in addition to retaining the ExternalRef property and classes.

+

In SPDX 2.3, both identifiers and references were captured in the externalRef property for packages.

+

In addition to the structural changes, the “url” ExternalRef type was removed and is replaced by the “securityOther” ExternalRef type.

+

Translating from 2.3 to 3.0

+

The following ExternalRef Types should be converted to ExternalIdentifiers:

+
    +
  • cpe22Type
    • +
  • cpe23Type
    • +
  • swid
    • +
  • purl
    • +
+

The following ExternalRef Types should be converted to ContentIdentifers:

+
    +
  • gitoid
    • +
  • swh
    • +
+

All other ExternalRef types should remain as ExternalRef’s.

+

The url ExternalRef type should be converted to a “securityOther”.

+

Rationale

+

Distinguishing identifiers from references is key to several integrity and provenance use cases. Creating a separate property and type enables easier identification of identifiers.

+

Package URL

+

Description of Change

+

In SPDX 3.0, Package URL is a new property for Artifact which is a superclass of Package.

+

Package URL is an External Ref type in SPDX 2.3.

+

Translating from 2.3 to 3.0

+

If there is a single ExternalReference of type purl without the optional ExternalRef comment property, place that in the packageUrl property.

+

Rationale

+

Package URL is a very common method of identifying software packages. Moving this to a property makes it significantly simpler to find and correlate Package URL identifiers.

+

Annotation

+

Description of Change

+

Annotations are now subclasses of Element, so it inherits a number of new optional properties including names, annotations, and its own relationships.

+

Annotations are no longer a property of an Element. It is now a standalone element with a “subject” field which points to the Element being annotated.

+

Translating from 2.3 to 3.0

+

A new Annotation element would be created for every annotation property in an element (Package, File or Snippet). The subject property would point to the Element which has the Annotation as a property.

+

The annotator from SPDX 2.3 should be translated to one of the creators for the creationInfo for the Annotation and the annotationDate should be translated to the created field in the same creationInfo. The creationInfo for the Annotation should be the creationInfo of the SPDX 2.3 document.

+

The SPDX 2.3 “comment” should use the statement field in SPDX 3.0.

+

Rationale

+

Changing from a property to a standalone element allows for relationships to exist outside the element itself (e.g. you can now create an amended SPDX document which has a new annotation for an element defined in the original document). This also supports third parties' ability to assert Annotations on Elements that they did not create.

+

Relationship

+

Description of Change

+

The structure of the Relationship class has changed to have a single direction and allow more than one related SPDX Elements. Relationships are now subclasses of Element, so it inherits a number of new optional properties including names, annotations, and its own relationships.

+

Relationships are no longer a property of an Element. It is now a standalone element with a “from” and “to” field.

+

A new property “completeness' ' complements the use of NONE and NOASSERTION for the related SPDX elements.

+

Translating from 2.3 to 3.0

+

The “from” property would be populated by the SPDX Element which has the relationship property. The “to” property will be the relatedSpdxElement.

+

When translating the relationshipType, the “from” and “to” may need to be swapped - the table below will have a “Y” in the “Swap to and from?” column when this is necessary.

+

The completeness property would be constructed based on the following:

+
    +
  • “to” value is NONE: complete
    • +
  • “to” value is NOASSERTION: noAssertion
    • +
  • “to” value is an SPDX element: No value for the completeness - uses the default
    • +
+

Relationship migration is being worked out in the relationships spreadsheet. Once completed, the following table will reflect the translation for relationship types from SPDX 2.3 to SPDX 3.0:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SPDX 2.3 Relationship TypeSPDX 3.0 Relationship TypeSwap to and from?LifecycleScopeType
AMENDSamendedByY
ANCESTOR_OFancestorOf
BUILD_DEPENDENCY_OFdependsOn
BUILD_TOOL_OFusesToolbuild (all lifecycle scope could be appropriate)
CONTAINED_BYcontainsY
CONTAINScontains
COPY_OFcopiedTo
DATA_FILE_OFhasDataFile
DEPENDENCY_MANIFEST_OFhasDependencyManifest
~~DEPENDENCY_OF~~[removed]
DEPENDS_ONdependsOnvarious LifecycleScopeType
DESCENDANT_OFdecendentOf
~~DESCRIBED_BY~~[removed]
DESCRIBESdescribes
DEV_DEPENDENCY_OFdependsOndevelopment
DEV_TOOL_OFusesTooldevelopment
DISTRIBUTION_ARTIFACThasDistributionArtifact
DOCUMENTATION_OFhasDocumentation
DYNAMIC_LINKhasDynamicLinkbuild, runtime
EXAMPLE_OFhasExample
EXPANDED_FROM_ARCHIVEexpandsTo
FILE_ADDEDhasAddedFile
FILE_DELETEDhasDeletedFile
FILE_MODIFIEDmodifiedBy
GENERATED_FROMgeneratesY
GENERATESgenerates
HAS_PREREQUISITEhasPrequisitelifecycle scope
METAFILE_OFhasMetadata
OPTIONAL_COMPONENT_OFhasOptionalComponent
OPTIONAL_DEPENDENCY_OFhasOptionalDependencylifecycle scope
OTHERother
PACKAGE_OFpackagedBy
~~PATCH_FOR~~[removed]
~~PREREQUISITE_FOR[removed]
PROVIDED_DEPENDENCY_OFhasProvidedDependencylifecycle scope
REQUIREMENT_DESCRIPTION_FORhasRequirementlifecycle scope
RUNTIME_DEPENDENCY_OFdependsOnruntime
SPECIFICATION_FORhasSpecificationlifecycle scope
STATIC_LINKhasStaticLinklifecycle scope
TEST_CASE_OFhasTestCase
TEST_DEPENDENCY_OFdependsOntest
TEST_OFhasTestlifecycle scope
TEST_TOOL_OFusesTooltest
VARIANT_OFhasVarient
+

Rationale

+

The addition of the completeness attribute is clearer than the use of NONE and NOASSERTION.

+

Changing from a property to a standalone element allows for relationships to exist outside the element itself (e.g. you can now create an amended SPDX document which has a new relationship for an element defined in the original document). This enables primary Element creating parties as well as third parties to express significantly greater contextual detail among content they create as well as content created by others.

+

Snippet

+

Description of Change

+

Byte and line range types have been changed from a StartEndPointer type to a PositiveIntegerRange. Byte range is now optional.

+

Translating from 2.3 to 3.0

+

Iterate through the “ranges” property. Any startPointer and endPointer with a property of “offset” would be translated to a snippetByteRange property. Any startPointer and endPointer with a property of “lineNumber” would translate to a snippetLineRange property.

+

A new Relationship would be created with the “from” pointing to the snippetFromFile and the “to” pointing to the Snippet. They relationshipType would be CONTAINS.

+

Rationale

+

Using the W3C Pointer standard introduced significant complexity in the SPDX 2.X specification. Although there may be some benefit in using a published standard, we have not found any instances where the W3C Pointer ontology was useful for SPDX use cases.

+

Changing the snippetFromFile from a property to a relationship [to be filled in].

+

SpecVersion

+

Description of Change

+

The type of SpecVersion is changed from a simple string without constraints to a SemVer string which must follow the Semantic Versioning format.

+

This adds a constraint where a patch version is required. Previous usage of the SpecVersiononly included the major and minor version.

+

Translating from 2.3 to 3.0

+

Add a patch version of “0” to any previous spec version.

+

Rationale

+

The additional constraints align with best practices for versioning strings.

+

LicenseListVersion

+

Description of Change

+

The type of LicenseListVersion is changed from a simple string without constraints to a SemVer string which must follow the Semantic Versioning format.

+

This adds a constraint where a patch version is required. Previous usage of the SPDX license list only included the major and minor version.

+

Translating from 2.3 to 3.0

+

Add a patch version of “0” to any previous license list version.

+

Rationale

+

The additional constraints align with best practices for versioning strings.

+

Properties Removed

+

Below is a list of properties present in 2.3 and not present in 3.0. The Range / Where used is where the property was used in the SPDX 2.3 model.

+

example

+

SPDX 2.3 Model Name

+

example

+

Tag/Value Name

+

Not used

+

Range / Where Used

+

LicenseException

+

Rationale

+

This field has not been used.

+

LicenseInfoInFiles

+

SPDX 2.3 Model Name

+

licenseInfoInFiles

+

Tag/Value Name

+

LicenseInfoInFiles

+

Range / Where Used

+

Package

+

Rationale

+

This field is redundant with the declaredLicense property in the Files contained in the Package. It is recommended that the licenseInfoInFiles can be added as an Annotation to the Package in the format: “SPDX 2.X LicenseInfoInFiles: [expression1], [expression2]” where the [expressions] are the string representation of the license expressions.

+

FilesAnalyzed

+

SPDX 2.3 Model Name

+

filesAnalyzed

+

Tag/Value Name

+

FilesAnalyzed

+

Range / Where Used

+

Package

+

Rationale

+

Many users of the SPDX 2.X spec reported this property as very confusing.

+

NOTE: There is no longer a way to specific checksums are required for files. This is being tracked in Issue #84.

+

Naming Differences

+

Below is a list of properties and classes where the name has been changed from 2.3 to 3.0. The Range / Where used is where the property was used in the SPDX 2.3 model.

+

Release Date

+

SPDX 2.3 Model Name

+

releaseDate

+

Tag/Value Name

+

ReleaseDate

+

New Name

+

releaseTime

+

Range / Where Used

+

Package

+

Rationale

+

Better reflects the granularity of the field.

+

Build Date

+

SPDX 2.3 Model Name

+

buildDate

+

Tag/Value Name

+

BuildDate

+

New Name

+

buildTime

+

Range / Where Used

+

Package

+

Rationale

+

Better reflects the granularity of the field.

+

Valid Until Date

+

SPDX 2.3 Model Name

+

validUntilDate

+

Tag/Value Name

+

ValidUntilDate

+

New Name

+

validUntilTime

+

Range / Where Used

+

Package

+

Rationale

+

Better reflects the granularity of the field.

+

External Document Reference

+

SPDX 2.3 Model Name

+

externalDocumentRef

+

Tag/Value Name

+

ExternalDocumentRef

+

New Name

+

import

+

Range / Where Used

+

SpdxDocument (Creation Information)

+

Rationale

+

Feedback from SPDX 2.X usage is that externalDocumentRef is confusing due to the similar externalRef property.

+

NOTE: See structural changes related to this property

+

Checksum Class / Data Type

+

SPDX 2.3 Model Name

+

Checksum class name and checksum property name

+

Tag/Value Name

+

FileChecksum, PackageChecksum

+

New Name

+

verifiedUsing property and Hash class

+

Range / Where Used

+

Package, File

+

Rationale

+

More general concept allowing for different verification algorithms for different scenarios.

+

Checksum Algorithm

+

SPDX 2.3 Model Name

+

checksumAlgorithm

+

Tag/Value Name

+

N/A - parsed from a string following the Checksum: keyword.

+

New Name

+

hashAlgorithm

+

Range / Where Used

+

Package, File

+

Rationale

+

The term “hash” better represents the intent of this property which is to validate the integrity of the data whereas the term “checksum” is typically for the purpose of error checking.

+

Name

+

SPDX 2.3 Model Name

+

packageName, fileName

+

Tag/Value Name

+

PackageName, FileName

+

New Name

+

name

+

Range / Where Used

+

Package, File

+

Rationale

+

In the SPDX 2.3 RDF Ontology, both spdx:fileName and spdx:packageName are sub-properties of spdx:name. The OWL has a restriction that spdx:File has exactly one spdx:fileName and spdx:Package has exactly one spdx:packageName.

+

Changing these restrictions to just spdx:name would simplify the model.

+

Version

+

SPDX 2.3 Model Name

+

versionInfo

+

Tag/Value Name

+

PackageVersion

+

New Name

+

packageVersion

+

Range / Where Used

+

Package

+

Rationale

+

This change would make the Tag/Value and RDF values consistent.

+

Home Page

+

SPDX 2.3 Model Name

+

doap:homepage

+

Tag/Value Name

+

PackageHomePage

+

New Name

+

homePage

+

Range / Where Used

+

Rationale

+

Uses a consistent namespace for SPDX properties.

+

Annotation Comment

+

SPDX 2.3 Model Name

+

rdfs:comment

+

Tag/Value Name

+

AnnotationComment

+

New Name

+

statement

+

Range / Where Used

+

Element (Package, File, Snippet)

+

Rationale

+

The rdfs:comment property is optional and has slightly different semantics in other uses (e.g. comments on Elements). Changing the property name clearly distinguishes this usage as a mandatory property for an Annotation.

+

With Exception Operator

+

SPDX 2.3 Model Name

+

WithExceptionOperator

+

member property in WithExceptionOperator

+

licenseException property in WithExceptionOperator

+

Tag/Value Name

+

With (part of License Expression)

+

New Name

+

WithAdditionOperator

+

subjectLicense

+

subjectAddition

+

Range / Where Used

+

Package, File, Snippet

+

Rationale

+

Custom Additions have been added in SPDX 3.0 which operate in a similar manner to listed License Exceptions. The new type and property names are more general to accommodate both custom additions and listed license Exceptions.

+

License Exception

+

SPDX 2.3 Model Name

+

LicenseException

+

licenseExceptionId property in LicenseException

+

licenseExceptionText property in LicenseException

+

name property in LicenseException

+

Tag/Value Name

+

Not used in Tag/Value

+

New Name

+

ListedLicenseException

+

additionId

+

additionText

+

additionName

+

Range / Where Used

+

Package, File, Snippet

+

Rationale

+

Custom Additions have been added in SPDX 3.0 which operate in a similar manner to listed License Exceptions. The new type and property names are more general to accommodate both custom additions and listed license Exceptions.

+

ExtractedLicenseInfo

+

SPDX 2.3 Model Name

+

ExtractedLicenseInfo

+

Tag/Value Name

+

ExtractedText

+

New Name

+

CustomLicense

+

Range / Where Used

+

Package, File, Snippet, Document

+

Rationale

+

The SPDX 2.X term implied that the only property was text when in fact there are several properties in common with the listed licenses. See model issue #233 for context.

+

licenseComment

+

SPDX 2.3 Model Name

+

licenseComment

+

Tag/Value Name

+

LicenseName

+

New Name

+

name

+

Range / Where Used

+

License, ListedLicense, ExtractedText

+

Rationale

+

“name” is used in the Element class. Since License is a type of (subclass of) Element, it should use the same field otherwise there would be redundant fields for the same purpose.

+

LicenseComment

+

SPDX 2.3 Model Name

+

licenseComment

+

Tag/Value Name

+

LicenseComment

+

New Name

+

comment

+

Range / Where Used

+

License, ListedLicense

+

Rationale

+

“comment” is used in the Element class. Since License is a type of (subclass of) Element, it should use the same field otherwise there would be redundant fields for the same purpose.

+

LicenseID

+

SPDX 2.3 Model Name

+

licenseId

+

Tag/Value Name

+

LicenseId

+

New Name

+

spdxId

+

Range / Where Used

+

License, ListedLicense

+

Rationale

+

“spdxId” is used in the Element class. Since License is a type of (subclass of) Element, it should use the same field otherwise there would be redundant fields for the same purpose.

+

Range / Where Used

+

License, ListedLicense

+

Rationale

+

Primary Package Purpose

+

SPDX 2.3 Model Name

+

primaryPackagePurpose

+

Tag/Value Name

+

PrimaryPackagePurpose

+

New Name

+

primaryPurpose

+

Range / Where Used

+

Package

+

Rationale

+

The purpose property is now available for files and snippets in addition to Package resulting in a more general name of primaryPurpose.

+

Note that additional purposes can be added using the additionalPurpose property.

+

Serialization Formats

+

SPDX 3.0 implements a JSON-LD format which has consistent class and property names with the model.

+

See the SPDX 3.0 JSON Schema for the format specifics.

+

The Tag/Value, YAML, RDF/XML and Spreadsheet formats are not supported.

+

Additional serialization formats are being considered for the SPDX 3.1 release.

+

A.2 Differences between V2.3 and V2.2.2

+

V2.3 has added new fields to improve the ability to capture security related information and to improve interoperability with other SBOM formats.

Key changes include:

  • @@ -843,7 +1578,7 @@

    I.1 Differences between V2.3 and V2

    Added Annex K ( How To Use SPDX in Different Scenarios ) to illustrate linking to external security information, and illustrate how the NTIA SBOM mandatory minimum elements map to SPDX fields.

-

I.2 Differences between V2.2.2 and V2.2.1

+

A.3 Differences between V2.2.2 and V2.2.1

V2.2.2 fixed formatting, grammatical and spelling issues found since ISO/IEC 5962:2021 SPDX v2.2.1 was published. No new fields were added.

Key changes include:

    @@ -863,7 +1598,7 @@

    I.2 Differences between V2.2.2 and

    It fixed annex lettering inconsistencies. It also moved CC-BY-3.0 to the end of the spec to keep annex letters more consistent in future versions. Here is the translation between lettering in V2.2.2 and the version that came before it:

-

Table I.1 — SPDX V2.2.2 Organizational Changes

+

Table A.1 — SPDX V2.2.2 Organizational Changes

@@ -901,9 +1636,9 @@

I.2 Differences between V2.2.2 and

*This edition featured inconsistent lettering.

-

I.3 Differences between V2.2.1 and V2.2

+

A.4 Differences between V2.2.1 and V2.2

There were no technical differences; V2.2.1 is V2.2 reformatted for submission to ISO via the PAS process. As a result, new clauses were added causing the previous clause-numbering sequence to change. Also, Annexes went from having Roman numbers to Latin letters. Here is the translation between numbering in V2.2.1 and the version that came before it:

-

Table I.2 — SPDX V2.2.1 Organizational Changes

+

Table A.2 — SPDX V2.2.1 Organizational Changes

@@ -1055,7 +1790,7 @@

I.3 Differences between V2.2.1 and

*This edition featured inconsistent lettering.

-

I.4 Differences from V2.2 and V2.1

+

A.5 Differences from V2.2 and V2.1

-

I.5 Differences between V2.1 and V2.0

+

A.6 Differences between V2.1 and V2.0

  • Snippets have been added to allow a portion of a file to be identified as having different properties from the file it resides in. The use of snippets is completely optional and it is not mandatory for snippets to be identified. See section 5 Snippet Information for further details on the fields available to describe snippets.

    @@ -1095,7 +1830,7 @@

    I.5 Differences between V2.1 and V2.

    Miscellaneous bug fixes.

-

I.6 Differences between V2.0 and V1.2

+

A.7 Differences between V2.0 and V1.2

  • Abstraction has been applied to the underlying model with the inclusion of SPDX elements. With SPDX 2.0, the concept of an SPDX element is introduced (see Appendix III). This includes SPDX documents, SPDX files, and SPDX packages, each of which gets associated with an SPDX identifier which is denoted by “SPDXRef-”.

    @@ -1124,7 +1859,7 @@

    I.6 Differences between V2.0 and V1.

diff --git a/annexes/getting-started/index.html b/annexes/getting-started/index.html new file mode 100644 index 0000000..e7726bb --- /dev/null +++ b/annexes/getting-started/index.html @@ -0,0 +1,1440 @@ + + + + + + + + Getting started with SPDX 3 - SPDX v3 Specification + + + + + + + + + + + + + + +
+ + +
+ +
+
+
    +
    • +
  • annexes
    • +
  • Getting started with SPDX 3
    • +
  • +
    • +
+
+
+
+
+ +

Annex B: Getting started writing SPDX 3 (Informative)

+

(a.k.a My First SPDX File)

+

This guide is designed to walk you through the concepts behind an SPDX +document, by walking through writing one by hand. While it is possible to write +all your SPDX documents by hand, we would recommend looking at the various +language bindings that are available for crafting more complex documents. +Nevertheless, walking through an example of a hand written document can be +instructive into how SPDX documents work to better understand concepts that are +at play, even when using language bindings.

+

All of the provided fragments listed here are intended to be used to construct +a complete a valid SPDX JSON document when concatenated together

+

If you do would like to construct the complete example from this Markdown file, +use the following command:

+
cat getting-started.md | awk 'BEGIN{flag=0} /^```json/, $0=="```" { if (/^---$/){flag++} else if ($0 !~ /^```.*/ ) print $0 > "doc-" flag ".spdx.json"}'
+
+ +

Please note that all descriptions of properties, classes, etc. are +non-normative; that is they are intended to help you understand what is going +on in simpler language, but are not necessarily complete. Links to the full +official documentation are provided where possible.

+

The Preamble

+

All documents need to start somewhere, and SPDX documents are no exception.

+

The root of all SPDX documents will be a JSON object, so start with that:

+
{
+
+ +

Next, we need to identify that the document is an SPDX 3 JSON-LD document, which is done with:

+
    "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld",
+
+ +

SPDX documents are designed to be a strict subset of JSON-LD, such that +they can be parsed using either a full JSON-LD parser if you need the full +power of linked documents or RDF, or a much simpler JSON parser if +all you care about is extracting meaningful SPDX data from the document.

+

Because the document is valid JSON-LD, the @context must be provided to tell +the JSON-LD parser how to expand the human readable names in the document into +full IRIs (don't worry if you don't know what that means, it's not really that +important). You can think of this line as telling us "This is an SPDX document, +and this provided URL tells us how to decode it". The SPDX JSON +Schema will force you to put the correct value here when +validating a document.

+

Now, we need to specify the list of objects that we want to create in this +document. JSON-LD has a special way of specifying this list using the @graph +property of the root object like so:

+
    "@graph": [
+
+ +

Tell us about yourself

+

Our first SPDX object is going to be a Person that tells us who +is writing this document (you!), so lets get started with it:

+
        {
+            "type": "Person",
+
+ +

This is the basic format for any object in SPDX; all objects have one required +property named type that tells us what this object actually is, so here we +say this is a Person.

+

Next, we need to name our object:

+
            "spdxId": "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9",
+
+ +

Most objects can have some sort of "ID" property that gives it a name. In the +case of Person, that property is called spdxId (inherited +from Element). This property is the URI that should give this +object a universally unique name. Although this property looks like a HTTP +URL, it is in fact not. Technically speaking, a URL defined a Location, where +as a URI defines an Identifier (i.e. the name by which something is known). +In all likelihood, a URI is not a resolvable location from whence you can do an +HTTP GET to retrieve data, but rather just a way of constructing a namespaced +identifier. This identifier can be used within this document to refer to this +object (more on that later), or it can be referenced from other documents to +refer to this specific object (although in that case there needs to be +additional information to describe how to find this document). URI's are +considered to be universally unique, so any objects constructed with this URI +are considered to be the same object, and any references to this URI is a +reference to this specific object we are creating.

+

If you work for a company, own a domain, etc. it is encouraged to use that (or +some subdomain of it) in place of spdx.org/spdxdocs.

+

In practice, many spdxId values will have some sort of hash or random +UUID-like string incorporated to make them unique.

+

Moving on from this, we have:

+
            "creationInfo": "_:creationinfo",
+
+ +

All SPDX objects derived from Element must specify how they +were created by linking to a CreationInfo object. It is +important to know the providence of where objects come from; but more on this +later.

+
            "name": "Joshua Watt",
+
+ +

The optional name property is inherited from the Element +class, and means "the common name for the thing", or in this case, your name.

+

As our last step, we want to indicate another way by which You are known to the +world; specifically your E-mail address.

+

To do this we first need to use the (optional) +externalIdentifier property which +Person inherits from Element:

+
            "externalIdentifier": [
+
+ +

This property is an array of ExternalIdentifier +objects, so start by adding one to the array:

+
                {
+                    "type": "ExternalIdentifier",
+
+ +

Again notice this uses the type property to identify what the object is. +However it should be noted that this is our first object that is not derived +from Element, and therefore it does not need a spdxId +property.

+

Next, lets add the relevant information about your email address:

+
                    "externalIdentifierType": "email",
+                    "identifier": "JPEWhacker@gmail.com"
+
+ +

Two properties are used here. First, +externalIdentifierType is used to indicate +what type of external identifier this is. There are many choices, but in the +case we are specifying your email address, so we choose the value email. The +second property is the indentifier property which is the +actual string identifier (in this case, your email address).

+

We are now done with our Person, so close it all out and +prepare for the next object:

+
                }
+            ]
+        },
+
+ +

Where did all this stuff come from?

+

Our next object is going to be a CreationInfo object. It +is required to provide one for every SPDX document, as all objects derived from +Element must link to one in their +creationInfo property to indicate where they came +from.

+

Note that the CreationInfo describes where a SPDX +Element itself came from (that is, who wrote the actual JSON). +This is a distinct concept from describing where the thing an +Element describes comes from, which is covered later.

+

Lets get started:

+
        {
+            "type": "CreationInfo",
+
+ +

Hopefully this is making sense. We are saying this object is a +CreationInfo.

+
            "@id": "_:creationinfo",
+
+ +

This object also has an @id similar to the spdxId of our person, but it is +subtly different First of all, this one is not a URI like our +Person, but instead starts with a _:. This type of identifier +is known as a blank node. Blank nodes serve a similar purpose to the URI of +the spdxId, however they only have scope within this SPDX document. What +this means is that it be impossible to reference this +CreationInfo by name outside of this document. Inside the +document, you can use this identifier to refer to this object. The string after +the _: is arbitrary and you may choose whatever unique (within the document) +string that you choose.

+

It should be noted that CreationInfo does not derive +from Element class (like our previous example of +ExternalIdentifier), and as such the @id property +is technically optional. However, since we will need to refer to this object at +other places in the document, we must give it an identifier. This also means +that this object does not have a mandatory +creationInfo property (which makes sense since it +would be a circular reference). Finally, CreationInfo is +only allowed to have a blank node identifier.

+

If you look back at the Person we just created, you'll notice +that its creationInfo property has the string value +that matches the @id of this object; this is how objects are linked together +by reference in SPDX.

+

Next, we need to specify which version of the SPDX spec that elements linking +to this CreationInfo are conforming to:

+
            "specVersion": "3.0.0",
+
+ +

Now, we need to use the createdBy property to indicated +who (or what) created the elements that are linked to this +CreationInfo:

+
            "createdBy": [
+                "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9"
+            ],
+
+ +

This property is a list of reference to any class that derives from +Agent. Since you are the person writing the document, put a +single list item that is the spdxId of your Person element +here to link them together. Note that even though this is using a full URI +instead of a blank node, this is linking in the same way as +creationInfo described above.

+

Also, it is worth noting that this does indeed create a circular reference +between our Person.creationInfo +property and CreationInfo.createdBy +property. This is fine in SPDX, as objects are not required to be a Directed +Acyclical Graph (DAG).

+

Finally, we need to specify the date that any objects linking to this +CreationInfo were created using the +created property and close out the object:

+
            "created": "2024-03-06T00:00:00Z"
+        },
+
+ +

Use today's date and time in ISO 8601 with the format: +"%Y-%m-%dT%H:%M:%SZ". The timezone should always be UTC.

+

Describing the Document

+

SPDX requires that information about the document itself be provided. In order +to do this, we must create a SpdxDocument object, so lets +do that now:

+
        {
+            "type": "SpdxDocument",
+            "spdxId": "https://spdx.org/spdxdocs/Document1-d078aed9-384d-4a64-87cb-99c79647c8c9",
+            "creationInfo": "_:creationinfo",
+
+ +

SpdxDocument derives from Element, so it +has 3 required properties, type, spdxId and +creationInfo. We've seen all of these properties +before in Person, so hopefully this getting more familiar. Note +that we again link back out our previous CreationInfo +object.

+

Next, we need to indicate which Profiles our document uses +using the profileConformance property. This can +be used by consumers of the document to quickly determine if the information +they want is in the document (for example, if a user wants to find CVE data, +but the security profile is not present, there is no reason to continue +looking in this document).

+
            "profileConformance": [
+                "core",
+                "software"
+            ],
+
+ +

In this case, we are saying this document conforms to the core profile (all +SPDX documents should include this), and the software profile, since we will +be describing some software later.

+

The final property we need to define is rootElement. +This property is a list of Element (or any subclass of +Element) references. Add this now and close our our +SpdxDocument:

+
            "rootElement": [
+                "https://spdx.org/spdxdocs/BOM-e2e955f5-c50e-4a3a-8c69-db152f0f4615"
+            ]
+        },
+
+ +

The purpose of this property is to indicate the "interesting" element(s) in the +document. Since a document can contain a large number of elements, it might be +difficult for a consumer of the document to know what the focus of the document +is. This property clarifies that by suggesting which element(s) a user should +look at to start navigating. While it is possible to have more than one root +element, it is rare to need more than one.

+

Careful readers of the SpdxDocument documentation will +note that we have omitted the element (derived from the +ElementCollection parent class). Technically +speaking, the property should link to all the elements that are in the +document using this property. However because this would be error prone, it is +implied that all Element objects present in the @graph (that +is, all the objects we are writing) are implicitly added to the +element property.

+

A Complete Document!

+

At this point, we have a completed SPDX document (albeit, one that has an +unresolved references in +SpdxDocument.rootElement). This +is a fully valid document because it has the SPDX 3.0 preamble, and the +required SpdxDocument object, which in turn requires a +valid CreationInfo, which we've provided. Finally, the +CreationInfo requires an Agent to describe +who or what created the Elements in the document, which we've provided by +writing a Person object which describes you.

+

While this is the minimal example, it may feel long. However, as we continue in +the document it should become more apparent how reuse of these 3 objects +(particularly the CreationInfo) helps reduce total +document size while still conveying precise information. In addition, there are +other options to make a more compact document that are not covered yet, such as +referring to a external Agent instead of encoding it in the +document.

+

Lets Add Some Software!

+

Now that we have the basic valid document, its time to start adding some +interesting data to it. Lets start with a fictitious software package called +amazing-widget which we distribute as a tarball for users to download and run.

+

To start with, we need to define a software_Package +object the defines how our software is distributed. In this case, the +software_Package will be describing a tarball which +someone can download, but it can be almost any unit of content that can be used +to distribute software (either as binaries or source). See the documentation +for more details.

+

Lets define our package:

+
        {
+            "type": "software_Package",
+            "spdxId": "https://spdx.org/spdxdocs/Package-d1db6e61-aebe-4b13-ae73-d0f66018dbe0",
+            "creationInfo": "_:creationinfo",
+
+ +

This should be familiar by now. Note the reuse of our previous +CreationInfo.

+

Also note that this is our first element that is outside of the Core profile +in SPDX. In this specific case, the class is defined in the Software profile, +and as such is prefixed with software_. Any classes and properties that are +defined in a profile other than Core will be prefixed with the lower case +profile name + _ to disambiguate them from classes and properties with the +same name in other profiles.

+

Again, we can use Element.name to give the +common name for our package:

+
            "name": "amazing-widget",
+
+ +

Importantly, even though this is a class defined in the Software profile, +name is defined in core so it does not get prefixed. When +writing objects, pay attention to which profile the property is defined in, +as that sets the prefix (the documentation should make it clear what the +serialized name of a property is if you are unsure TODO: It does not yet).

+

Next, we will define what version the amazing-widget package is using +software_packageVersion, and where the user +could download this package from using +software_downloadLocation (both are +optional):

+
            "software_packageVersion": "1.0",
+            "software_downloadLocation": "http://dl.example.com/amazing-widget_1.0.0.tar",
+
+ +

These are our first two examples of properties not defined in the Core +profile, and as such they get the software_ prefix.

+

Now, we should define when this software was packaged using the (optional) +builtTime property, so that downstream users can tell how +old it is:

+
            "builtTime": "2024-03-06T00:00:00Z",
+
+ +

Note that we are back in the Core profile properties here (specifically, +builtTime is a property of Artifact in +Core)

+

Next, we want to indicate who actually made the package we are describing. This +is done using the (optional) originatedBy array +property:

+
            "originatedBy": [
+                "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9"
+            ],
+
+ +

In this example, you can put a single element that references your +Person spdxId here to indicate that you actually made the +package. Note that while we are using the same spdxId as we used in the +CreationInfo, this is not required. +originatedBy is the property that we used to describe +who made the actual package being described by the +software_Package and not the JSON object itself.

+

Finally, we would like to inform consumers of our SPDX how they can validate +the package to ensure its contents have not changed, or to check if a file that +they have is the same one being described by this document. This is done using +the verifiedUsing property, which is an array of +IntegrityMethod objects (or subclasses).

+
            "verifiedUsing": [
+                {
+                    "type": "Hash",
+                    "algorithm": "sha256",
+                    "hashValue": "f3f60ce8615d1cfb3f6d7d149699ab53170ce0b8f24f841fb616faa50151082d"
+                }
+            ]
+        },
+
+ +

Specifically, we are using the Hash subclass of integrity method to +indicate that the SHA-256 checksum of the package file is +f3f60ce8615d1cfb3f6d7d149699ab53170ce0b8f24f841fb616faa50151082d

+

Whats in our Package?

+

Describing that we have a distributed package is a great start, but we are able +to go further (although this is not mandatory!). Our next object is going to +describe all the files contained in our +software_Package by using +software_File.

+

Lets get started with our first file, the program executable:

+
        {
+            "type": "software_File",
+            "spdxId": "https://spdx.org/spdxdocs/File-8f79956e-4089-4166-9a71-457de77e4846",
+            "creationInfo": "_:creationinfo",
+            "name": "/usr/bin/amazing-widget",
+            "verifiedUsing": [
+                {
+                    "type": "Hash",
+                    "algorithm": "sha256",
+                    "hashValue": "ee4f96ed470ea288be281407dacb380fd355886dbd52c8c684dfec3a90e78f45"
+                }
+            ],
+            "builtTime": "2024-03-05T00:00:00Z",
+            "originatedBy": [
+                "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9"
+            ],
+
+ +

We've seen all this before, so hopefully it all makes sense.

+

While it's great to have a file, it's not easy to tell what purpose this file +serves. We might be able to infer that its an executable program from the +name, but SPDX provides the ability for us to directly specify +this using the (optional) +software_primaryPurpose and +software_additionalPurpose properties +(derived from sofware_Artifact):

+
            "software_primaryPurpose": "executable",
+            "software_additionalPurpose": [
+                "application"
+            ],
+
+ +

A software_Artifact can have as many purposes a you +want to describe, but there should always be a +software_primaryPurpose property defined +before any software_additionalPurpose +are added.

+

Finally, as one last bit of information, we'll say what the copyright text of +the program is using the (optional) +software_copyrightText property and close +out our file:

+
            "software_copyrightText": "Copyright 2024, Joshua Watt"
+        },
+
+ +

Lets add one more file for fun. This one will describe a config file for our +program:

+
        {
+            "type": "software_File",
+            "spdxId": "https://spdx.org/spdxdocs/File-77808a5c-7a1b-43d1-9fa9-410a309ca9f3",
+            "creationInfo": "_:creationinfo",
+            "name": "/etc/amazing-widget.cfg",
+            "verifiedUsing": [
+                {
+                    "type": "Hash",
+                    "algorithm": "sha256",
+                    "hashValue": "89a2e80bc48c4dd10044c441af0fc6fdad5d31b2fa391cb2cf9c51dbf4200ed9"
+                }
+            ],
+            "builtTime": "2024-03-05T00:00:00Z",
+            "originatedBy": [
+                "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9"
+            ],
+            "software_primaryPurpose": "configuration"
+        },
+
+ +

Linking things together with Relationships

+

Now we've described our software_Package, and two +software_Files that should be contained in it, but we +have one small problem: there is nothing that tells us that our files are +actually contained by the package.

+

In order to do this, we must introduce the SPDX +Relationship. These are a very powerful concept in SPDX +that allows linking Elements and describing how they are +related.

+

Relationships themselves are also derived from SPDX +Elements, so we need the required three properties to start a +new one:

+
        {
+            "type": "Relationship",
+            "spdxId": "https://spdx.org/spdxdocs/Relationship/contains-6b0b7ce4-a069-406d-9088-9e91f65b79f0",
+            "creationInfo": "_:creationinfo",
+
+ +

Next, we need to say what the relationship between our objects is going to be. +We do this using the relationshipType property:

+
            "relationshipType": "contains",
+
+ +

The full list of what a Relationship can describe is +defined by the RelationshipType vocabulary (a fancy +work for enumeration). There are a lot of possible options, and each one has a +specific meaning and restrictions on what types it can relate, so read the +documentation to find the specific one you need and how to use it. In our case, +we are using contains which is defined as "The from +Element contains each to Element". Perfect.

+

Now, we need to describe what Elements are being connected. +Relationships always have a directionality associated +with them: you can think of them as an arrow pointing from their +from property to their to properties. +from is always required and must be a single object, whereas +to is a list of zero or more objects. Lets write the JSON to +express this:

+
            "from": "https://spdx.org/spdxdocs/Package-d1db6e61-aebe-4b13-ae73-d0f66018dbe0",
+            "to": [
+                "https://spdx.org/spdxdocs/File-8f79956e-4089-4166-9a71-457de77e4846",
+                "https://spdx.org/spdxdocs/File-77808a5c-7a1b-43d1-9fa9-410a309ca9f3"
+            ],
+
+ +

This is the minimum required to define a Relationship, +but we want to add one more property to convey additional information and close +out the object:

+
            "completeness": "complete"
+        },
+
+ +

The completeness property is very useful as it +indicates if we know that this Relationship can be +considered to describe all we know about the type of relationship or not. For +example, by stating that this relationship is complete, we are saying that +our package contains those 2 files, and only those 2 files. We could have +also stated that the relationship was incomplete in which case we are stating +that we know we didn't list all the files, and other are included. +Alternatively, we could have stated that the relationship +completeness was noAssertion meaning we don't know +if we captured all the files or not. If this property is omitted, it's assumed +to be noAssertion.

+

Wrapping it all up in a BOM

+

We've made great progress, and we are almost done. For our final step, we +want to wrap up everything we know about the package into a "Software Bill of +Materials".

+

This is done by creating a software_Sbom object:

+
        {
+            "type": "software_Sbom",
+            "spdxId": "https://spdx.org/spdxdocs/BOM-e2e955f5-c50e-4a3a-8c69-db152f0f4615",
+            "creationInfo": "_:creationinfo",
+
+ +

Note that this is the object referenced by the rootElement of +our SpdxDocument, since it is the primary subject of our entire +document.

+

software_Sbom derives from +ElementCollection just like +SpdxDocument, so it has the same +rootElement property. In this case, it is the subject +of the SBOM, which is our software_Package:

+
            "rootElement": [
+                "https://spdx.org/spdxdocs/Package-d1db6e61-aebe-4b13-ae73-d0f66018dbe0"
+            ],
+
+ +

Unlike SpdxDocument however, there is no implicit value +for the element property. Instead, we need to list all the +elements that are part of this SBOM (think of this as the line items in the +SBOM). In our specific case, this is the software_Files +that part of our package, but if you had any other elements related to the +package (e.g. licenses, security information, etc.) those would also be +included:

+
            "element": [
+                "https://spdx.org/spdxdocs/File-8f79956e-4089-4166-9a71-457de77e4846",
+                "https://spdx.org/spdxdocs/File-77808a5c-7a1b-43d1-9fa9-410a309ca9f3"
+            ],
+
+ +

Finally, we need to specify what type(s) of BOM this is using the +software_sbomType property:

+
            "software_sbomType": [
+                "build"
+            ]
+        }
+
+ +

This property is effectively indicating at what point in the software lifecycle +this SBOM was generated. Since we are describing an executable program, build +seems the most likely.

+

Closing it all up

+

Now that we are all done, we have a few things to clean up, namely that we need +to close the @graph list and the root object, so lets do that now:

+
    ]
+}
+
+ +

Congratulations! You just wrote your first SPDX document! Hopefully this +walk through has been instructive and you are ready to get started with SPDX!

+ +
+
+ +
+
+ +
+ +
+ +
+ + + + « Previous + + + Next » + + +
+ + + + + + + + + diff --git a/annexes/file-tags/index.html b/annexes/including-security-information-in-SPDX/index.html similarity index 51% rename from annexes/file-tags/index.html rename to annexes/including-security-information-in-SPDX/index.html index 7784e1b..57f477d 100644 --- a/annexes/file-tags/index.html +++ b/annexes/including-security-information-in-SPDX/index.html @@ -5,7 +5,7 @@ - Specifying SPDX information in source files (Informative) - SPDX v3 Specification + Including Security Information in SPDX - SPDX v3 Specification @@ -13,8 +13,8 @@ @@ -61,7 +61,7 @@
    @@ -756,10 +756,10 @@

annexes

-
    +

    licenses

    @@ -797,7 +825,8 @@
      • -
    • Specifying SPDX information in source files (Informative)
      • +
    • annexes
      • +
    • Including Security Information in SPDX
    @@ -806,120 +835,357 @@
    -

    Specifying SPDX information in source files (Informative)

    -

    TODO: re-write for SPDXv3

    -

    H.1 Rationale

    -

    SPDX short-form license identifiers using the SPDX-License-Identifier: tag, as described in Annex E, provide a mechanism for developers to easily convey information about the licenses they declare on a file-by-file basis. That mechanism is intentionally very easy for software tools to identify and detect, since it includes a standard text string that is unlikely to occur in other contexts, and since it uses license identifiers from the SPDX License List or from user-defined LicenseRef- statements.

    -

    The SPDX specification defines various other fields in the File Information section (Clause 8) that are also useful for conveying information on a file-by-file basis, as well as snippet-level information in Snippet Information section (Clause 9). For example, the REUSE Software guidelines community expressed interest in having a similar method to recommend that developers use to express their copyright notices in a machine-readable manner.

    -

    This appendix describes a mechanism, similar to SPDX-License-Identifier, for developers to convey such other file-based and snippet-based information easily in comments in their files. This in turn enables software tools to easily find and extract that information, and to insert it into the corresponding fields of an SPDX document generated by those tools.

    -

    H.2 File tags format

    -

    An SPDX file tag consists of a single line, generally as part of a comment near the top of the file, in the following format:

    -
    SPDX-tagname: <value>
+                
    Annex G: Including Security Information in a SPDX document
    
+
    The flexibility of SPDX 3.0 allows users to either link SBOMs to external security vulnerability data or to embed security vulnerability information in the SPDX 3.0 data format. For more details about the differences, read "Capturing Software Vulnerability Data in SPDX 3.0".
    
+
    G.1 External References and External Identifiers
    
+
    SPDX 3.0 has the concept of an External Reference for an Element which points to a general resource outside the scope of the SPDX-3.0 content that provides additional context or information about an Element.
    
+
    The specification for External Reference types has many type options, a large handful of which pertain specifically to security use cases:
    
+
      
+
    • cwe
      • 
+
    • secureSoftwareAttestation
      • 
+
    • securityAdvisory
      • 
+
    • securityAdversaryModel
      • 
+
    • securityFix
      • 
+
    • securityOther
      • 
+
    • securityPenTestReport
      • 
+
    • securityPolicy
      • 
+
    • securityThreatModel
      • 
+
    • vulnerabilityDisclosureReport
      • 
+
    • vulnerabilityExploitabilityAssessment
      • 
+
    
+
    SPDX 3.0 also has the concept of External Identifier which should be used in cases where an identifier scheme exists and is already defined for an Element outside of SPDX-3.0.
    
+
    There are several External Identifier types that may be used in a security context:
    
+
      
+
    • cpe22
      • 
+
    • cpe23
      • 
+
    • cve
      • 
+
    • packageUrl
      • 
+
    • securityOther
      • 
+
    
+
    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 pages. Multiple instances and types of external security information may be included within a SPDX document.
    
+
    G.1.1 Linking to an Advisory
    
+
    To reference a Common Vulnerabilities and Exposures (CVE) advisory applicable to a package, you must first create a Vulnerability Element. You can then use ExternalIdentifiers or ExternalRefs to supplement the CVE with associated external metadata.
    
+
    {
+  "type": "security_Vulnerability",
+  "spdxId": "urn:spdx.dev:cve-2020-2849",
+  "creationInfo": "_:creationInfo",
+  "summary": "Use of a Broken or Risky Cryptographic Algorithm",
+  "description": "The npm package `elliptic` before version 6.5.4 are vulnerable to Cryptographic Issues via the secp256k1 implementation in elliptic/ec/key.js. There is no check to confirm that the public key point passed into the derive function actually exists on the secp256k1 curve. This results in the potential for the private key used in this implementation to be revealed after a number of ECDH operations are performed.",
+  "security_modifiedTime": "2021-03-08T16:06:43Z",
+  "security_publishedTime": "2021-03-08T16:02:50Z",
+  "externalIdentifier": [
+    {
+      "type": "ExternalIdentifier",
+      "externalIdentifierType": "cve",
+      "identifier": "CVE-2020-2849",
+      "identifierLocator": [
+        "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-28498",
+        "https://www.cve.org/CVERecord?id=CVE-2020-28498"
+      ],
+      "issuingAuthority": "urn:spdx.dev:agent-cve.org"
+    },
+    {
+      "type": "ExternalIdentifier",
+      "externalIdentifierType": "securityOther",
+      "identifier": "GHSA-r9p9-mrjm-926w",
+      "identifierLocator": ["https://github.com/advisories/GHSA-r9p9-mrjm-926w"]
+    }
+  ],
+  "externalRef": [
+    {
+        "type": "ExternalRef",
+        "externalRefType": "securityAdvisory",
+        "locator": ["https://nvd.nist.gov/vuln/detail/CVE-2020-28498"]
+    },
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityAdvisory",
+      "locator": ["https://ubuntu.com/security/CVE-2020-28498"]
+    },
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityOther",
+      "locator": ["https://github.com/indutny/elliptic/pull/244/commits"]
+    }
+  ]
+},
 
    
 
-
    where tagname is replaced by the 'tag' defined for tag-value SPDX documents for that field, according to the File Information section of the SPDX specification. The meaning and semantics of any SPDX file tag are intended to be identical to those described in the File Information (Clause 8) section of the SPDX specification.
    
-
    Examples:
    
-
    File type (see 8.3):
    
-
    SPDX-FileType: SOURCE
-SPDX-FileType: DOCUMENTATION
-SPDX-FileType: TEXT
+
    G.1.2 Linking to a CSAF Document
    
+
    To reference CSAF formatted security information see below for examples.
    
+
    G.1.2.1 Linking to a CSAF VEX
    
+
    To reference a CSAF VEX document, include an external reference of type vulnerabilityExploitabilityAssessment on the Vulnerability Element that encapsulates the CVE described in the CSAF VEX document.
    
+
    {
+  "type": "security_Vulnerability",
+  "spdxId": "urn:spdx.dev:vuln-2",
+  "creationInfo": "_:creationInfo",
+  "name": "cve-2021-44228",
+  "description": "Apache Log4j2 2.0-beta9 through 2.15.0 (excluding security releases 2.12.2, 2.12.3, and 2.3.1) JNDI features used in configuration, log messages, and parameters do not protect against attacker controlled LDAP and other JNDI related endpoints. An attacker who can control log messages or log message parameters can execute arbitrary code loaded from LDAP servers when message lookup substitution is enabled.",
+  "security_modifiedTime": "2021-03-08T16:02:43Z",
+  "security_publishedTime": "2021-03-08T16:06:50Z",
+  "externalIdentifier": [
+    {
+      "type": "ExternalIdentifier",
+      "externalIdentifierType": "cve",
+      "identifier": "CVE-2021-44228",
+      "identifierLocator": [
+        "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44228",
+        "https://www.cve.org/CVERecord?id=CVE-2021-44228"
+      ],
+      "issuingAuthority": "http://spdx.dev/agent-cve.org"
+    }
+  ],
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "vulnerabilityExploitabilityAssessment",
+      "locator": ["https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/examples/csaf/csaf_vex/2022-evd-uc-01-a-001.json"]
+    }
+  ]
+},
 
    
 
-
    Copyright text (see 8.8):
    
-
    SPDX-FileCopyrightText: 2019 Jane Doe <jane@example.com>
-SPDX-FileCopyrightText: Copyright 2008-2010 John Smith
-SPDX-FileCopyrightText: Copyright Example Company
-SPDX-FileCopyrightText: Copyright contributors to the Foo project.
+
    G.1.2.2 Linking to a CSAF Advisory
    
+
    To reference a CSAF Advisory document, include the document locator as an external reference of type securityAdvisory on a Package Element.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:pkg-rh-open-shift",
+  "creationInfo": "_:creationInfo",
+  "name": "Red Hat OpenShift Enterprise",
+  "software_packageVersion": "3.6",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityOther",
+      "locator": ["https://github.com/oasis-tcs/csaf/blob/master/csaf_2.0/examples/csaf/rhsa-2019_1862.json"]
+    }
+  ]
+},
 
    
 
-
    File contributors (see 8.14):
    
-
    SPDX-FileContributor: Modified by Jane Doe
-SPDX-FileContributor: The Regents of the University of California
+
    G.1.3 Linking to CycloneDX Security Data
    
+
    To reference to CycloneDX formatted security information applicable to a package you need to first create a Package Element.
    
+
    Using an External Reference, link the package to the matching component in the CycloneDX BOM. Link to it using its BOM link, a URN formed by combining the CycloneDX serial number, version and bom-ref which contains the security information about the package.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:pkg-stack-cors",
+  "creationInfo": "_:creationInfo",
+  "name": "stack-cors",
+  "software_packageVersion": "1.3.0",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityOther",
+      "locator": ["https://cyclonedx.org/capabilities/bomlink/17cfc349-c637-4685-856c-81196420c7f5/2#componentRef"]
+    }
+  ]
+},
 
    
 
-
    SPDX file tags of a particular type may appear one or multiple times in a file, depending on the corresponding cardinality defined for that field in the File Information section of the SPDX specification.
    
-
    Multiple-line values are not recommended, because doing so will make it harder for simple search tools to extract all data by looking only for lines beginning with the relevant tag.
    
-
    Version 3.0 of the REUSE Software guidelines implements this format, via a recommendation to use the tag SPDX-FileCopyrightText: to include copyright notices as part of a file's comment headers.
    
-
    H.3 Snippet tags format 
    
-
    If certain SPDX tags are to apply only to a certain snippet instead of the whole file, SPDX snippet tags should be used.
    
-
    SPDX snippet tags should start with SPDX-SnippetBegin to mark the beginning of the snippet and end with SPDX-SnippetEnd to mark its end, in the following format:
    
-
    SPDX-SnippetBegin
-SPDX-tagname: <value>
-
-...
-
-SPDX-SnippetEnd
+
    G.1.4 Linking to an OSV
    
+
    To include a reference to Open Source Vulnerability (OSV) formatted security information applicable to a package you need to first create a Package Element. Then use an External Reference to link to the OSV advisory.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:pkg-Django",
+  "creationInfo": "_:creationInfo",
+  "name": "Django",
+  "software_packageVersion": "2.2",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityAdvisory",
+      "locator": ["https://github.com/github/advisory-database/blob/6b9d5bc96a62bb845ee71e4551a214eb1457e2c6/advisories/github-reviewed/2022/04/GHSA-2gwj-7jmv-h26r/GHSA-2gwj-7jmv-h26r.json"]
+    }
+  ]
+},
 
    
 
-
    where tagname is replaced by the 'tag' defined for tag-value SPDX documents for that field, according to the Snippet Information section of the SPDX specification, and ... represents the code snippet itself. The meaning and semantics of any SPDX snippet tag are intended to be identical to those described in the Snippet Information (Clause 9) section of the SPDX specification.
    
-
    Any Snippet Information (Clause 9) and short-form license identifiers (Annex E) tags found between begin and end tags mentioned above apply only to such snippet.
    
-
    Snippets may nest, and this is denoted by having SPDX-SnippetBegin/SPDX-SnippetEnd pairs within other pairs, in the same way that parentheses nest in mathematical expressions. In the case of nested snippets, the SPDX file tags are considered to apply to the inner-most snippet.
    
-
    Examples:
    
-
    Simple stand-alone example:
    
-
    SPDX-SnippetBegin
-SPDX-License-Identifier: MIT
-SPDX-SnippetCopyrightText: 2022 Jane Doe <jane@example.com>
-
-...
-
-SPDX-SnippetEnd
+
    G.1.5 Linking to an OmniBOR (formerly known as GitBOM)
    
+
    To identify a Package with an OmniBOR (Universal Bill Of Receipts, formerly known as GitBOM) gitoid, use an External Identifier to add gitoid to the package.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:pkg-example",
+  "creationInfo": "_:creationInfo",
+  "name": "Example",
+  "software_packageVersion": "1.2.3",
+  "externalIdentifier": [
+    {
+      "type": "ExternalIdentifier",
+      "externalIdentifierType": "gitoid",
+      "identifier": "gitoid:blob:sha1:bcb99b819dadaebdf2c8f88d92ee9024c45f9df3"
+    }
+  ]
+},
 
    
 
-
    Two snippets with a different license and additional information in the broader context of a file:
    
-
    SPDX-License-Identifier: GPL-2.0-or-later
-SPDX-FileCopyrightText: Copyright contributors to the Foo project.
-
-...
-
-SPDX-SnippetBegin
-SPDX-License-Identifier: MIT
-SPDX-SnippetCopyrightText: 2022 Jane Doe <jane@example.com>
-SDPX—SnippetName: functionX from project Bar
-SPDX-SnippetComment: A complex function X that was copy-pasted from project Bar
-
-...
-
-SPDX-SnippetEnd
-
-...
-
-SPDX-SnippetBegin
-SPDX-License-Identifier: BSD-2-Clause
-SPDX-SnippetCopyrightText: Copyright Example Company
-
-...
-
-SPDX-SnippetEnd
+
    G.1.6 Linking to a vulnerability disclosure document
    
+
    To express a reference to a vulnerability disclosure document for a package, use an External Reference for a Package Element. The example below shows Cisco’s response to Apache log4j vulnerability.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:pkg-apache-log4j",
+  "creationInfo": "_:creationInfo",
+  "name": "log4j",
+  "software_packageVersion": "2.14.0",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityAdvisory",
+      "locator": ["https://sec.cloudapps.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-apache-log4j-qRuKNEbd"]
+    }
+  ]
+},
 
    
 
-
    Nesting snippets:
    
-
    SPDX-SnippetBegin
-SPDX-License-Identifier: MIT
-SPDX-SnippetCopyrightText: 2022 Jane Doe <jane@example.com>
+
    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 using an External Reference on the package.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:example-1",
+  "creationInfo": "_:creationInfo",
+  "name": "example",
+  "software_packageVersion": "1.0.0",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityAdvisory",
+      "locator": ["https://example.com/product-x/security-info-not-affected.html"]
+    }
+  ]
+},
+
    
 
-...
+
    To refer to a security disclosure feed, such as the security bulletins from CERT-EU, include an External Reference in the package Element.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:example-2",
+  "creationInfo": "_:creationInfo",
+  "name": "example",
+  "software_packageVersion": "2.0.0",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityAdvisory",
+      "locator": ["https://cert.europa.eu/cert/Data/newsletter/reviewlatest-SecurityBulletins.xml"]
+    }
+  ]
+},
+
    
 
-SPDX-SnippetBegin
-SPDX-License-Identifier: BSD-2-Clause
-SPDX-SnippetCopyrightText: Copyright Example Company
+
    G.1.7 Linking to a Code Fix for a Security Issue
    
+
    You can include a reference to a code fix for a security issue applicable to a Package or Vulnerability Element.
    
+
    Using the Vulnerability Element from example 1.1 above or a Package Element, you would add a code fix External Reference to the Element as follows. In this example, the link points to a specific code revision containing the fix for CVE-2020-28498.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:example-2",
+  "creationInfo": "_:creationInfo",
+  "name": "example",
+  "software_packageVersion": "2.0.0",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityFix",
+      "locator": ["https://github.com/indutny/elliptic/commit/441b7428b0e8f6636c42118ad2aaa186d3c34c3f"],
+      "comment": "elliptic before version 6.5.4 are vulnerable to Cryptographic Issues via the secp256k1 implementation in elliptic/ec/key.js. This patch fixes CVE-2020-28498."
+    }
+  ]
+},
+
    
 
-...
+
    A fix reference may point to a configuration change for example the patch file as one of the fixes for CVE-2022-26499.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:example-2",
+  "creationInfo": "_:creationInfo",
+  "name": "example",
+  "software_packageVersion": "2.0.0",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityFix",
+      "locator": ["https://downloads.digium.com/pub/security/AST-2022-002-16.diff"]
+    }
+  ]
+},
+
    
 
-SPDX-SnippetEnd
+
    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.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:example-2",
+  "creationInfo": "_:creationInfo",
+  "name": "example",
+  "software_packageVersion": "2.0.0",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityFix",
+      "locator": ["https://www.oracle.com/security-alerts/cpujan2022.html"]
+    }
+  ]
+},
+
    
 
-... 
+
+
    If you want to reference any security information related to a package but cannot or do not wish to specify its kind, use the securityOther externalRefType.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:pkg-elliptic",
+  "creationInfo": "_:creationInfo",
+  "name": "elliptic",
+  "software_packageVersion": "6.5.4",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityOther",
+      "locator": ["https://github.com/christianlundkvist/blog/blob/aa3a69b5e4c06e4435070610c0c4a2b1e8731783/2020_05_26_secp256k1_twist_attacks/secp256k1_twist_attacks.md"],
+      "comment": "Blog post from author who wrote fix for CVE-2020-28498."
+    }
+  ]
+},
+
    
 
-SPDX-SnippetEnd
+
    One can also use it to refer to guidance related to a vulnerability such as CISA guidance for Apache Log4j.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:pkg-apache-log4j",
+  "creationInfo": "_:creationInfo",
+  "name": "log4j",
+  "software_packageVersion": "2.14.0",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "securityOther",
+      "locator": ["https://www.cisa.gov/uscert/apache-log4j-vulnerability-guidance"]
+    }
+  ]
+},
 
    
 
-
    H.4 Caveats 
    
-
    A creator of an SPDX document may elect to disregard any or all file tags in any file. SPDX document creators should determine for themselves the extent to which they will rely upon the information specified in a file tag.
    
-
    Not all fields in the File Information section will be useful or relevant to use as file tags. For example, SPDX-FileName is unnecessary as it can be easily derived from the actual file name; SPDX-SPDXID is likely to be ignored by an SPDX document creator who may need to define their own SPDXRef- ID system for their document; etc.
    
-
    Another more complex example are SPDX-SnippetBegin and SPDX-SnippetEnd where the line number these two tags are found in could be stored to start and end the range in SnippetLineRange (see 9.4).
    
-
    The short-form license identifiers described in Annex E do not follow the file tag convention described above. The SPDX-License-Identifier emerged from the broader community prior to being defined in the SPDX specification, so it does not map to a License-Identifier field in the File Information section.
    
+
    G.1.9 Linking to a Vulnerability Disclosure Report (VDR)
    
+
    The National Institute of Standards and Technology (NIST) describes the concept of correlating vulnerability and SBOM information for a software product at the component level in “Software Security in Supply Chains: Software Bill of Materials (SBOM)”. Use the External Reference vulnerabilityDisclosureReport type to report on vulnerabilities related to the components contained in a software product’s SBOM.
    
+
    This enables a software producer to articulate to software consumers the status of vulnerabilities contained in the software product, by means of reporting vulnerability information at either the SBOM document or component level.
    
+
    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.
    
+
    {
+  "type": "software_Package",
+  "spdxId": "urn:spdx.dev:sag-pm",
+  "creationInfo": "_:creationInfo",
+  "name": "SAG-PM (TM)",
+  "software_packageVersion": "1.1.8",
+  "externalRef": [
+    {
+      "type": "ExternalRef",
+      "externalRefType": "vulnerabilityDisclosureReport",
+      "locator": ["https://github.com/rjb4standards/REA-Products/blob/master/SBOM_and_VDRbaseline/sag-pm-118_VDR.json"]
+    }
+  ]
+},
+
    
               
             
    
           
    
diff --git a/annexes/using-SPDX-short-identifiers-in-source-files/index.html b/annexes/using-SPDX-short-identifiers-in-source-files/index.html
index accd4c2..9e2dbae 100644
--- a/annexes/using-SPDX-short-identifiers-in-source-files/index.html
+++ b/annexes/using-SPDX-short-identifiers-in-source-files/index.html
@@ -61,7 +61,7 @@

licenses

@@ -817,7 +817,7 @@
-

Annex E Using SPDX license list short identifiers in source files (Informative)

+

Annex E: Using SPDX license list short identifiers in source files (Informative)

TODO: update for SPDXv3

E.1 Introduction

Identifying the license for open source software is critical for both reporting purposes and license compliance. However, determining the license can sometimes be difficult due to a lack of information or ambiguous information. Even when licensing information is present, a lack of consistent notation can make automating the task of license detection very difficult, thus requiring vast amounts of human effort.

@@ -874,6 +874,7 @@

E.4 Representing multiple licenses

diff --git a/annexes/using-SPDX-lite/index.html b/annexes/using-SPDX-to-comply-with-industry-guidance/index.html similarity index 85% rename from annexes/using-SPDX-lite/index.html rename to annexes/using-SPDX-to-comply-with-industry-guidance/index.html index adbb292..f67e754 100644 --- a/annexes/using-SPDX-lite/index.html +++ b/annexes/using-SPDX-to-comply-with-industry-guidance/index.html @@ -5,7 +5,7 @@ - Using SPDX Lite (Informative) - SPDX v3 Specification + Using SPDX to comply with norms, standards and regulation - SPDX v3 Specification @@ -13,8 +13,8 @@ @@ -61,7 +61,7 @@
    @@ -756,10 +756,10 @@

annexes

-
@@ -797,7 +803,8 @@
    • -
  • Using SPDX Lite (Informative)
    • +
  • annexes
    • +
  • Using SPDX to comply with norms, standards and regulation
@@ -806,11 +813,115 @@
-

Using SPDX Lite (Informative)

-

TODO: re-write for SPDXv3

+

Annex F: Using SPDX to comply with Norms, Standards and Regulation (Informative)

+

F.1 Satisfying NTIA Minimum Elements for an SBOM using SPDX / US Executive Order 14028

+

US Executive Order 14028 in conjunction with the National Telecommunications and Information Administration (NTIA) outlined minimum elements for an SBOM. The minimum elements are detailed in NTIA's Framing Software Component Transparency: Establishing a Common Software Bill of Maternials and The Minimum Elements for a SBOM documents and summarized below:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SBOM Minimum FieldDescription
Author NameAuthor of the SBOM entry (this may not always be the supplier).
Supplier NameName or identity of the supplier of the component in the SBOM entry.
Component NameDesignation assigned to a unit of software defined by the original supplier.
Version StringVersion used to identify a component.
Component HashA cryptographic hash to uniquely identify a component.
Unique IdentifierA unique identifier to help identify components or serve as a look-up key for relevant databases.
RelationshipCharacterizing the relationship that an upstream component X is included in software Y.
TimestampRecord of the date and time of the SBOM data assembly.
+

The SPDX Specification contains fields able to address each of the NTIA minimum required data fields.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NTIA SBOM Minimum FieldSatisfying SPDX field model location
Author NameCore/Classes/CreationInfo.createdBy
Supplier NameCore/Classes/Artifact.suppliedBy
Component NameSoftware/Classes/Package.name inherited from Core/Classes/Element.name
Version StringSoftware/Classes/Package.packageVersion
Component HashCore/Classes/Element.verifiedUsing
Unique IdentifierSoftware/Classes/SoftwareArtifact.contentIdentifier for SPDX Software Artifacts or Software/Classes/Package.packageUrl if the packageUrl is considered to be unique,
or Core/Classes/Element.externalIdentifier for resources outside the scope of SPDX-3.0 content
RelationshipCore/Classes/Relationship
TimestampCore/Classes/CreationInfo.created
+

F.2 BSI TR-03183 - Technical Guideline Cyber Resilience Requirements for Manufacturers and Products

+

The German BSI is actively propagating its technical guideline in preparation for adopting and detailing the +requirements of the EU Cyber Resilience Act +becoming effective in 2027.

+

The guideline can be regarded as German equivalent of the US Executive Order 14028. Nevertheless, BSI is exploring +various options and recommendations to further detail the content of SBOMs.

+

Important elements of the guideline in the context of SPDX: +* The guideline references SPDX as one of the exchange formats for SBOMs. +* It defines levels of details as well as mandatory and optional data fields. +* The guideline scopes the content (dependency relationships) of an SBOM (top-level, n-level, transitive, delivery item, complete). +* Different types of SBOMs (design, source, build, analysed, deployed, runtime) are defined.

+

The guideline (available in version 1.1) is currently being revised by the BSI. Draft versions of the future 2.0 document +are circulated by the BSI to collect review comments.

+

See BSI Technical Guideline TR-03183.

diff --git a/bibliography/index.html b/bibliography/index.html index 1c8d831..53c7244 100644 --- a/bibliography/index.html +++ b/bibliography/index.html @@ -61,7 +61,7 @@
@@ -810,13 +810,13 @@

Bibliography

The following documents are useful references for implementers and users of this document:

-

[1] Software Package Data Exchange (SPDX®) Specification Version 1.0 and 1.1, 1.2, 2.0, 2.1, and 2.2; SPDX.dev, https://spdx.dev/specifications

+

[1] Software Package Data Exchange (SPDX®) Specification Version 1.0 and 1.1, 1.2, 2.0, 2.1, 2.2, and 2.3; SPDX.dev, https://spdx.dev/specifications

[2] Open Source Initiative (OSI); https://opensource.org/licenses