Skip to content

Fix Markdown lint warnings to avoid rendering issue #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kestewart merged 4 commits into from
Sep 3, 2024
Merged

Fix Markdown lint warnings to avoid rendering issue #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f21ab13
Cleanup Markdown lint warnings
bact Jul 11, 2024
c022187
Return the exclamations
bact Jul 11, 2024
e1d9a93
Remove </br>
bact Jul 11, 2024
076de59
Merge branch 'main' into main
bact Sep 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
# using

Information on how to use the SPDX specification
30 changes: 16 additions & 14 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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",
Expand Down Expand Up @@ -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",
```
Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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].

Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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].

Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down
11 changes: 3 additions & 8 deletions docs/including-security-information-in-SPDX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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
{
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions docs/using-SPDX-short-identifiers-in-source-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://spdx.dev/ids-where>.

## Format for `SPDX-License-Identifier`

Expand Down Expand Up @@ -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: <https://github.com/spdx/license-list-XML/blob/master/CONTRIBUTING.md>.

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:

Expand Down
16 changes: 8 additions & 8 deletions docs/using-SPDX-to-comply-with-industry-guidance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,<br>or [Core/Classes/Element.externalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) for resources outside the scope of SPDX-3.0 content </br> |
| 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,<br>or [Core/Classes/Element.externalIdentifier](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) for resources outside the scope of SPDX-3.0 content |
| 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).