diff --git a/README.md b/README.md index 9034faf..118c040 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,3 @@ # using + Information on how to use the SPDX specification diff --git a/docs/getting-started.md b/docs/getting-started.md index fa0f344..6522673 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,4 +1,5 @@ # Getting started writing SPDX 3 + ## (a.k.a My First SPDX File) This guide is designed to walk you through the concepts behind an SPDX @@ -29,14 +30,17 @@ official documentation are provided where possible. 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: + ```json { ``` Next, we need to identify that the document is an SPDX 3 JSON-LD document, which is done with: + ```json "@context": "https://spdx.org/rdf/3.0.0/spdx-context.jsonld", ``` + SPDX documents are designed to be a strict subset of [JSON-LD][1], such that they can be parsed using either a full JSON-LD parser if you need the full power of [linked documents][2] or [RDF][3], or a much simpler JSON parser if @@ -50,15 +54,14 @@ and this provided URL tells us how to decode it". The [SPDX JSON Schema][spdxjsonschema] 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: + ```json "@graph": [ ``` - ## Tell us about yourself Our first SPDX object is going to be a [Person][Class_Person] that tells us who @@ -74,6 +77,7 @@ property named `type` that tells us what this object actually is, so here we say this is a [Person][Class_Person]. Next, we need to name our object: + ```json "spdxId": "http://spdx.org/spdxdocs/Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9", @@ -102,6 +106,7 @@ 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: + ```json "creationInfo": "_:creationinfo", ``` @@ -156,7 +161,6 @@ case we are specifying your email address, so we choose the value `email`. The second property is the [indentifier][Property_identifier] property which is the actual string identifier (in this case, your email address). - We are now done with our [Person][Class_Person], so close it all out and prepare for the next object: @@ -166,7 +170,6 @@ prepare for the next object: }, ``` - ## Where did all this stuff come from? Our next object is going to be a [CreationInfo][Class_CreationInfo] object. It @@ -181,10 +184,12 @@ This is a distinct concept from describing where the thing an [Element][Class_Element] _describes_ comes from, which is covered later. Lets get started: + ```json { "type": "CreationInfo", ``` + Hopefully this is making sense. We are saying this object is a [CreationInfo][Class_CreationInfo]. @@ -207,7 +212,7 @@ It should be noted that [CreationInfo][Class_CreationInfo] does _not_ derive from [Element][Class_Element] class (like our previous example of [ExternalIdentifier][Class_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 +other places in the document, we must give it an identifier. This also means that this object does not have a mandatory [creationInfo][Property_creationInfo] property (which makes sense since it would be a circular reference). Finally, [CreationInfo][Class_CreationInfo] is @@ -238,7 +243,7 @@ who (or what) created the elements that are linked to this This property is a list of reference to any class that derives from [Agent][Class_Agent]. Since you are the person writing the document, put a single list item that is the `spdxId` of your [Person][Class_Person] element -here to link them together. Note that even though this is using a full URI +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][Property_creationInfo] described above. @@ -248,7 +253,6 @@ property and [CreationInfo][Class_CreationInfo].[createdBy][Property_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][Class_CreationInfo] were created using the [created][Property_created] property and close out the object: @@ -261,7 +265,6 @@ Finally, we need to specify the date that any objects linking to this Use today's date and time in [ISO 8601][4] 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 @@ -362,12 +365,14 @@ to distribute software (either as binaries or source). See the documentation for more details. Lets define our package: + ```json { "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][Class_CreationInfo]. @@ -389,7 +394,7 @@ Importantly, even though this is a class defined in the `Software` profile, [name][Property_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*). +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][Property_software_packageVersion], and where the user @@ -405,7 +410,6 @@ optional): 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_builtTime] property, so that downstream users can tell how old it is: @@ -418,7 +422,6 @@ Note that we are back in the `Core` profile properties here (specifically, [builtTime][Property_builtTime] is a property of [Artifact][Class_Artifact] in `Core`) - Next, we want to indicate who actually made the package we are describing. This is done using the (optional) [originatedBy][Property_originatedBy] array property: @@ -458,7 +461,6 @@ Specifically, we are using the [Hash][Class_Hash] subclass of integrity method t 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 @@ -553,7 +555,7 @@ 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][Class_Relationship]. These are a very powerful concept in SPDX +[Relationship][Class_Relationship]. These are a very powerful concept in SPDX that allows linking [Element][Class_Element]s and describing how they are related. @@ -656,7 +658,7 @@ for the [element][Property_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_File][Class_software_File]s 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 +package (e.g. licenses, security information, etc.) those would also be included: ```json diff --git a/docs/including-security-information-in-SPDX.md b/docs/including-security-information-in-SPDX.md index 7214726..549c65f 100644 --- a/docs/including-security-information-in-SPDX.md +++ b/docs/including-security-information-in-SPDX.md @@ -3,6 +3,7 @@ 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"](https://spdx.dev/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__](https://github.com/spdx/spdx-3-model/blob/main/model/Core/Classes/ExternalRef.md) 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](https://github.com/spdx/spdx-3-model/blob/main/model/Core/Vocabularies/ExternalRefType.md), a large handful of which pertain specifically to security use cases: @@ -19,7 +20,6 @@ The specification for External Reference types has many [type options](https://g * vulnerabilityDisclosureReport * vulnerabilityExploitabilityAssessment - SPDX 3.0 also has the concept of [__External Identifier__](https://github.com/spdx/spdx-3-model/blob/main/model/Core/Classes/ExternalIdentifier.md) 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](https://github.com/spdx/spdx-3-model/blob/main/model/Core/Vocabularies/ExternalIdentifierType.md) that may be used in a security context: @@ -30,7 +30,6 @@ There are several External Identifier [types](https://github.com/spdx/spdx-3-mod * 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](https://github.com/spdx/spdx-3-model/tree/main/model/Security/Classes) pages. Multiple instances and types of external security information may be included within a SPDX document. ## G.1.1 Linking to an Advisory @@ -89,8 +88,8 @@ To reference a Common Vulnerabilities and Exposures (CVE) advisory applicable to To reference [CSAF](https://docs.oasis-open.org/csaf/csaf/v2.0/cs01/csaf-v2.0-cs01.html) 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. +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. ```json { @@ -124,6 +123,7 @@ To reference a CSAF VEX document, include an external reference of type `vulnera ``` ### 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. ```json @@ -143,7 +143,6 @@ To reference a CSAF Advisory document, include the document locator as an extern }, ``` - ## G.1.3 Linking to CycloneDX Security Data To reference to [CycloneDX](https://cyclonedx.org) formatted security information applicable to a package you need to first create a Package Element. @@ -188,12 +187,10 @@ To include a reference to [Open Source Vulnerability](https://github.com/google/ }, ``` - ## G.1.5 Linking to an OmniBOR (formerly known as GitBOM) To identify a Package with an [OmniBOR](https://omnibor.io/) (Universal Bill Of Receipts, formerly known as GitBOM) gitoid, use an External Identifier to add gitoid to the package. - ```json { "type": "software_Package", @@ -253,7 +250,6 @@ To communicate that a package is not vulnerable to a specific vulnerability it i To refer to a security disclosure feed, such as the security bulletins from [CERT-EU](https://cert.europa.eu), include an External Reference in the package Element. - ```json { "type": "software_Package", @@ -333,7 +329,6 @@ Alternatively, it may also link to a landing page with patches for a variety of }, ``` - ## G.1.8 Linking to any Security Related Document 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. diff --git a/docs/using-SPDX-short-identifiers-in-source-files.md b/docs/using-SPDX-short-identifiers-in-source-files.md index a87fcb2..82d89e3 100644 --- a/docs/using-SPDX-short-identifiers-in-source-files.md +++ b/docs/using-SPDX-short-identifiers-in-source-files.md @@ -18,7 +18,7 @@ Identifying the license for open source software is critical for both reporting * An SPDX short identifier is immutable. * Easy look-ups and cross-references to the SPDX License List website. -If using SPDX short identifiers in individual files, it is recommended to reproduce the full license in the projects LICENSE file and indicate that SPDX short identifiers are being used to refer to it. +If using SPDX short identifiers in individual files, it is recommended to reproduce the full license in the projects LICENSE file and indicate that SPDX short identifiers are being used to refer to it. For links to projects illustrating these scenarios, see . ## Format for `SPDX-License-Identifier` @@ -62,7 +62,7 @@ SPDX-License-Identifier: GPL-2.0-or-later WITH Bison-exception-2.2 Please see the specification Annex for more examples and details of the license expression specific syntax. -If you can’t express the license(s) as an expression using identifiers from the SPDX list, it is probably best to just put the text of your license header in the file (if there is a standard header), or refer to a neutral site URL where the text can be found. To request a license be added to the SPDX License List, please follow the process described here: [https://github.com/spdx/license-list-XML/blob/master/CONTRIBUTING.md](https://github.com/spdx/license-list-XML/blob/master/CONTRIBUTING.md). +If you can’t express the license(s) as an expression using identifiers from the SPDX list, it is probably best to just put the text of your license header in the file (if there is a standard header), or refer to a neutral site URL where the text can be found. To request a license be added to the SPDX License List, please follow the process described here: . Alternatively, you can use a `LicenseRef-` custom license identifier to refer to a license that is not on the SPDX License List, such as the following: diff --git a/docs/using-SPDX-to-comply-with-industry-guidance.md b/docs/using-SPDX-to-comply-with-industry-guidance.md index 996c541..f9c7417 100644 --- a/docs/using-SPDX-to-comply-with-industry-guidance.md +++ b/docs/using-SPDX-to-comply-with-industry-guidance.md @@ -15,36 +15,36 @@ US Executive Order 14028 in conjunction with the National Telecommunications and | Relationship | Characterizing the relationship that an upstream component X is included in software Y. | | Timestamp | Record of the date and time of the SBOM data assembly. | - The SPDX Specification contains fields able to address each of the NTIA minimum required data fields. | NTIA SBOM Minimum Field | Satisfying SPDX field model location | | ----------- | :----------- | | Author Name | [Core/Classes/CreationInfo.createdBy](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/CreationInfo/) | -| Supplier Name | [Core/Classes/Artifact.suppliedBy ](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Artifact/) | +| Supplier Name | [Core/Classes/Artifact.suppliedBy](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Artifact/) | | Component Name | [Software/Classes/Package.name](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) inherited from [Core/Classes/Element.name](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) | | Version String | [Software/Classes/Package.packageVersion](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) | -| Component Hash | [Core/Classes/Element.verifiedUsing](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) | -| Unique Identifier | [Software/Classes/SoftwareArtifact.contentIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/SoftwareArtifact/) for SPDX Software Artifacts or [Software/Classes/Package.packageUrl](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) if the packageUrl is considered to be unique,
or [Core/Classes/Element.externalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) for resources outside the scope of SPDX-3.0 content
| +| Component Hash | [Core/Classes/Element.verifiedUsing](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) | +| Unique Identifier | [Software/Classes/SoftwareArtifact.contentIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/SoftwareArtifact/) for SPDX Software Artifacts or [Software/Classes/Package.packageUrl](https://spdx.github.io/spdx-spec/v3.0/model/Software/Classes/Package/) if the packageUrl is considered to be unique,
or [Core/Classes/Element.externalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) for resources outside the scope of SPDX-3.0 content | | Relationship | [Core/Classes/Relationship](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Relationship/) | | Timestamp | [Core/Classes/CreationInfo.created](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/CreationInfo/) | ## 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](https://www.europarl.europa.eu/doceo/document/TA-9-2024-0130_EN.html) +The German BSI is actively propagating its technical guideline in preparation for adopting and detailing the +requirements of the [EU Cyber Resilience Act](https://www.europarl.europa.eu/doceo/document/TA-9-2024-0130_EN.html) 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: +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 +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](https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Publications/TechGuidelines/TR03183/BSI-TR-03183-2.html).