diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..ecb56b3 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,16 @@ +# EditorConfig helps developers define and maintain consistent +# coding styles between different editors and IDEs +# See also http://editorconfig.org/ + +root = true + +[*] +charset = utf-8 +end_of_line = lf +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.md] +trim_trailing_whitespace = false # Markdown using two trailing spaces for
diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..17e37d8 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,16 @@ +# Set the default behavior, in case people don't have core.autocrlf set. +* text=auto + +# Explicitly declare text files you want to always be normalized and converted +# to native line endings on checkout. +*.md text eol=lf +*.py text eol=lf +*.txt text eol=lf +*.yml text eol=lf + +# Denote all files that are truly binary and should not be modified. +*.gif binary +*.jpg binary +*.pdf binary +*.png binary +*.svg binary diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..fd47a8f --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,36 @@ +on: + push: + branches: + - main + workflow_dispatch: {} +permissions: + contents: write +jobs: + build: + runs-on: ubuntu-latest + container: python:3 + env: + REF: "main" # source branch/tag release + GH_PAGES_BRANCH: "gh-pages" # target branch (to publish HTML to) + GIT_USER_NAME: "publish-github-actions" # for gh-pages commit + GIT_USER_EMAIL: "publish-github-actions[bot]@users.noreply.github.com" # for gh-pages commit + steps: + - name: Checkout content + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 + with: + ref: ${{ env.REF }} + path: using + fetch-depth: 0 + - name: Install pre-requisites for MkDocs + run: pip install -r using/requirements.txt + - name: Set Git identity + working-directory: using + run: | + git config user.name ${{ env.GIT_USER_NAME }} + git config user.email ${{ env.GIT_USER_EMAIL }} + - name: Sync GitHub Pages + working-directory: using + run: git checkout ${{ env.GH_PAGES_BRANCH }} && git pull && git checkout ${{ env.REF }} + - name: Build and deploy docs + working-directory: using + run: mkdocs gh-deploy --clean --verbose --remote-branch ${{ env.GH_PAGES_BRANCH }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cd0fbcf --- /dev/null +++ b/.gitignore @@ -0,0 +1,33 @@ +# Ignore all hidden files/dirs except .gitignore +.* +!/.gitignore +!/.github + +# Operating system files +.DS_Store +._* +Thumbs.db +Thumbs.db:encryptable +*.lnk + +# Generated docs +*.epub +*.mobi +*.pdf + +# Build output directory +dist/ +site/ + +# Build temporary directory +logs/ +__pycache__/ + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ diff --git a/README.md b/README.md index 118c040..1c82c0d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,18 @@ -# using +--- +SPDX-License-Identifier: Community-Spec-1.0 +--- -Information on how to use the SPDX specification +# Using SPDX + +Information on how to use the +[SPDX specification](https://spdx.dev/use/specifications/). + +This is not part of the specification. + +Everything in this repository is for informative purpose only. + +Copyright © 2024, The Linux Foundation and its Contributors. + +This work is licensed under the +[Community Specification License 1.0](./LICENSE) +(Community-Spec-1.0). diff --git a/docs/using-SPDX-to-comply-with-industry-guidance.md b/docs/comply-with-norms.md similarity index 96% rename from docs/using-SPDX-to-comply-with-industry-guidance.md rename to docs/comply-with-norms.md index 7ee8e24..ca1170e 100644 --- a/docs/using-SPDX-to-comply-with-industry-guidance.md +++ b/docs/comply-with-norms.md @@ -1,4 +1,11 @@ -# Using SPDX to comply with Norms, Standards and Regulation +--- +SPDX-License-Identifier: Community-Spec-1.0 +tags: + - compliance + - v3.0 +--- + +# Using SPDX to comply with norms, standards and regulation ## Satisfying NTIA Minimum Elements for an SBOM using SPDX / US Executive Order 14028 diff --git a/docs/cross-reference.md b/docs/cross-ref.md similarity index 97% rename from docs/cross-reference.md rename to docs/cross-ref.md index 79cbdc9..53b446e 100644 --- a/docs/cross-reference.md +++ b/docs/cross-ref.md @@ -1,3 +1,10 @@ +--- +SPDX-License-Identifier: Community-Spec-1.0 +tags: + - reference + - v3.0 +--- + # Cross referencing in SPDX 3 This document will walk though how to refer to SPDX Elements across documents @@ -7,7 +14,7 @@ If you do would like to construct the complete example documents from this Markdown file, use the following command: ```shell -cat cross-reference.md | awk 'BEGIN{flag=0} /^```json/, $0=="```" { if (/^---$/){flag++} else if ($0 !~ /^```.*/ ) print $0 > "doc-" flag ".spdx.json"}' +cat cross-ref.md | awk 'BEGIN{flag=0} /^```json/, $0=="```" { if (/^---$/){flag++} else if ($0 !~ /^```.*/ ) print $0 > "doc-" flag ".spdx.json"}' ``` ## Linking via spdxId diff --git a/docs/diffs-from-previous-editions.md b/docs/diffs-from-previous-editions.md index 791739c..8018f98 100644 --- a/docs/diffs-from-previous-editions.md +++ b/docs/diffs-from-previous-editions.md @@ -1,4 +1,17 @@ -# Annex A: Differences from previous editions (Informative) +--- +SPDX-License-Identifier: Community-Spec-1.0 +tags: + - v3.0 + - v2.3 + - v2.2.2 + - v2.2.1 + - v2.2 + - v2.1 + - v2.0 + - v1.2 +--- + +# Differences from previous editions ## A.1 Differences between V3.0 and V2.3 diff --git a/docs/getting-started.md b/docs/getting-started.md index 6522673..b8f2919 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,12 @@ +--- +SPDX-License-Identifier: Community-Spec-1.0 +tags: + - v3.0 +--- + # Getting started writing SPDX 3 -## (a.k.a My First SPDX File) +(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 diff --git a/docs/images/favicon.png b/docs/images/favicon.png new file mode 100644 index 0000000..6d8701c Binary files /dev/null and b/docs/images/favicon.png differ diff --git a/docs/images/logo-color.svg b/docs/images/logo-color.svg new file mode 100644 index 0000000..34e9050 --- /dev/null +++ b/docs/images/logo-color.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/images/logo-white.svg b/docs/images/logo-white.svg new file mode 100644 index 0000000..fce5de0 --- /dev/null +++ b/docs/images/logo-white.svg @@ -0,0 +1,10 @@ + + + + + + + + + + \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a8a0df2 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,20 @@ +--- +SPDX-License-Identifier: Community-Spec-1.0 +--- + +# Using SPDX + +Information on how to use the +[SPDX specification](https://spdx.dev/use/specifications/). + +Copyright © 2024, The Linux Foundation and its Contributors. + +This work is licensed under the +[Community Specification License 1.0](https://spdx.org/licenses/Community-Spec-1.0.html) +(Community-Spec-1.0). + +!!! info + + This is not part of the specification. + + Everything on this website is for informative purpose only. diff --git a/docs/using-SPDX-short-identifiers-in-source-files.md b/docs/license-id-in-source.md similarity index 81% rename from docs/using-SPDX-short-identifiers-in-source-files.md rename to docs/license-id-in-source.md index 82d89e3..ec7bf7c 100644 --- a/docs/using-SPDX-short-identifiers-in-source-files.md +++ b/docs/license-id-in-source.md @@ -1,4 +1,11 @@ -# Using SPDX license list short identifiers in source files +--- +SPDX-License-Identifier: Community-Spec-1.0 +tags: + - license + - compliance +--- + +# Using SPDX License List short identifiers in source files TODO: update for SPDXv3 @@ -8,23 +15,27 @@ Identifying the license for open source software is critical for both reporting [Short identifiers](https://spdx.org/licenses/) from the SPDX License List can be used to indicate license info at the file level. The advantages of doing this are numerous but include: -* It is precise. -* It is concise. -* It is language neutral. -* It is easy and more reliable to machine process. -* Leads to code that is easier to reuse. -* The license information travels with the file (as sometimes not entire projects are used or license files are removed). -* It is a standard and can be universal. There is no need for variation. -* An SPDX short identifier is immutable. -* Easy look-ups and cross-references to the SPDX License List website. +- It is precise. +- It is concise. +- It is language neutral. +- It is easy and more reliable to machine process. +- Leads to code that is easier to reuse. +- The license information travels with the file (as sometimes not entire projects are used or license files are removed). +- It is a standard and can be universal. There is no need for variation. +- 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. For links to projects illustrating these scenarios, see . ## Format for `SPDX-License-Identifier` -The `SPDX-License-Identifier` tag declares the license the file is under and should be placed at or near the top of the file in a comment. +The `SPDX-License-Identifier` tag declares the license the file is under and should be placed at or near the top of the file in a comment. -The SPDX License Identifier syntax may consist of a single license (represented by a short identifier from the [SPDX license list](https://spdx.org/licenses/)) or a compound set of licenses (represented by joining together multiple licenses using the license expression syntax). +The SPDX License Identifier syntax may consist of a single license +(represented by a short identifier from the +[SPDX License List](https://spdx.org/licenses/)) or a compound set of licenses +(represented by joining together multiple licenses using the license expression +syntax). The tag should appear on its own line in the source file, generally as part of a comment. @@ -34,7 +45,9 @@ SPDX-License-Identifier: ## Representing single license -A single license is represented by using the short identifier from [SPDX license list](https://spdx.org/licenses/), optionally with a unary "+" operator following it to indicate "or later" versions may be applicable. +A single license is represented by using the short identifier from +[SPDX License List](https://spdx.org/licenses/), optionally with a unary "+" +operator following it to indicate "or later" versions may be applicable. Examples: @@ -71,4 +84,3 @@ SPDX-License-Identifier: LicenseRef-my-special-license ``` The `LicenseRef-` format is defined in the SPDX specification Annex defining license expressions. When using a custom `LicenseRef-` identifier, you will also need to provide a way for others to determine what license text corresponds to it. The [REUSE Software Specification](https://reuse.software/spec/) provides a standardized format that can optionally be used for providing the corresponding license text for these identifiers. - diff --git a/docs/including-security-information-in-SPDX.md b/docs/security-info-in-spdx.md similarity index 94% rename from docs/including-security-information-in-SPDX.md rename to docs/security-info-in-spdx.md index 549c65f..88318f6 100644 --- a/docs/including-security-information-in-SPDX.md +++ b/docs/security-info-in-spdx.md @@ -1,38 +1,45 @@ -# Including Security Information in a SPDX document +--- +SPDX-License-Identifier: Community-Spec-1.0 +tags: + - security + - v3.0 +--- + +# 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"](https://spdx.dev/capturing-software-vulnerability-data-in-spdx-3-0/). -## G.1 External References and External Identifiers +## 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: -* cwe -* secureSoftwareAttestation -* securityAdvisory -* securityAdversaryModel -* securityFix -* securityOther -* securityPenTestReport -* securityPolicy -* securityThreatModel -* vulnerabilityDisclosureReport -* vulnerabilityExploitabilityAssessment +- cwe +- secureSoftwareAttestation +- securityAdvisory +- securityAdversaryModel +- securityFix +- securityOther +- securityPenTestReport +- securityPolicy +- securityThreatModel +- 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: -* cpe22 -* cpe23 -* cve -* packageUrl -* securityOther +- 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](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 +## 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](https://github.com/spdx/spdx-3-model/blob/main/model/Security/Classes/Vulnerability.md). You can then use ExternalIdentifiers or ExternalRefs to supplement the CVE with associated external metadata. @@ -83,11 +90,11 @@ To reference a Common Vulnerabilities and Exposures (CVE) advisory applicable to }, ``` -## G.1.2 Linking to a CSAF Document +## 1.2 Linking to a CSAF Document 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 +### 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. @@ -122,7 +129,7 @@ To reference a CSAF VEX document, include an external reference of type `vulnera }, ``` -### G.1.2.2 Linking to a CSAF Advisory +### 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. @@ -143,7 +150,7 @@ To reference a CSAF Advisory document, include the document locator as an extern }, ``` -## G.1.3 Linking to CycloneDX Security Data +## 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. @@ -166,7 +173,7 @@ Using an External Reference, link the package to the matching component in the C }, ``` -## G.1.4 Linking to an OSV +## 1.4 Linking to an OSV To include a reference to [Open Source Vulnerability](https://github.com/google/osv) (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. @@ -187,7 +194,7 @@ To include a reference to [Open Source Vulnerability](https://github.com/google/ }, ``` -## G.1.5 Linking to an OmniBOR (formerly known as GitBOM) +## 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. @@ -208,7 +215,7 @@ To identify a Package with an [OmniBOR](https://omnibor.io/) (Universal Bill Of }, ``` -## G.1.6 Linking to a vulnerability disclosure document +## 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. @@ -267,7 +274,7 @@ To refer to a security disclosure feed, such as the security bulletins from [CER }, ``` -## G.1.7 Linking to a Code Fix for a Security Issue +## 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. @@ -329,7 +336,7 @@ Alternatively, it may also link to a landing page with patches for a variety of }, ``` -## G.1.8 Linking to any Security Related Document +## 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. @@ -370,7 +377,7 @@ One can also use it to refer to guidance related to a vulnerability such as CISA }, ``` -## G.1.9 Linking to a Vulnerability Disclosure Report (VDR) +## 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)](https://www.nist.gov/itl/executive-order-14028-improving-nations-cybersecurity/software-security-supply-chains-software-1)”. Use the External Reference `vulnerabilityDisclosureReport` type to report on vulnerabilities related to the components contained in a software product’s SBOM. diff --git a/docs/tags.md b/docs/tags.md new file mode 100644 index 0000000..93cbe97 --- /dev/null +++ b/docs/tags.md @@ -0,0 +1,9 @@ +--- +SPDX-License-Identifier: Community-Spec-1.0 +--- + +# Tags + +Here are the contents of this website categorized by tags: + + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..6357b3c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,48 @@ +site_name: Using SPDX +site_description: Information on how to use the System Package Data Exchange specification +site_author: The Linux Foundation and its Contributors. +site_url: https://spdx.github.io/using/ # set to the "root" of the site, to be combined with canonical_version +repo_url: https://github.com/spdx/using/ +edit_uri: "edit/main/docs" # set to an empty string to disable edit links; +copyright: Using SPDX Copyright © 2024, The Linux Foundation and its Contributors. +use_directory_urls: true +theme: + name: material + favicon: images/favicon.png + logo: images/logo-white.svg + features: + - content.action.edit +plugins: +- search +- social +- tags: + tags_file: tags.md +markdown_extensions: +- admonition +- abbr +- def_list +- pymdownx.details +- pymdownx.superfences +- pymdownx.caret +- pymdownx.mark +- pymdownx.tilde +strict: true +validation: + nav: + omitted_files: warn + not_found: warn + absolute_links: warn + links: + not_found: warn + anchors: warn + absolute_links: warn + unrecognized_links: warn +nav: +- Home: index.md +- Getting started: getting-started.md +- Cross referencing: cross-ref.md +- Including security information in a SPDX document: security-info-in-spdx.md +- Using SPDX License List short identifiers in source files: license-id-in-source.md +- Using SPDX to comply with norms, standards and regulation: comply-with-norms.md +- Differences from previous editions: diffs-from-previous-editions.md +- Browse by tags: tags.md diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..e97c812 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +mkdocs==1.6.1 +mkdocs-material[imaging]==9.5.34