Improve the value of the "documentDescribes" field in a generated SPDX 2.3 SBOM

[DennisClark]

At the recent SPDX Docfest, it was pointed out that the value we provide in the SPDX 2.3 SBOM for the "documentDescribes" field is a self-reference to the SPDX Document, rather than the subject of the SBOM: SPDXRef-DOCUMENT .

It would be better to provide a filename (possibly even a PURL when available) to identify (describe?) the overall subject of the SBOM. See attached.

[DennisClark]

[DennisClark]

I'm not sure we need to fill out the whole subset of the field, which might be imho redundant with the rest of the SBOM, but a concise "description" value would be nice.

[JonoYang]

@DennisClark

I've updated the SPDX SBOM generation code to populate the documentDescribes field with the SPDX ID of the Packages and Dependencies found in the codebase.

{
  "spdxVersion": "SPDX-2.3",
  "dataLicense": "CC0-1.0",
  "SPDXID": "SPDXRef-DOCUMENT",
  "name": "scancodeio_asdf",
  "documentNamespace": "https://scancode.io/spdxdocs/077c7103-d683-4f47-b5c3-349ae813cb7f",
  "creationInfo": {
    "created": "2022-12-09T20:10:40Z",
    "creators": [
      "Tool: ScanCode.io-32.0.0"
    ],
    "licenseListVersion": "3.18"
  },
  "packages": [
    {
      "name": "Django",
      "SPDXID": "SPDXRef-scancodeio-discoveredpackage-5286f46a-f62a-4b2e-bcae-282aee7e620e",
      "downloadLocation": "NOASSERTION",
      "licenseConcluded": "NOASSERTION",
      "copyrightText": "NOASSERTION",
      "filesAnalyzed": false,
      "externalRefs": [
        {
          "referenceCategory": "PACKAGE-MANAGER",
          "referenceType": "purl",
          "referenceLocator": "pkg:npm/Django"
        }
      ]
    },
   ...
  ],
  "documentDescribes": [
    "SPDXRef-scancodeio-discoveredpackage-5286f46a-f62a-4b2e-bcae-282aee7e620e",
    "SPDXRef-scancodeio-discoveredpackage-4a76f0fb-f146-4151-b9f7-6997f85204fc",
    "SPDXRef-scancodeio-discovereddependency-pkg:npm/eslint?uuid=aaefa02a-0326-471c-9003-18e0afb0ac34",
    "SPDXRef-scancodeio-discovereddependency-pkg:npm/grunt?uuid=2600e427-07ec-4490-87ca-8b5ddbd5f17e",
    "SPDXRef-scancodeio-discovereddependency-pkg:npm/grunt-cli?uuid=29ff8a00-435e-4ec5-af25-2db1a832bd7f",
    "SPDXRef-scancodeio-discovereddependency-pkg:npm/grunt-contrib-qunit?uuid=47f256ef-4251-45dc-a976-8854c3ba6811",
    "SPDXRef-scancodeio-discovereddependency-pkg:npm/puppeteer?uuid=8e16b4fa-8cf4-49d2-b9f9-361ca3ceb53f",
    "SPDXRef-scancodeio-discovereddependency-pkg:npm/qunit?uuid=fa60f617-27b0-45de-99a5-08600914d297",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/argon2-cffi?uuid=b3fa402a-b986-4443-a993-82ed61e1f428",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/argon2-cffi?uuid=f4abd865-58dc-4b26-b4bc-001c85c355ed",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/asgiref?uuid=ed109be4-8a6c-4904-9e92-9eae2f55dbde",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/asgiref?uuid=ce7bff4f-40d5-40f7-88c5-78bd8fecba8d",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/backports-zoneinfo?uuid=c60fef1a-030e-42bc-9be2-1ee7915637d3",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/backports-zoneinfo?uuid=692e1fb0-fd27-41a0-a990-a0c145e5cdab",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/bcrypt?uuid=ec51c3dd-d80d-4a3e-85b8-e273b983033e",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/bcrypt?uuid=5cf29eb4-7afb-475d-87d9-9124a4b14a62",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/pyenchant?uuid=f8129dd9-d393-462b-8fc7-5fac305d5783",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/sphinx?uuid=0dd97a6e-6e59-4733-b415-641687010a6b",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/sphinxcontrib-spelling?uuid=0b295eba-a6e1-4058-b6c4-526f705bee4f",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/sqlparse?uuid=8fcacf7d-79ba-4658-8963-e00a925a8908",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/sqlparse?uuid=15463bb1-35ef-4a08-8e4e-fcca09b64f02",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/tzdata?uuid=24724dac-00f4-4979-95ca-fd975855dad3",
    "SPDXRef-scancodeio-discovereddependency-pkg:pypi/tzdata?uuid=c740db9d-d3a8-4406-be3c-b1ba578bb35a"
  ],
  ...

Should we also include the SPDX IDs of the files in the codebase as well? My gut feeling is opposed to it because in the case of my test scan of django 4.1.4, we would have an extra ~9000 lines of SPDX IDs that do not provide additional value.

[DennisClark]

@JonoYang great, thanks! and follow your gut feeling please regarding the files. Let me know when and where I can try out the improved code please.

[DennisClark]

Hi @JonoYang You certainly got the "hard part" right, and so you have resolved the issue from a technical point of view, with the SPDX ID for the embedded packages and dependencies, but it would be really nice if you could also provide some text in the first higher level "description" field (see the comments above). It can be something simple like the name of whatever it was that was scanned. Unless, of course, I am interpreting the spec incorrectly, in which case what you have done is fine.

[JonoYang]

@DennisClark

I think the description field is describing the data that should go into the documentDescribes field, rather than it describing the SPDX ID that is going into the field. The other fields in that snippet you posted also shows that the documentDescribes field is an array, where each item in the array is an SPDX ID string.