One of Syft's most important jobs is identifying operating system packages on your container images or filesystems. This list of packages and other software is the raw material for the resulting Software Bill of Materials (SBOM). A common question when you see a package in an SBOM is “how did Syft come to the conclusion that this package exists?” 

To answer this question, we implemented a new feature in Syft 0.78.0 that can “show its work” and include information in the SBOM of the files that Syft has detected as evidence of the package. This is called location annotation. Here is an example from an SBOM in JSON format, generated by scanning an image that uses dpkg package management:

[
  {
    "id": "3e9282034226b93f",
    "name": "adduser",
    "version": "3.118",
    "type": "deb",
    "foundBy": "dpkgdb-cataloger",
    "locations": [
      {
        "path": "/var/lib/dpkg/status",
        "layerID": "sha256:ec09eb83ea031896df916feb3a61cefba9facf449c8a55d88667927538dca2b4",
        "annotations": {
          "evidence": "primary"
        }
      }
      {
        "path": "/usr/share/doc/adduser/copyright",
        "layerID": "sha256:ec09eb83ea031896df916feb3a61cefba9facf449c8a55d88667927538dca2b4",
        "annotations": {
          "evidence": "supporting"
        }
      },
      {
        "path": "/var/lib/dpkg/info/adduser.conffiles",
        "layerID": "sha256:ec09eb83ea031896df916feb3a61cefba9facf449c8a55d88667927538dca2b4",
        "annotations": {
          "evidence": "supporting"
        }
      },
...

You can see several items in the locations array. These are some of the specific files that Syft has used to identify the adduser package, version 3.118. There are two kinds of evidence in this array: primary and supporting. Primary evidence are the files that are used to determine a package’s existence on the system being scanned, and supporting evidence is additional data not necessarily fundamental to the package’s existence, but providing additional information.

We additionally raise up locations that are annotated as primary evidence as package-to-file relationships in the SBOM so that this information can be used across more SBOM formats in a portable way.

You can read through the pull request for this feature for more technical details. If you’re interested in learning more, implementing location annotations for a new package cataloger, or if you have any questions about the new feature, please join us on Discourse!