search

oss-review-toolkit / ort

A suite of tools to automate software compliance checks.
https://oss-review-toolkit.org
Apache License 2.0
1.57k stars 306 forks source link

Setting author information for all SBOM reporters #9017

Open MacOS opened 3 weeks ago

MacOS commented 3 weeks ago

What is the feature you want to request?

User story 1: global configuration with config.yml

As an ORT user, I want to set the SBOM author information globally for all reporters, so that I can maintain the author information globally for all repositories in one and only one place.

User story 2: repository configuration with .ort.yml

As an ORT user, I want to set the SBOM author information on a repository level for all reporters, so that I can overwrite the author information from the global config.yml, and maintain the author information for the repository in one and only one place.

User story 3: command line arguments

As an ORT user, I want to set the SBOM author information with command line arguments for all reporters, so that I can overwrite the author information from the repositorie's .ort.yml.

In the following, I use the two Software Bill of Materials (SBOMs) standards CycloneDX and SPDX examples on how the expected output should look. However, the author information should be included in all other reports as well. The following information is given

"Person: FirstName LastName (first_name.last_name@my_organisation.com)"
"Organization: MyOrganisation (opensource@my_organisation.com)"
SPDX

The following shows how the author information should be displayed for SPDX version 2.2.

<?xml version='1.0' encoding='UTF-8'?>
<Document>
  <SPDXID>SPDXRef-DOCUMENT</SPDXID>
  <spdxVersion>SPDX-2.2</spdxVersion>
  <creationInfo>
    <created>2024-08-20T10:41:42Z</created>
    <creators>Tool: ort-22.3.0-054.sha.6298797</creators>
    <creators>Organization: MyOrganisation (opensource@my_organisation.com)</creators>
    <creators>Person: FirstName LastName (first_name.last_name@my_organisation.com)</creators>
    <licenseListVersion>3.23</licenseListVersion>
  </creationInfo>
  ....
CycloneDX

The following shows how the author information should be displayed for CycloneDX version 1.5.

  <bom xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://cyclonedx.org/schema/bom/1.5" serialNumber="urn:uuid:2911d30c-8cbb-42e5-9ad3-1c46749f6a0e" version="2">
    <metadata>
      <timestamp>2024-08-14T09:17:29Z</timestamp>
      <tools>
        <components>
          ....
        </components>
      </tools>
      <authors>
        <author>
          <name>MyOrganisation</name>
          <email>opensource@my_organisation.com</email>
        </author>
        <author>
          <name>FirstName LastName</name>
          <email>first_name.last_name@my_organisation.com</email>
        </author>
      </authors>
      <component type="application" bom-ref="pkg:npm/app@2.1.18">
  ....

Describe the solution you would like

To address the three user stories from above, I would like to set the author information in config.yml file globally, on the repository level in .ort.yml, and on the command line with options. The following shows a yml file which sets the author information. Please note that I would expect the configuration for the global and repository level to be identical.

ort:
....
    reporter:
        config:
            options:
                author.person: FirstName LastName
                author.person.email: first_name.last_name@my_organisation.com

                author.organization: MyOrganisation
                author.organization.email: opensource@my_organisation.com
        ....

And in the case of multiple authors, I would expect the following.

ort:
....
    reporter:
        config:
            options:
                author.person: FirstNameA LastNameA
                author.person.email: first_nameA.last_nameA@my_organisationA.com

                author.person: FirstNameB LastNameB
                author.person.email: first_nameB.last_nameB@my_organisationB.com

                author.organization: MyOrganisationA
                author.organization.email: opensource@my_organisationA.com

                author.organization: MyOrganisationB
                author.organization.email: opensource@my_organisationB.com
        ....

For the command line arguments, I would expect it to work as follows.

./ort/cli/build/install/ort/bin/ort \
    report \
        ....
        --report-formats=PlainTextTemplate,PdfTemplate,WebApp,SpdxDocument,CycloneDx \
        --report-option=reporters=author.person=FirstName LastName \
        --report-option=reporters=author.person.email=first_name.last_nameA@my_organisation.com \
        --report-option=reporters=author.organization=MyOrganisation \
        --report-option=reporters=author.organization.email=opensource@my_organisation.com \

And for multiple authors the following.

./ort/cli/build/install/ort/bin/ort \
    report \
        ....
        --report-formats=PlainTextTemplate,PdfTemplate,WebApp,SpdxDocument,CycloneDx \
        --report-option=reporters=author.person=FirstNameA LastNameA,FirstNameB LastNameB \
        --report-option=reporters=author.person.email=first_nameA.last_nameA@my_organisationA.com,first_nameB.last_nameB@my_organisationB.com \
        --report-option=reporters=author.organization=MyOrganisationA,MyOrganisationB \
        --report-option=reporters=author.organization.email=opensource@my_organisationA.com,opensource@my_organisationB.com \

Alternatives you have considered

Within the tool, there are no alternatives to set the author information. Neither can you set it globally, nor can you set it on a repository level. In addition, this information can also not be set as a command line argument. See discussion at #9003.

Outside of the tool, there are ways on how to include the information. Apart from the obvious way to copy and paste the information manually into the file, it is possible to use software from other parties to automatically insert author information. See for example the following code that uses xmlstarlet to insert the author information into a CycloneDX SBOM created by ORT.

xmlstarlet edit --inplace --omit-decl \
    -N ns="http://cyclonedx.org/schema/bom/1.5" \
    --subnode /ns:bom/ns:metadata/ \
        -type elem -n "authors" --value "" \
    --subnode /ns:bom/ns:metadata/authors \
        -type elem -n "author" --value "" \
    --subnode /ns:bom/ns:metadata/authors/author[1] \
        -type elem -n "name" --value "FirstName LastName" \
    --subnode /ns:bom/ns:metadata/authors/author[1] \
        -type elem -n "email" --value "first_name.last_name@MyCompany.com" \
    --subnode /ns:bom/ns:metadata/authors \
        -type elem -n "author" --value "" \
    --subnode /ns:bom/ns:metadata/authors/author[2] \
        -type elem -n "name" --value "MyCompany" \
    --subnode /ns:bom/ns:metadata/authors/author[2] \
        -type elem -n "email" --value "opensource@MyCompany.com" \
    my-project-sbom.xml

Additional context

Relevance

The relevance of this feature is high. First, the Cyber Resilience Act (CRA) mandates a Software Bill of Materials (SBOM) for all digital products that are put on the market place within the European Union. Technical requirement documents of the CRA, such as the BSI-TR-03183-2, define minimum data fields for a Software Bill of Materials (SBOMs). And one of the minimum required data fields is the Creator of the SBOM. See the following verbatim Table 2 from the document.

Data field Description
Creator of the SBOM Email address of the entity that created the SBOM. If no email address is available this MUST be a “Uniform Resource Locator (URL)”.
Timestamp Date and time of the SBOM data compilation according to the specification of the formats (see chapter 4)

Similarely, for the USA, the National Telecommunications and Information Administration (NTIA) and the Department of Commerce published the minimal requirements for a SBOM as well in The Minimum Elements For a Software Bill of Materials (SBOM). This publication is in the legal context of Executive Order 14028. These minimum elements also declare the author of an SBOM as being part of the minimum elements - see Author of SBOM Data within the linked document.

In short, two jurisdictions of hugh market places mandate the inclusion of SBOM author information in the SBOM. And as a result, all ORT users are potential beneficiaries of such a feature.

Bigger picture

I would argue that this feature request should be part of a larger effort with the goal to be 100% compliant with the two jurisdictions, and also with different CycloneDX and SPDX versions. The bigger effort, and hence long term goal, would hence include adding more supported versions for CycloneDX and SPDX and making sure that ORT can produce compliant SBOMs right out the box with test cases for all CycloneDX and SPDX.

ToDo List

A rough to do list might be the following

MacOS commented 3 weeks ago

By the way, I'm happy to take the task, or at least contribute partially.

sschuberth commented 3 weeks ago

By the way, I'm happy to take the task, or at least contribute partially.

That's appreciated! As this is a bigger change, involving sensitive locations like configuration (which we do not want to break for existing users), I recommend to participate in one of our weekly community calls in order to present our issue to the audience.

A few initial random and incomplete remarks from my side:

I want to set the SBOM author information globally for all reporters

Personally, I'm a bit reluctant to implementing this in a way so that it affects really all reporters, or at least all reporters that create SBOMs. That's because in ORT each reporter is a plugin to the reporter module / command, an as such does not know anything about other reporters. With that in mind it seems weird to create some coupling between otherwise independent reporter plugins by configuring them all via common settings.

Given that we only have two major SBOM formats right now, I believe it's not asking too much to have the user configure the author information for both of these separately.

In addition, this information can also not be set as a command line argument. See discussion at https://github.com/oss-review-toolkit/ort/discussions/9003.

That's actually not completely true anymore. As of https://github.com/oss-review-toolkit/ort/pull/9004 author / creator information can actually be set on the command line at least for the SPDX reporter.

MacOS commented 2 weeks ago

That's appreciated! As this is a bigger change, involving sensitive locations like configuration (which we do not want to break for existing users), I recommend to participate in one of our weekly community calls in order to present our issue to the audience.

Of course! I'm happy to participate. Since the project Wiki states that we should put issues on the agenda - How can I put our issue on the agenda?

Personally, I'm a bit reluctant to implementing this in a way so that it affects really all reporters, or at least all reporters that create SBOMs. That's because in ORT each reporter is a plugin to the reporter module / command, an as such does not know anything about other reporters. With that in mind it seems weird to create some coupling between otherwise independent reporter plugins by configuring them all via common settings. I'm sorry, but I do not understand your argument. After the changes, the reportes would still not know anything about other reporters. The coupling would only effect the data that is passed on, and the passing on of data has to happen somehow. My idea would be to simply hand over the data and pass it on to the reporters. A given plugin can then decide to ignore it.

I strongly believe that from a user perspective, the change brings a lot of value.

Given that we only have two major SBOM formats right now, I believe it's not asking too much to have the user configure the author information for both of these separately.

I agree, it is not too much to ask for. However, I then would suggest to display a warning message when an additional SBOM reporter is added but the author information is only set for one. In addition, I would also make this clear in the documentation to avoid unpleasent surprises.

That's actually not completely true anymore. As of https://github.com/oss-review-toolkit/ort/pull/9004 author / creator information can actually be set on the command line at least for the SPDX reporter.

That is indeed the case. Actually, you can do that since ORT release 29.0.0

sschuberth commented 2 weeks ago

How can I put our issue on the agenda?

Just let us know, preferably via Slack (but in this case here is fine), what to add and on which date.

I believe something went wrong in your quoting, but this should be your sentence:

My idea would be to simply hand over the data and pass it on to the reporters. A given plugin can then decide to ignore it.

The last sentence is exactly my point: IMO it does not make sense to move configuration options that only a minority of reporters use to global configuration. Instead such options should go to reporter-specific configuration (either in config.yml or .ort.yml) and eventually be duplicated for the individual reporters.

MacOS commented 2 weeks ago

Just let us know, preferably via Slack (but in this case here is fine), what to add and on which date.

I will then let you know via Slack.

The last sentence is exactly my point: IMO it does not make sense to move configuration options that only a minority of reporters use to global configuration. Instead such options should go to reporter-specific configuration (either in config.yml or .ort.yml) and eventually be duplicated for the individual reporters.

As said, I'm totally fine with that but I would recommend making that as clear as possible so no one is suprised.