Clarity of the "midstream component" definition

[praiskup]

Reading a paragraph in https://redhatproductsecurity.github.io/security-data-guidelines/sbom/#understanding-sboms

- For each software component, an SBOM must list its provenance. That is, if the (downstream) component is a
  redistributed version of an open source project (upstream), the downstream component must be directly linked
  to its upstream counterpart. If an upstream component is augmented in a mirrored repository before being used
  in a build of a downstream component, this version of the component (also called a midstream component) must
  be recorded as a separate package.

Could we make the midstream component and the this version of the component part more obvious?

Consider example: An upstream project example.com/foo is augmented in midstream ?? repo example.com/bar, and that is used for building downstream component foobar (e.g., foobar.rpm). We want to provide SBOM for the downstream foobar.rpm component.

I'd like to better emphasize what "midstream" means; is it the foobar component itself? or the augmented example.com/bar repo? Does SBOM of foobar refer only to example.com/bar (expecting it exists somewhere with its own SBOM), or does it refer to both example.com/bar and example.com/foo?

[mprpic]

@praiskup In your example, midstream is the version at example.com/bar. It is the augmented version of upstream (example.com/foo) that is then used to build downstream (`foobar).

You can see it in one of the example SBOMs for OpenSSL here: https://github.com/RedHatProductSecurity/security-data-guidelines/blob/main/sbom/examples/rpm/release/openssl-3.0.7-18.el9_2.spdx.json#L142-L159. OpenSSL upstream comes from openssl.org, but we also have an augmented version of it that removes some specific features due to compliance reasons that we then use to build off of. This version is different from upstream. You could skip specifying a midstream package if our downstream copy of the upstream sources is simply a 1:1 mirror of upstream.

Does that make sense? Would you prefer to have the OpenSSL example described in the text you quoted to make it clearer?

[praiskup]

Does that make sense?

Seems yes, but I'm missing the "transitivity" perspective; the package foobar declares it is using the midstream repo. How does the SBOM of foobar package refer to upstream?

Would you prefer to have the OpenSSL example described in the text you quoted to make it clearer?

Probably? Another appreciated thing would be to make a clear statement that dist-git repo is not a midstream repo, even if it technically modifies sources, too (e.g., it applies patches in %prep). That downstream never equals to midstream? Then, the question is if we have the term downstream defined 🤷

[azhuzhu]

Considering RPM building, my questions are:

• Because of the use of dist-git in RPM building, could you please clarify if the midstream component is an source archive or a reference of the dist-git repo commit, or something else?
• Should the changes applied, e.g, PatchN or a plain file as SourceN in RPM specfile, be recorded as a software component, as well as the relationship between them and SRPM, midstream/upstream component?

[mprpic]

Seems yes, but I'm missing the "transitivity" perspective; the package foobar declares it is using the midstream repo. How does the SBOM of foobar package refer to upstream?

Here is a crude diagram of all the relationships between upstream, midstream, and downstream.

+-------------------------------------------------------------------------------+
| https://github.com/(RH openssl midstream repo)/archive/refs/tags/3.0.7.tar.gz | <+
+-------------------------------------------------------------------------------+  |
  |                                                                                |
  | GENERATED_FROM                                                                 |
  v                                                                                |
+-------------------------------------------------------------------------------+  | CONTAINS
|                https://openssl.org/source/openssl-3.0.7.tar.gz                |  |
+-------------------------------------------------------------------------------+  |
                                                                                   |
  +--------------------------------------------------------------------------------+
  |
+-------------------------------------------------------------------------------+
|                        rpm.src: openssl 3.0.7-18.el9_2                        |
+-------------------------------------------------------------------------------+
  ^
  | GENERATED_FROM
  |
+-------------------------------------------------------------------------------+
|                      rpm.aarch64: openssl 3.0.7-18.el9_2                      |
|                 rpm.aarch64: openssl-debuginfo 3.0.7-18.el9_2                 |
|                rpm.aarch64: openssl-debugsource 3.0.7-18.el9_2                |
|                   rpm.aarch64: openssl-devel 3.0.7-18.el9_2                   |
|                   rpm.aarch64: openssl-libs 3.0.7-18.el9_2                    |
|              rpm.aarch64: openssl-libs-debuginfo 3.0.7-18.el9_2               |
|                   rpm.aarch64: openssl-perl 3.0.7-18.el9_2                    |
|                       rpm.i686: openssl 3.0.7-18.el9_2                        |
|                  rpm.i686: openssl-debuginfo 3.0.7-18.el9_2                   |
|                 rpm.i686: openssl-debugsource 3.0.7-18.el9_2                  |
|                                 ... (25 more)                                 |
+-------------------------------------------------------------------------------+

Probably? Another appreciated thing would be to make a clear statement that dist-git repo is not a midstream repo, even if it technically modifies sources, too (e.g., it applies patches in %prep). That downstream never equals to midstream? Then, the question is if we have the term downstream defined 🤷

Downstream is the set of sources that is actually used to create a source RPM. Midstream is a modified and mirrored version of upstream. I'll add better definitions of these terms into the docs.

Because of the use of dist-git in RPM building, could you please clarify if the midstream component is an source archive or a reference of the dist-git repo commit, or something else?

Midstream is a reference to a source archive that contains a copy of the upstream code that is somehow modified. It doesn't always have to be present, in a lot of cases we ship the same sources as are present in upstream.

Should the changes applied, e.g, PatchN or a plain file as SourceN in RPM specfile, be recorded as a software component, as well as the relationship between them and SRPM, midstream/upstream component?

Ideally yes, but we haven't found a use case for listing patches as individual components yet. If you have any, please do tell!