-
Notifications
You must be signed in to change notification settings - Fork 2
Sync guide content from Google Docs and externalize image assets for GitHub-friendly maintenance #18
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.
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
base: main
Are you sure you want to change the base?
Sync guide content from Google Docs and externalize image assets for GitHub-friendly maintenance #18
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Large diffs are not rendered by default.
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # 0\. Preface {#0.-preface} | ||
|
|
||
| The ”OpenChain SBOM Document Quality Guide” is a format-independent framework focused on the quality of the information contained within the document, such as its accuracy and integrity. It defines the essential quality requirements for achieving robust security assurance and license compliance, providing actionable steps to ensure the reliability of the content. | ||
| Key considerations and differences when adapting the Telco SBOM Guide to develop this guide: | ||
|
|
||
| * **Compatibility**: This guide is designed for broad compatibility beyond the “OpenChain Telco SBOM Guide”. By conforming to this guide, an SBOM document not only meets the requirements of the “OpenChain Telco SBOM Guide” but also aligns with various other industry guidelines and regulatory standards. | ||
| * **Applicability**: This guide serves as a foundational quality standard applicable across all industries. Its language and requirements have been carefully refined to ensure universal relevance, making it a basic framework for any sector implementing SBOM Document. | ||
| * **Format Independence**: This guide is written to be independent of any specific SBOM Data format. | ||
| * **Quality Definition**: A new chapter discusses what constitutes a high-quality SBOM Document, explains its importance, and describes how such documents can be effectively utilized. | ||
| * **Best practices**: Guidance addressing various challenges in creating and managing SBOM Documents have been incorporated. | ||
| * **Practical Examples**: As part of these best practices, practical SBOM Document samples are provided in JSON format along with their corresponding schema. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # 1\. Scope and SBOM Document Quality {#1.-scope-and-sbom-document-quality} | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Same as previous: e04598e#r3271227462 |
||
|
|
||
| While the term **"SBOM"** generally refers to the information that constitutes a software's composition, this guide specifically focuses on the quality of the “**SBOM Document”**. In this guide, **”SBOM Document”** is a structured artifact – typically formatted in JSON and based on specifications such as SPDX or CycloneDX – that is exchanged between software distributors and recipients. | ||
|
|
||
| ![][image1] | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Memo: Transparent image is hard to see in dark mode. Will fix soon. |
||
| This guide, “OpenChain SBOM Document Quality Guide”, establishes a clear framework for document quality – centered on security assurance and license compliance – and providing actionable requirements to achieve it. | ||
| Specifically, documents are evaluated based on following two essential aspects: | ||
|
|
||
| * Adequacy of Security Assurance | ||
| Assesses whether sufficient baseline information is provided to support an investigation that validates the software's security posture, even if, at the time of delivery, the document does not comprehensively cover all risks, vulnerabilities, or mitigation strategies. | ||
| * Effectiveness of License Compliance | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This bullet should be aligned. |
||
| Assesses whether the necessary licensing details and usage terms for each software component are properly captured to ensure compliance with relevant laws and regulations. | ||
|
|
||
| By adhering to this guide, stakeholders can ensure that the SBOM Documents exchanged within the software supply chain consistently meet high-quality standards. | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Wrong indentation here. |
||
|
|
||
| [image1]: <../assets/images/sbom-document-quality-guide/01-scope-and-sbom-document-quality-overview.png> | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Images should probably go under the MD file's directory, but let's discuss. |
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| # 2\. Terms and Definitions {#2.-terms-and-definitions} | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Same as previous: e04598e#r3271227462 |
||
|
|
||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 \[[RFC2119](https://www.ietf.org/rfc/rfc2119.txt)\] \[[RFC8174](https://www.ietf.org/rfc/rfc8174.txt)\] when, and only when, they appear in all capitals, as shown here. | ||
|
|
||
| | Terms | Definitions | | ||
| | ----- | ----- | | ||
| | Data Format | Data Format means the data format of the information in the SBOM. Possible Data Formats include SPDX, Cyclone DX, SWID, or other proprietary formats. | | ||
| | Entity | Entity shall mean the legal entity (for profit, non profit, or natural person) that distributes software to third parties (e.g., other organizations or individuals). Entity does not include other group companies, or companies under common control of the Entity. | | ||
| | SBOM | A Software Bill of Materials (SBOM) is a formal record containing the details and supply chain relationships of various components used in building software. | | ||
| | SBOM Type | An SBOM can be of one of the following types: Design, Source, Build, Analyzed, Deployed, Runtime. The definition of these types can be found in [the CISA document](https://www.cisa.gov/sites/default/files/2023-04/sbom-types-document-508c.pdf). | | ||
| | SPDX | SPDX (System Package Data Exchange) is the ISO standard ([ISO/IEC 5962:2021](https://www.iso.org/standard/81870.html)) for exchanging SBOM for a given software package, including associated license and copyright information. The standard was created by the Linux Foundation's [SPDX project](https://spdx.dev/). | | ||
| | CycloneDX | CycloneDX is the ECMA standard ([ECMA-424](https://ecma-international.org/publications-and-standards/standards/ecma-424/)) for a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction.The standard was created by the OWASP Foundation, which is a nonprofit foundation for improving software security. | | ||
| | OpenChain Specification ISO/IEC 5230:2020 | [ISO/IEC 5230:2020](https://www.iso.org/standard/81039.html) is an international standard that specifies the key requirements of a quality open source license compliance program in order to provide a benchmark that builds trust between organizations exchanging software solutions that incorporate open source software. The OpenChain standard is produced by [the OpenChain project](https://www.openchainproject.org/) of the Linux Foundation. | | ||
| | OpenChain Specification ISO/IEC 18974:2023 | [ISO/IEC MO 18974:2023](https://www.iso.org/standard/86450.html) is an international standard from the OpenChain Project that provides requirements for open source software security assurance. It aims to improve software supply chain confidence by managing publicly known security vulnerabilities. Organizations can demonstrate compliance through self-certification or audits. | | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
| | Transitive dependencies | Transitive dependencies are all components that are necessary for the software to run. They include any dependency of the package that is not a direct dependency. | | ||
| | Package URL(PURL) | Package URL (PURL) is a de facto standard to uniquely identify software packages. | | ||
| | SBOM Document | A Software Bill of Materials (SBOM) document is the output of SBOM information in formats like JSON or YAML for the purpose of accurate information transfer between organizations. | | ||
| | File Format | File Format means the format of SBOM Document. Possible File Formats include JSON, YAML, Excel Sheet etc. | | ||
| | Software Package | A software package is a distributable unit that can consist of a single software component, such as code or a library, or a bundle of related components, including configuration files. It may also include information about dependencies and versioning, making installation, updates, and integration with other systems more efficient. This packaging approach helps streamline software development and maintenance processes. | | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is the purpose of the embedded '{#0.-preface}'? anchor?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This seems to be a Pandoc's Markdown extension.
We should be need to decide whether or not to use Markdown extensions.