diff --git a/Features.md b/Features.md index 240eb69..42258f1 100644 --- a/Features.md +++ b/Features.md @@ -14,7 +14,6 @@ limitations under the License. --> - # SBOM Quality Checks This page describes each SBOM Quality check in detail, including scoring criteria, @@ -25,16 +24,19 @@ If you have ideas for additions or new detection techniques, please [contribute](https://github.com/interlynk-io/sbomqs#contributions)! ## Taxonomy + - A `Quality Check` is a test that can be performed on SBOM to return a binary result (e.g., A check for specification) - A `Quality Check Category` is a logical grouping of Quality Checks (e.g., "NTIA-Minimum-Elements" Checks) - A `Quality Check Set` is a collection of Quality Checks (e.g., "Default Check Set", "IoT Quality Set") ## Scoring Methodology + - Each Quality Check has an equal weight and a score range of 0.0 - 10.0. (Coming soon: Customization of weight per Quality Check) - A Quality Check applied over a list of items (e.g., licenses) averages its score from the Check applied to each element. - Quality Check Set Score is an average of scores over all Quality Checks in that Set. ## Check Set Versioning + Any Check Set, including the default Check Set, may change over time as new Checks are added, existing ones are removed and meaning of an existing one changes. Such a breaking change is marked by incrementing `scoring_engine_version` in the output of `sbomqs`. @@ -43,7 +45,9 @@ Therefore comparing Quality Scores across `scoring_engine_version` is not recomm ## Quality Check Sets - Interlynk (Default) ### Category: Structural + --- + #### Specification This check determines whether the SBOM is in one of the specifications (CycloneDX, SPDX, SWID) recommended by the [CISA reference document](https://ntia.gov/sites/default/files/publications/ntia_sbom_framing_2nd_edition_20211021_0.pdf) . @@ -51,34 +55,43 @@ This check determines whether the SBOM is in one of the specifications (CycloneD CISA recommends limiting the document to three commonly used formats to facilitate widespread adoption. - ***Remediation*** + - Re-create the document in CycloneDX, SPDX, or SWID. + --- + #### Specification Version This check determines whether the given SBOM is in the specification version that can support fields necessary for typical SBOM operations. The current check tests for: + - CycloneDX Versions: 1.0, 1.1, 1.2, 1.3, 1.4 - SPDX Versions: 2.1, 2.2, 2.3 While the earlier versions of specifications may exist, a document in an earlier version will not be able to carry all of the required fields. ***Remediation*** + - Re-create the document in one of the versions listed above. + --- + #### Specification File Format This check determines whether the given SBOM can be easily consumed by testing for the most common file formats associated with the specification. + - CycloneDX: XML, JSON - SPDX: JSON, YAML, RDF, tag/value Building and sharing SBOM in the most commonly used file format enables the use of SBOM in various conditions. ***Remediation steps*** + - Re-create the document in one of the file formats listed above. --- + #### Specification Syntax This check determines whether the given SBOM meets all the requirements of the underlying specification and file format to be parsed. @@ -86,12 +99,17 @@ This check determines whether the given SBOM meets all the requirements of the u A syntactic error in the SBOM will prevent it from being usable. ***Remediation*** + - Check the SBOM generator tool's known issues and get the most recent version of the tool. - Check options/setup of the environment variables required to use the tool. - Build SBOM with a different tool. + --- -### Category: NTIA-Minimum-Elements + +## Category: NTIA-Minimum-Elements + --- + #### Component Name This check determines whether each component in the SBOM includes a name. @@ -99,12 +117,13 @@ This check determines whether each component in the SBOM includes a name. Components must have a name to be used meaningfully to assess compliance or security risk. **Remediation** - Identify the component with a missing name and check its product page to get its name. + - CycloneDX field: [components:name](https://cyclonedx.org/docs/1.4/json/#components_items_name) - SPDX field: [PackageName](https://spdx.github.io/spdx-spec/v2.3/package-information/#71-package-name-field) --- + #### Supplier Name This check determines whether each component in the SBOM includes a supplier name. Supplier name is not a well defined term @@ -113,9 +132,12 @@ especially in the context of Open Source projects and we will update the recomme ***Remediation*** Identify the component with a missing supplier name and check its product page to get its supplier name. + - CycloneDX field: [components:supplier](https://cyclonedx.org/docs/1.4/json/#components_items_supplier) - SPDX field: [PackageSupplierName](https://spdx.github.io/spdx-spec/v2.3/package-information/#75-package-supplier-field) + --- + #### Unique Identifier This check determines whether each component in the SBOM includes a unique identifier. @@ -125,10 +147,12 @@ Unique component identifiers are essential to ensure the document can uniquely d ***Remediation*** Identify the component with a missing/duplicate identifier. + - CycloneDX field: [components:bom-ref](https://cyclonedx.org/docs/1.4/json/#components_items_bom-ref) - SPDX field: [SPDXID](https://spdx.github.io/spdx-spec/v2.3/package-information/#72-package-spdx-identifier-field) --- + #### Component Version This check determines whether each component in the SBOM includes a version. @@ -137,9 +161,12 @@ Components without a version can not be checked for vulnerabilities. ***Remediation*** Identify the component with the missing version and populate the version field below. + - CycloneDX field: [components:version](https://cyclonedx.org/docs/1.4/json/#components_items_version) - SPDX field: [PackageVersion](https://spdx.github.io/spdx-spec/v2.3/package-information/#73-package-version-field) + --- + #### Author Name This check determines whether the document includes the name of the author. @@ -148,10 +175,12 @@ The person, organization, or the tool that created the SBOM must be specified as ***Remediation*** Check and populate the following fields with the name of the person, organization, or tool creating the SBOM. + - CycloneDX field: [metadata:authors](https://cyclonedx.org/docs/1.4/json/#metadata_authors) - SPDX field: [Creator](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#68-creator-field) --- + #### Timestamp This check determines if the document includes the timestamp of its creation. @@ -159,11 +188,13 @@ This check determines if the document includes the timestamp of its creation. The timestamp can be used to determine when the SBOM was created relative to the software itself. ***Remediation steps*** + - Check and populate the following fields with the timestamp of the SBOM document. - CycloneDX field: [metadata:timestamp](https://cyclonedx.org/docs/1.4/json/#metadata_timestamp) - SPDX field: [Created](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#69-created-field) --- + #### Relationship among Components This check determines if the document describes the relationship among included components. @@ -171,13 +202,17 @@ This check determines if the document describes the relationship among included The dependency relationship can be critical in determining the order of inclusion and updates. ***Remediation*** + - Check and populate the following fields with the relationship of components in the SBOM. - CycloneDX field: [dependencies](https://cyclonedx.org/docs/1.4/json/#dependencies) - SPDX field: [Relationship](https://spdx.github.io/spdx-spec/v2.3/relationships-between-SPDX-elements/#111-relationship-field) --- + ### Category: Semantic + --- + #### Component Checksum This check determines whether each component in the SBOM includes a valid checksum. @@ -192,6 +227,7 @@ A valid checksum can be used to independently identify the contents of the packa --- + #### Component License This check determines whether each component in the SBOM includes a valid license. @@ -201,10 +237,12 @@ A declared valid SPDX license is the key to evaluating any compliance risks. ***Remediation steps*** Check and populate the following fields with the relationship of components in the SBOM. + - CycloneDX field: [component:licenses](https://cyclonedx.org/docs/1.4/json/#components_items_licenses) - SPDX fields: [PackageLicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field), (Coming Soon) [LicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/file-information/#85-concluded-license-field) --- + #### Required Fields This check determines whether several fields required by the underlying specification are present in the document. @@ -214,13 +252,16 @@ With the required fields, the SBOM processing becomes consistent by different to ***Remediation*** Check and populate the following required fields: + - CycloneDX Fields: [bomFormat](https://cyclonedx.org/docs/1.4/json/#bomFormat), [SpecVersion](https://cyclonedx.org/docs/1.4/json/#specVersion), [Version](https://cyclonedx.org/docs/1.4/json/#version), [component:type](https://cyclonedx.org/docs/1.4/json/#components_items_type),[component:name](https://cyclonedx.org/docs/1.4/json/#components_items_name) - SPDX Fields: [CreationInfo](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/), [Creator](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#68-creator-field), [Created](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#69-created-field), [SPDXVersion](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#61-spdx-version-field), [DataLicense](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#62-data-license-field), [SPDXIdentifier](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#63-spdx-identifier-field), [DocumentName](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#64-document-name-field), [DocumentNamespace](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#65-spdx-document-namespace-field), [PackageName](https://spdx.github.io/spdx-spec/v2.3/package-information/#71-package-name-field), [PackageSPDXIdentifier](https://spdx.github.io/spdx-spec/v2.3/package-information/#72-package-spdx-identifier-field), [PackageDowloadLocation](https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field), [PackageVerificationCode](https://spdx.github.io/spdx-spec/v2.3/package-information/#79-package-verification-code-field) (if applicable) - --- + ### Category: Quality + --- + #### Vulnerability Lookup Identifier This check determines whether at least one vulnerability lookup identifier (CPE/PURL) is present for each component. @@ -234,6 +275,7 @@ A vulnerability lookup identifier is critical in mapping SBOM components to know - SPDX fields: [ExternalRef with CPE or PURL](https://spdx.github.io/spdx-spec/v2.3/package-information/#721-external-reference-field) --- + #### Multiple Vulnerability Lookup Identifier This check determines whether multiple vulnerability lookup identifiers are present for each component. @@ -243,10 +285,12 @@ Including more than one vulnerability lookup identifier can enable vulnerability ***Remediation*** Check and populate the following fields: + - CycloneDX field: [components:cpe](https://cyclonedx.org/docs/1.4/json/#components_items_cpe) AND [components:purl](https://cyclonedx.org/docs/1.4/json/#components_items_purl) - SPDX fields: [ExternalRef with CPE AND PURL](https://spdx.github.io/spdx-spec/v2.3/package-information/#721-external-reference-field) --- + #### Valid SPDX License This check determines whether all included licenses are valid SPDX [licenses or license expressions](https://spdx.org/licenses/). @@ -260,6 +304,7 @@ Any license expression not found on the SPDX list is a commercial license and mu - SPDX fields: [PackageLicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field), (Coming Soon) [LicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/file-information/#85-concluded-license-field) --- + #### Deprecated License This check determines whether any of the included licenses have been declared deprecated. @@ -271,7 +316,9 @@ A deprecated license declaration can be considered a compliance risk. - Check the following fields to confirm none of the licenses belong to the [deprecated licenses](https://spdx.org/licenses/): - CycloneDX field: [component:licenses](https://cyclonedx.org/docs/1.4/json/#components_items_licenses) - SPDX fields: [PackageLicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field), (Coming Soon) [LicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/file-information/#85-concluded-license-field) + --- + #### Restricted License This check determines whether any included licenses have been declared restricted for use. @@ -285,6 +332,7 @@ A restricted license declaration can be considered a compliance risk. - SPDX fields: [PackageLicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field), (Coming Soon) [LicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/file-information/#85-concluded-license-field) --- + #### Primary Purpose This check determines whether the SBOM component includes the Primary Purpose field. @@ -294,10 +342,12 @@ The primary purpose (or type) indicates the use of the component inside the appl ***Remediation steps*** Check the following fields to confirm none of the licenses belong to the [restricted license list](https://opensource.google/documentation/reference/thirdparty/licenses): + - CycloneDX field: [component:type](https://cyclonedx.org/docs/1.4/json/#components_items_type) - SPDX fields: [PrimaryPackagePurpose](https://spdx.github.io/spdx-spec/v2.3/package-information/#724-primary-package-purpose-field) --- + #### Primary Component Present An sbom is expected to describe a primary component. This check determines if the sbom has @@ -308,15 +358,19 @@ a primary component or not. - CycloneDX: ensure the metadata section has the primary [component](https://cyclonedx.org/docs/1.5/json/#metadata_component) defined - SPDX: Should have a [DESCRIBES](https://spdx.github.io/spdx-spec/v2.3/relationships-between-SPDX-elements/) relationship which points to a package, or have a documentDescribes field present. - --- + ### Category: Sharing + --- + #### Unencumbered License This check determines whether the SBOM can be shared easily because it includes an unencumbered license: [CC0](https://spdx.org/licenses/CC0-1.0), [Unlicense](https://spdx.org/licenses/Unlicense.html), [0BSD](https://spdx.org/licenses/0BSD.html) Check the following fields to see if the license includes one of the above licenses: + - CycloneDX field: [metadata:licenses](https://cyclonedx.org/docs/1.4/json/#metadata_licenses) - SPDX fields: [DataLicense](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#62-data-license-field) + --- diff --git a/README.md b/README.md index cc8fd2c..30ef49a 100644 --- a/README.md +++ b/README.md @@ -31,60 +31,74 @@ brew install sbomqs Other [installation options](#installation). # SBOM Card + [![SBOMCard](https://api.interlynk.io/api/v1/badges.svg?type=hcard&project_group_id=7f52093e-3d78-49cb-aeb1-6c977de9442e )](https://app.interlynk.io/customer/products?id=7f52093e-3d78-49cb-aeb1-6c977de9442e&signed_url_params=eyJfcmFpbHMiOnsibWVzc2FnZSI6IklqUmhPRGRoTjJNNExXSXpZekl0TkdVeE9TMDVNRGxoTFRKbFpHRmlPR1ZoWldReVl5ST0iLCJleHAiOm51bGwsInB1ciI6InNoYXJlX2x5bmsvc2hhcmVfbHluayJ9fQ==--daf6585ecf8013a0b2713a5cebb28c140d29eed904b15c84c0566b9ddd334e71) # Usage -#### Quality Score for a single SBOM + +## Quality Score for a single SBOM + ```sh sbomqs score ``` -#### Compliance Report: BSI TR-03183-2 +## Compliance Report: BSI TR-03183-2 + ```sh sbomqs compliance -c samples/photon.spdx.json ``` -#### Quality Score with a shareable link at [sbombenchmark.dev](https://sbombenchmark.dev/) +## Quality Score with a shareable link at [sbombenchmark.dev](https://sbombenchmark.dev/) + ```sh sbomqs share ``` Example: + ```sh sbomqs share cdxgen-9.5.1_alpine-latest.cdx.json ``` -``` -5.9 cdxgen-9.5.1_alpine-latest.cdx.json +```sh +5.9 cdxgen-9.5.1_alpine-latest.cdx.json ShareLink: https://sbombenchmark.dev/user/score?id=a97af1bf-4c9d-4a55-8524-3d4bcee0b9a4 ``` -#### Quality Score for your dependency track projects +## Quality Score for your dependency track projects + ```sh sbomqs dtrackScore -u -k ``` Example: + ```sh sbomqs dtrackScore -u "http://localhost:8080/" -k "IIcfPA9qc1F4IkQFa2FqQJoTwcfQI" bbd4434d-8062-4e59-a323-3b416701c948 ``` + ![alt text](./images/dt.png "Depedency Track with sbomqs score") -#### Quality Score in an AirGapped Environment +## Quality Score in an AirGapped Environment + ```sh INTERLYNK_DISABLE_VERSION_CHECK=true ./build/sbomqs score ~/wrk/sbom*/samples/*.json -b ``` -#### Quality Score using containers +## Quality Score using containers + ```sh docker run -v :/app/inputfile ghcr.io/interlynk-io/sbomqs score /app/inputfile ``` + Example + ```sh docker run -v $(pwd)/samples/sbomqs-cdx-cgomod.json:/app/inputfile ghcr.io/interlynk-io/sbomqs score -j /app/inputfile ``` -``` + +```sh Unable to find image 'ghcr.io/interlynk-io/sbomqs:latest' locally latest: Pulling from interlynk-io/sbomqs 708d61464c72: Already exists @@ -101,9 +115,11 @@ Status: Downloaded newer image for ghcr.io/interlynk-io/sbomqs:latest ``` # What is a high quality SBOM + A high quality SBOM should aptly support managing software assets, license information and Intellectual Property as well as provide a base for configuration management, vulnerability handling and incident response. A quality SBOM is one that is accurate, complete, and up-to-date. There are many factors that go into constructing a high quality SBOM. + 1. Identify & list all components of your product along with their transitive dependencies. 2. List all your components along with their versions & content checksums. 3. Include accurate component licenses. @@ -112,10 +128,10 @@ A quality SBOM is one that is accurate, complete, and up-to-date. There are many 6. Signed SBOMs. 7. Should layout information based on industry standard specs like CycloneDX, SPDX and SWID. - # Goals The main goals of the utility are: + 1. Make it easy and fast to assess the quality if an SBOM, generated or acquired. 2. Support all well-known SBOM standards. 3. Scoring output should be customizable. @@ -130,13 +146,15 @@ SBOMs can be generated using both commercial and open-source tooling. As consume ```sh sbomqs score samples/julia.spdx.tv -b ``` -``` + +```sh 6.9 samples/julia.spdx.json ``` ## Goal #2: SBOM Standards The NTIA recommends these standards for SBOMs: + - SPDX - CycloneDX - SWID @@ -152,8 +170,10 @@ In addition to supporting these SBOM formats, we support various formats for dat `sbomqs` scoring output can be customized by category or by feature. We understand everyone's needs for scoring differ, hence we allow to customize which categories or features should rsp. should not be included for scoring. -#### Category scoring +## Category scoring + We have categorized our current features as follows: + - **NTIA-minimum-elements**: Includes features, which help you to quickly understand if an SBOM complies with NTIA's minimum element guidelines. - **Structural**: Checks if an SBOM complies with the underlying specifications, be it [SPDX](https://spdx.dev/specifications/) or [CycloneDX](https://cyclonedx.org/specification/overview/). - **Semantic**: Checks meaning of SBOM fields specific to their standard. @@ -161,8 +181,8 @@ We have categorized our current features as follows: - **Sharing**: Helps to determine if an SBOM can be shared. - [OWASP BOM Maturity Model](https://docs.google.com/spreadsheets/d/1wu6KbgwuokC5357ikrhFN-QkwQ7Pyb6z0zE80sTNNus/edit#gid=0): Work in progress +## Feature Scoring -#### Feature Scoring We allow running any single feature to be tested against an SBOM. 1. `sbomqs generate features` generates a features.yaml file. @@ -187,6 +207,7 @@ The basic output is great for a quick check of the quality of an SBOMs. Once you Detailed output is presented in tabular and json formats, currently: Tabular format: this format has been inspired by oss scorecard project. + ```sh SBOM Quality Score: 6.0 samples/blogifier-dotnet-SBOM.json +-----------------------+--------------------------------+-----------+--------------------------------+ @@ -206,6 +227,7 @@ SBOM Quality Score: 6.0 samples/blogifier-dotnet-SBOM.json ``` json format + ```json { "run_id": "fc86a94d-7490-4f20-a202-b04bb3cdfde9", @@ -238,16 +260,19 @@ json format ``` # Compliance Reports + sbomqs can produce compliance reports for industry standard requirements. Details about compliance implementation are [avaliable here](./Compliance.md). ## Reports + - [BSI TR-03183-2 v1.1](https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Publications/TechGuidelines/TR03183/BSI-TR-03183-2.pdf) - [OpenChain Telco SBOM Guide Version 1.0](https://github.com/OpenChain-Project/Reference-Material/blob/master/SBOM-Quality/Version-1/OpenChain-Telco-SBOM-Guide_EN.md) - [NTIA minimum element](https://www.ntia.doc.gov/files/ntia/publications/sbom_minimum_elements_report.pdf) - Coming soon. - [OWASP SCVS](https://scvs.owasp.org/bom-maturity-model/) - Coming soon. Example of a BSI report -``` + +```json { "report_name": "Cyber Resilience Requirements for Manufacturers and Products Report", "subtitle": "Part 2: Software Bill of Materials (SBOM)", @@ -280,7 +305,9 @@ Example of a BSI report }, ... ``` + Example of a OpenChain Telco SBOM Basic Report + ``` ➜ sbomqs git:(fix/command-line) ./build/sbomqs compliance -t -b constellation-spdx.json OpenChain Telco Report @@ -288,6 +315,7 @@ Score:3.1 RequiredScore:3.1 OptionalScore:0.0 for constellation-spdx.json ``` # SBOM Samples + - A sample set of SBOMs is present in the [samples](https://github.com/interlynk-io/sbomqs/tree/main/samples) directory above - [SBOM Benchmark](https://www.sbombenchmark.dev) is a repository of SBOM and quality score for most popular containers and repositories - [SBOM Explorer](https://github.com/interlynk-io/sbomex) is a command line utility to search and pull SBOMs @@ -302,6 +330,7 @@ https://github.com/interlynk-io/sbomqs/releases ``` ## Using Homebrew + ```console brew tap interlynk-io/interlynk brew install sbomqs @@ -323,7 +352,9 @@ This approach involves cloning the repo and building it. 4. To test if the build was successful run the following command `./build/sbomqs version` # Contributions + We look forward to your contributions, below are a few guidelines on how to submit them + - Fork the repo - Create your feature/bug branch (`git checkout -b feature/bug`) - Commit your changes (`git commit -aSm "awesome new feature"`) - commits must be signed @@ -331,13 +362,16 @@ We look forward to your contributions, below are a few guidelines on how to subm - Create a new pull-request # Other Open Source Software tools for SBOMs + - [SBOM Assembler](https://github.com/interlynk-io/sbomasm) - A tool to compose a single SBOM by combining other SBOMs or parts of them - [SBOM Quality Score](https://github.com/interlynk-io/sbomqs) - A tool for evaluating the quality and completeness of SBOMs - [SBOM Search Tool](https://github.com/interlynk-io/sbomagr) - A tool to grep style semantic search in SBOMs - [SBOM Explorer](https://github.com/interlynk-io/sbomex) - A tool for discovering and downloading SBOMs from a public repository # Contact + We appreciate all feedback. The best ways to get in touch with us: + - ❓& 🅰️ [Slack](https://join.slack.com/t/sbomqa/shared_invite/zt-2jzq1ttgy-4IGzOYBEtHwJdMyYj~BACA) - :phone: [Live Chat](https://www.interlynk.io/#hs-chat-open) - 📫 [Email Us](mailto:hello@interlynk.io) @@ -349,5 +383,3 @@ We appreciate all feedback. The best ways to get in touch with us: If you like this project, please support us by starring it. [![Stargazers](https://starchart.cc/interlynk-io/sbomqs.svg)](https://starchart.cc/interlynk-io/sbomqs) - -