Document which fields of Syft SBOM are used in processing input

[chovanecadam]

What would you like to be added:

Documentation about what fields from the Syft JSON are used and for what purpose.

Why is this needed:

Some organizations have access to information about installed packages from other sources, e.g. from monitoring tools, or configuration management tools. In this case Syft is not used, but Syft SBOM is constructed from the data manually. Syft SBOM contains many fields which are not necessary for vulnerability analysis with Grype. It would be great to document which fields are necessary for Grype to function and to include this information in the changelog in case it changes.

Additional context:

[popey]

Hi @chovanecadam - thanks for the interesting issue. This sentence alone raises, for me, a point and a question

Syft SBOM contains many fields which are not necessary for vulnerability analysis with Grype.

• Question: Which fields? I'm not trying to be awkward, but when someone asserts that "Thing does something that is unnecessary", I'm inclined to ask for more data to back up the assertion.

• Point: Syft doesn't only exist to feed Grype. Many people use Syft to generate an SBOM which may be analyzed by some tool other than Grype. As such we probably shouldn't limit the data in the Syft output only to that which is consumed by Grype.

That said, I don't doubt that it might be useful to have documented somewhere, the metadata used by Grype to correctly identify packages, versions, files and origins.

But, it's all open source, so this would be a great "fresh eyeballs" taslk for someone. Thanks again for the question.

[chovanecadam]

To answer the question, through trial and error I have arrived at this snippet of an entry in the artifacts array. I am not sure if this even counts as a valid SBOM, but Grype does not complain.

    {
      "id": "118",
      "name": "zlib1g",
      "version": "1:1.2.13.dfsg-1",
      "type": "deb",
      "foundBy": "",
      "locations": [],
      "licenses": [],
      "language": "",
      "cpes": [],
      "purl": "pkg:pkg/deb/debian/zlib1g@1:1.2.13.dfsg-1?arch=amd64&distro=debian-12",
      "metadataType": "dpkg-db-entry",
      "metadata": {
        "package": "zlib1g",
        "source": "zlib",
        "version": "1:1.2.13.dfsg-1",
        "sourceVersion": "1:1.2.13.dfsg-1",
        "architecture": "amd64",
        "maintainer": "",
        "installedSize": 0,
        "provides": [],
        "depends": [],
        "files": []
      }

Many other fields in the SBOM are not AFAIK necessary, such as the files array or the artifactRelationships array. I didn't look at the source code of Grype to figure out which fields is it taking into considerations yet.

Would there be an interest at documenting this behavior and updating the docs? I might create the docs, but if there isn't interest in the project for this, I don't see the point. No docs is better than incorrect docs imo.

[popey]

Thanks @chovanecadam - if you would like to document it, I'm sure we can find somewhere in the docs to put it!
That would be a wonderful contribution. Apologies if my previous response sounded like I wasn't interested. 🙏

[chovanecadam]

Great. I will look into it hopefully sometime this week and notify you if I make some progress.