WIP

RedHatProductSecurity · Aug 21, 2024 · fef9f07 · fef9f07
1 parent 71fb100
commit fef9f07
Show file tree

Hide file tree

Showing 32 changed files with 424 additions and 87 deletions.
diff --git a/docs/sbom.md b/docs/sbom.md
@@ -0,0 +1,318 @@
+# Understanding SBOMs
+
+A Software Bill of Materials (SBOM) is at its core a listing of software components for a given deliverable. That
+deliverable may be a single RPM package, a container image, or an entire product version. There are several use
+cases where SBOMs are beneficial:
+
+- in-depth review of the composition of a particular product for procurement or audit purposes,
+
+- accurate vulnerability risk assessment when combined with VEX data,
+
+- or faster incident response when aggregating SBOMs for an entire product portfolio.
+
+When talking about inventories of components, it's also important to describe what the current design goals of a
+comprehensive SBOM are:
+
+- Provide a complete and accurate listing of software components and their relationships to each other from a
+  supply chain perspective.
+
+- Define an accurate identification of components and products usable across all published security data.
+
+It's also important to cover the qualities of an SBOM that are currently out of scope:
+
+- Provide a component dependency graph: providing dependency relationships between components as part of an
+  application or an operating system is currently out of scope. This type of information is varied between different
+  ecosystems, and it would be difficult to express it correctly in product-level SBOMs.
+  The relationships currently represented are limited to more direct dependencies, such as those between a container
+  image and the packages it includes, an operating system and its constituent packages, or a package and its
+  upstream counterpart. We do not include application-level dependencies, like those where a Python package such as
+  `requests` depends on another package like `certifi`.
+
+- Inclusion of complete listings of individual files for each component: for each listed component in an SBOM, it is
+  assumed that the user can fetch it from its indicated location, and inspect the component itself to list out its
+  files. For example, when downloading a source RPM, the downloaded archive can be unpacked and inspected to acquire
+  a list of files contained in it.
+
+## Formats
+
+The two most widely used SBOM formats are [SPDX](https://spdx.dev/) and
+[CycloneDX](https://cyclonedx.org/). Both offer similar features and data fields, and can be used to represent
+complex inventories of components, their metadata (such as provenance or licensing), and additional document properties.
+
+Most of this document focuses on Red Hat's use of SPDX 2.3 in its published SBOMs. In the future, we may add similar
+guidelines for CycloneDX and SPDX 3.0.
+
+## SBOM Types
+
+Build vs Release
+
+Component-level vs Product-level
+
+Shallow vs Complete
+
+
+## Document Structure
+
+The following snippet shows a minimal SBOM document:
+
+=== "SPDX 2.3"
+
+    ```json
+    {
+      "spdxVersion": "SPDX-2.3",// (1)!
+      "dataLicense": "CC-BY-4.0",// (2)!
+      "SPDXID": "SPDXRef-[ID]",
+      "creationInfo": {
+        "created": "2006-08-14T02:34:56Z",
+        "creators": [
+          "Tool: example SPDX document only"
+        ]
+      },
+      "name": "ubi9-micro-container-9.4-6.1716471860_amd64",
+      "documentNamespace": "https://www.redhat.com/ubi9-micro-container-9.4-6.1716471860_amd64.spdx.json",
+      "packages": [...],
+      "files": [],
+      "relationships": [...]
+    }
+    ```
+
+    1. SPDX version 2.3 as described at [https://spdx.github.io/spdx-spec/v2.3/](https://spdx.github.io/spdx-spec/v2.3/).
+
+    2. All Red Hat security data is published under the
+       [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/).
+
+A more detailed breakdown of some of the fields:
+
+[`SPDXID`](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#63-spdx-identifier-field)
+:   The `SPDXID` value must be unique across all published SBOM documents. It consists of the `SPDXRef` prefix, an
+    optional set of strings used for easier human identification in defined relationships delimited by dashes,
+    and a UUID suffix, e.g. `SPDXRef-openssl-srpm-032bdb22-3316-41ac-a2ef-5e248fdd2176`.
+
+`creationInfo`
+:   This field must contain at least the
+    [`created`](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#68-creator-field) and
+    [`creators`](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#69-created-field)
+    fields. The timestamp in the `created` field must be set to an ISO 8601-formatted date and time string using
+    the UTC timezone. The `creators` field must identify the tool and its version that was used to generate the SBOM
+    file (for example, `Tool: SBOMer 1.2.3` or even `Tool: pkg:github/project-ncl/[email protected]`).
+    Optionally, the organization responsible for generating the SBOM can be included in a separate string
+    (for example,`Organization: Red Hat Product Security ([email protected])`).
+
+[`name`](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#64-document-name-field)
+:   This is an arbitrary value that should describe the main artifact described by the SBOM document. This can be a
+    product, a container image, or a specific package. The name should contain a descriptive value for that given
+    artifact along with a version identifier. This field should only serve as a human-readable value and be shown in
+    user interfaces for informational purposes. The metadata of the main package (the one _DESCRIBED_ by
+    the SBOM document) should be used for any automation purposes. Note also that the `name` value may not be unique
+    to a single SBOM document.
+
+[`documentNamespace`](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#65-spdx-document-namespace-field)
+:   The value of this field can be set to two possible values:
+
+    - A URI that is namespaced to a generic Red Hat location: `https://www.redhat.com/[DocumentName]-[UUID].spdx.json`.
+      This URI is not accessible and only serves the purpose of identifying the document to its namespace (here,
+      Red Hat).
+
+    - A URI that is namespaced to `access.redhat.com/security/data`:
+     `https://access.redhat.com/security/data/sbom/spdx/rhel-8.2-eus-c8f54354-8791-44b6-b2d6-4eee6d33ec91.spdx.json`.
+      This URI is assumed to be accessible and the identified SBOM can be downloaded from the specified location.
+
+The `packages` and `relationships` fields are described in depth in the sections below for each respective software
+content type. The `files` field is currently unused and will thus either not be present at all, or set to an empty
+list. All software components in an SBOM are described as packages; all files are assumed to be a part of _some_
+package and should thus not be listed on their own in the `files` field.
+
+### Packages and Relationships
+
+=== "SPDX 2.3"
+
+    ```json
+    {
+      "SPDXID": "SPDXRef-[UUID]",// (1)!
+      "name": "ubi9-micro-container",
+      "versionInfo": "9.4-6.1716471860",
+      "supplier": "Organization: Red Hat",// (2)!
+      "downloadLocation": "NOASSERTION",
+      "licenseConcluded": "NOASSERTION",
+      "externalRefs": [...],
+      "checksums": [...]
+    }
+    ```
+
+    1. A unique identifier of a given component within this document. This value should only be used to associate
+       relationships to other components described in an SBOM via their relationships.
+
+    2. The value `Organization: Red Hat` must be used for all components that are distributed by Red Hat.
+
+[`name`](https://spdx.github.io/spdx-spec/v2.3/package-information/#71-package-name-field)
+:   TODO
+
+[`versionInfo`](https://spdx.github.io/spdx-spec/v2.3/package-information/#73-package-version-field)
+:   TODO
+
+[`downloadLocation`](https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field)
+:   TODO
+
+[`licenseConcluded`](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field)
+:   TODO
+
+[`externalRefs`](https://spdx.github.io/spdx-spec/v2.3/package-information/#722-external-reference-comment-field)
+:   must contain purl unless it's a product; may contain multiple purls; see also
+    [Identifying Red Hat components using Package URL](./purl.md).
+
+[`checksums`](https://spdx.github.io/spdx-spec/v2.3/package-information/#710-package-checksum-field)
+:   different values for different content types, see below
+
+
+#### Container Image
+
+=== "SPDX 2.3"
+
+    ```json
+    {
+      "SPDXID": "SPDXRef-image-index",// (1)!
+      "name": "ubi9-micro-container",// (2)!
+      "versionInfo": "9.4-6.1716471860",
+      "supplier": "Organization: Red Hat",
+      "downloadLocation": "NOASSERTION",
+      "licenseConcluded": "NOASSERTION",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:oci/ubi-micro@sha256%3A1c8483e0fda0e990175eb9855a5f15e0910d2038dd397d9e2b357630f0321e6d?repository_url=registry.access.redhat.com/ubi9&tag=9.4-6.1716471860"
+        },
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:oci/ubi9-micro@sha256%3A1c8483e0fda0e990175eb9855a5f15e0910d2038dd397d9e2b357630f0321e6d?repository_url=registry.access.redhat.com&tag=9.4-6.1716471860"
+        }
+      ],
+      "checksums": [
+        {
+          "algorithm": "SHA256",
+          "checksumValue": "1c8483e0fda0e990175eb9855a5f15e0910d2038dd397d9e2b357630f0321e6d"
+        }
+      ]
+    }
+    ```
+
+    1. TODO
+
+    2. TODO
+
+#### RPM
+
+Downstream:
+
+=== "SPDX 2.3"
+
+    ```json
+    {
+      "SPDXID": "SPDXRef-aarch64-openssl-libs",
+      "name": "openssl-libs",
+      "versionInfo": "3.0.7-18.el9_2",
+      "supplier": "Organization: Red Hat",
+      "downloadLocation": "NOASSERTION",
+      "packageFileName": "openssl-libs-3.0.7-18.el9_2.aarch64.rpm",
+      "licenseConcluded": "Apache-2.0",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:rpm/redhat/[email protected]_2?arch=aarch64&repository_id=rhel-9-for-aarch64-baseos-eus-rpms"
+        },
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:rpm/redhat/[email protected]_2?arch=aarch64&repository_id=rhel-9-for-aarch64-baseos-aus-rpms"
+        },
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:rpm/redhat/[email protected]_2?arch=aarch64&repository_id=rhel-9-for-aarch64-baseos-e4s-rpms"
+        }
+      ],
+      "checksums": [
+        {
+          "algorithm": "SHA256",
+          "checksumValue": "cae5941219fd64e75c2b29509c6fe712bef77181a586702275a46a5e812d4dd4"
+        }
+      ]
+    }
+    ```
+
+TODO: describe binary vs source RPM
+
+Upstream:
+
+=== "SPDX 2.3"
+    ```json
+    {
+      "SPDXID": "SPDXRef-Source0-origin",
+      "name": "openssl",
+      "versionInfo": "3.0.7",
+      "downloadLocation": "https://openssl.org/source/openssl-3.0.7.tar.gz",
+      "packageFileName": "openssl-3.0.7.tar.gz",
+      "checksums": [
+        {
+          "algorithm": "SHA256",
+          "checksumValue": "83049d042a260e696f62406ac5c08bf706fd84383f945cf21bd61e9ed95c396e"
+        }
+      ],
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:generic/[email protected]?download_url=https://openssl.org/source/openssl-3.0.7.tar.gz&checksum=sha256:83049d042a260e696f62406ac5c08bf706fd84383f945cf21bd61e9ed95c396e"
+        }
+      ]
+    }
+    ```
+
+Note: we may not have this yet
+
+Note: mention midstream; may not be present
+
+#### Product
+
+=== "SPDX 2.3"
+    ```json
+    {
+      "SPDXID": "SPDXRef-RHEL-9.2-EUS",
+      "name": "Red Hat Enterprise Linux",
+      "versionInfo": "9.2 EUS",
+      "supplier": "Organization: Red Hat",
+      "downloadLocation": "NOASSERTION",// (1)!
+      "licenseConcluded": "NOASSERTION",// (2)!
+      "externalRefs": [
+        {
+          "referenceCategory": "SECURITY",
+          "referenceLocator": "cpe:/a:redhat:rhel_eus:9.2::baseos",
+          "referenceType": "cpe22Type"
+        }
+      ]
+    }
+    ```
+
+    1. Not used because this product component is not specific enough to an architecture or ISO variant (workstation vs server)
+
+    2. Not set, only components have licenses
+
+`name`
+:   This field must contain a human-readable name of the product.
+
+`versionInfo`
+:   This field must contain the most granular version of the product, for which the SBOM was generated.
+
+`externalRefs`
+:   TODO: describe CPE usage
+
+## Additional Notes
+
+The guidelines highlighted in this document represent an ideal state across all of Red Hat-published security data
+that we want to achieve in the long term. In some SBOMs, components may be missing their provenance data or their
+license expressions may not be accurate. Please
+[contact Red Hat Product Security](https://access.redhat.com/security/team/contact/) or file a Jira issue in the
+[SECDATA project](https://issues.redhat.com/projects/SECDATA) if you find any discrepancies in Red Hat's security data.
+Feedback on our SBOM design and publishing is always welcome and appreciated.
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -0,0 +1,3 @@
+.md-typeset {
+    line-height: 1.4;
+}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,7 +1,7 @@
 site_name: Red Hat Security Data Guidelines
 site_url: https://redhatproductsecurity.github.io/security-data-guidelines/
 edit_uri: "https://github.com/RedHatProductSecurity/security-data-guidelines/blob/main/docs"
-copyright: Copyright &copy; Red Hat, Inc. &nbsp;&centerdot;&nbsp; <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>
+copyright: Copyright &copy; Red Hat, Inc. &nbsp;&centerdot;&nbsp; <a href="https://creativecommons.org/licenses/by/4.0/">CC-BY-4.0</a>
 
 theme:
   name: material
@@ -19,30 +19,37 @@ theme:
   language: en
   favicon: images/favicon.png
   logo: images/logo.png
+  font:
+    text: Red Hat Text
+    code: Red Hat Mono
   palette:
     - scheme: default
       toggle:
-        icon: material/toggle-switch-off-outline
+        icon: material/brightness-4
         name: Switch to dark mode
       primary: black
     - scheme: slate
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-7
         name: Switch to light mode
       primary: black
 
 nav:
   - Home: "index.md"
+  - SBOM: "sbom.md"
   - purl: "purl.md"
 
 plugins:
   - social
   - search
 
+extra_css:
+  - stylesheets/extra.css
+
 extra:
   social:
     - icon: fontawesome/brands/github-alt
-      link: https://github.com/RedHatProductSecurity
+      link: https://github.com/RedHatProductSecurity/security-data-guidelines
     - icon: fontawesome/regular/envelope
       link: "mailto:[email protected]"
 
@@ -55,6 +62,7 @@ markdown_extensions:
   - attr_list
   - abbr  # https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations
   - md_in_html
+  - def_list  # https://squidfunk.github.io/mkdocs-material/reference/lists/#using-definition-lists
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true

diff --git a/...ples/container_image/build/kernel-module-management-operator-container-1.1.2-25.spdx.json b/...ples/container_image/build/kernel-module-management-operator-container-1.1.2-25.spdx.json
@@ -1,9 +1,9 @@
 {
   "spdxVersion": "SPDX-2.3",
-  "dataLicense": "CC0-1.0",
+  "dataLicense": "CC-BY-4.0",
   "SPDXID": "SPDXRef-DOCUMENT",
   "creationInfo": {
-    "created": "2006-08-14T02:34:56-06:00",
+    "created": "2006-08-14T02:34:56Z",
     "creators": [
       "Tool: example SPDX document only"
     ]
@@ -118,4 +118,4 @@
       "relatedSpdxElement": "SPDXRef-kernel-module-management-operator-container-ppc64le"
     }
   ]
-}
+}