Fm/vcs link

[tamilari]

feat: add Vcs informations to sbom

For spdx, add the Vcs information in the 'download_location' field. Format this string according to the spdx documentation. It is not possible to add the url to the web interface for browsing the repository, since there is no field for this information.

For cdx add the Vcs information and the url to the web interface to the 'external_refs' object with the type set to 'vcs'.

This Vcs information can be useful for analysing the packages (e.g. how well a package is maintained and what the risk factor is).

[fmoessbauer]

Can we please combine this into a single field with a custom type?

[fmoessbauer]

Are the entries in the .dsc files (and alike) usually precise, or do they just link to the upstream repo? My interpretation of https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field is that it is in general allowed to be imprecise, but it I would also like to hear the opinion of @gernot-h .

[Urist-McGit]

IMO this should link to the snapshot download location of the .dsc file. We are representing a source package and I would not consider the link to the repository a location where I can download it

[tamilari]

I also thought that this field wasn't the best fit for VCS information, but the description and examples provide such detailed instructions on how to format the VCS information. I couldn't find a better place for it, and I assume that we need this information in the SPDX format as well. Alternatively, maybe it could go in the source information field (https://spdx.github.io/spdx-spec/v2.3/package-information/#712-source-information-field)?

[Urist-McGit]

What speaks against using the external reference field?

[Urist-McGit]

While we are at it, there is documentation now about what fields are modeled how. See the Mapping of Debian Source Packages to SBOM Packages/Components section in docs/source/design-decisions.rst, you need to add the additional information there too.

[tamilari]

What speaks against using the external reference field?

I can't find a suitable category and type. The only option there would be to use the 'Other' category.

[tamilari]

While we are at it, there is documentation now about what fields are modeled how. See the Mapping of Debian Source Packages to SBOM Packages/Components section in docs/source/design-decisions.rst, you need to add the additional information there too.

Thanks for the reminder. I'll do that once we've agreed on a field.

[Urist-McGit]

Yes, I would do something like category = Other and type = vcs

[gernot-h]

Sorry, I'm having a hard time completely following the theoretical discussion here, so I can't provide a final opinion. Can you please provide two or three short examples how the final SPDX and CDX output would look like?

[tamilari]

For CDX, it is pretty clear on where to add the Debian Version Control System fields Vcs-Browser and Vcs-<type>. There is a vcs type for the externalReferences field. So a component would look something like this:

{
    "externalReferences": [
        {
            "comment": "URL of a web interface for browsing the repository",
            "type": "vcs",
            "url": "https://salsa.debian.org/perl-team/modules/packages/libxml-sax-expat-perl"
        },
        {
            "comment": "Version control system of type Git",
            "type": "vcs",
            "url": "https://salsa.debian.org/perl-team/modules/packages/libxml-sax-expat-perl.git"
        },
        {
            "comment": "homepage",
            "type": "website",
            "url": "https://metacpan.org/release/XML-SAX-Expat"
        }
    ],
    "name": "libxml-sax-expat-perl",
    "version": "0.51-2"
}

The only problem there is that you can't differentiate between the vcs-Browser and the normal vcs field based on the type alone.

For SPDX, this isn't clear since there isn't a suitable category or type for this in the externalReferences field. Therefore, we would use the Other category. There, we can use any type, so a package could look like this:

{
    "downloadLocation": "NOASSERTION",
    "externalRefs": [
        {
            "referenceCategory": "PACKAGE_MANAGER",
            "referenceLocator": "pkg:deb/debian/[email protected]?arch=source",
            "referenceType": "purl"
        },
        {
            "comment": "URL of a web interface for browsing the repository",
            "referenceCategory": "OTHER",
            "referenceLocator": "https://salsa.debian.org/perl-team/modules/packages/libxml-sax-expat-perl",
            "referenceType": "vcsBrowser"
        },
        {
            "comment": "Version control system of type Git",
            "referenceCategory": "OTHER",
            "referenceLocator": "https://salsa.debian.org/perl-team/modules/packages/libxml-sax-expat-perl.git",
            "referenceType": "vcs"
        }
    ],
    "name": "libxml-sax-expat-perl",
    "versionInfo": "0.51-2"
}

Previously, I had it in the download location field. This is partly because there is such a detailed explanation on how to format the string for all the different version control systems. However, we feel that the name of this field is not appropriate.

{
    "downloadLocation": "git+https://salsa.debian.org/perl-team/modules/packages/libxml-sax-expat-perl.git",
    "externalRefs": [
        {
            "referenceCategory": "PACKAGE_MANAGER",
            "referenceLocator": "pkg:deb/debian/[email protected]?arch=source",
            "referenceType": "purl"
        }
    ],
    "name": "libxml-sax-expat-perl",
    "versionInfo": "0.51-2"
}

[Urist-McGit]

Could we also have a test that verifies the parsing works as expected? The setup should be available in the apt-sources root, from there you could simply check if it parsed correctly into a package.