Corrections

When Anchore analyzes an image, it persists a Software Bill of Materials (SBOM) which will be submitted for periodic scanning for known vulnerabilities. During the scan, various attributes will be used from the SBOM package artifacts to match to the relevant vulnerability data. Depending on the ecosystem, the most important of these package attributes tend to be Package URL (purl) and/or Common Platform Enumeration (CPE). The Anchore analyzer attempts to generate a best effort guess of the CPE candidates for a given package as well as the purl based on the metadata that is available at the time of analysis (ex. for Java packages, the manifest, which contains multiple different version specifications among other metadata), but sometimes gets this wrong.

To facilitate the necessary corrections in these instances, Anchore provides the Corrections feature. Now, a user can provide a correction that will update a given package’s metadata so that attributes (including CPEs and Package URLs) can be corrected at the time that Anachore performs a vulnerability scan.

An example follows for a very common scenario in the java maven ecosystem where the official maven groupid and artifactid are not available in the metadata and the best guess that the Anchore analyzer surfaces for package url and CPEs is not in line with the vulnerability data, so a correction can be issued to align them.

Imagine an Anchore analysis results in the following package content:

{
  "cpes": [
    "cpe:2.3:a:apache:catalina:9.0.88:*:*:*:*:*:*:*"
  ],
  "implementationVersion": "9.0.88",
  "licenses": [
    "https://www.apache.org/licenses/LICENSE-2.0.txt"
  ],
  "location": "/usr/local/tomcat/lib/catalina.jar",
  "mavenVersion": "N/A",
  "origin": "Apache Software Foundation",
  "package": "catalina",
  "purl": "pkg:maven/org.apache.tomcat-catalina/[email protected]",
  "specificationVersion": "9.0",
  "type": "JAVA-JAR",
  "version": "9.0.88"
}

There are several issues with this entry. The maven groupid and artifactid within the purl, the package name, and the CPE are all not in line with what is expected for proper vulnerability matching.

Using the above example, a user can add a correction as using anchorectl or via HTTP POST to the /corrections endpoint:

{
  "description": "Correct Tomcat Catalina package metadata",
  "match": {
    "type": "java",
    "field_matches": [
        {
            "field_name": "package",
            "field_value": "catalina"
        }
    ]
  },
  "replace": [
      {
          "field_name": "cpes",
          "field_value": "cpe:2.3:a:apache:tomcat_catalina:{version}:*:*:*:*:*:*:*"
      },
      {
          "field_name": "purl",
          "field_value": "pkg:maven/org.apache.tomcat/tomcat-catalina@{version}"
      },
      {
          "field_name": "package",
          "field_value": "tomcat-catalina"
      }
  ],
  "type": "package"
}

JSON Reference:

• description: A description of the correction being added (for note taking purposes)
• replace: a list of field name/value pairs to replace. For the “cpes” and “purl” field only, Anchore Enterprise can recognize a templated field via curly braces “{}”. Package JSON keys contained here will be replaced with their corresponding value from the package. For “cpe” if the templated field does not exist in the package, the corresponding cpe component will be replaced with *. For “purl” if the templated field doesn’t exist the purl replacement will be aborted and the purl will remain unchanged from the original value.
• type: The type of correction being added. Currently only “package” is supported
• match:
  • type: The type of package to match upon. Supported values are based on the type of content available to images being analyzed (ex. java, gem, python, npm, os, go, nuget)
  • field_matches: A list of name/value pairs based on which package metadata fields to match this correction upon
    • The schema of the fields to match can be found by outputting the direct JSON content for the given content type:
      • Ex. Java Package Metadata JSON:

      {
          "cpes": [
              "cpe:2.3:a:*:spring-core:5.1.4.RELEASE:*:*:*:*:*:*:*",
              "cpe:2.3:a:*:spring-core:5.1.4.RELEASE:*:*:*:*:java:*:*",
              "cpe:2.3:a:*:spring-core:5.1.4.RELEASE:*:*:*:*:maven:*:*",
              "cpe:2.3:a:spring-core:spring-core:5.1.4.RELEASE:*:*:*:*:*:*:*",
              "cpe:2.3:a:spring-core:spring-core:5.1.4.RELEASE:*:*:*:*:java:*:*",
              "cpe:2.3:a:spring-core:spring-core:5.1.4.RELEASE:*:*:*:*:maven:*:*"
          ],
          "implementation-version": "5.1.4.RELEASE",
          "location": "/app.jar:BOOT-INF/lib/spring-core-5.1.4.RELEASE.jar",
          "maven-version": "N/A",
          "origin": "N/A",
          "package": "spring-core",
          "purl": "pkg:maven/org.springframework/[email protected]",
          "specification-version": "N/A",
          "type": "JAVA-JAR"
      }
      

Note: if a new field is specified here, it will be added to the content output when the correction is matched. See below for additional functionality around CPEs and Package URL

To add the above JSON using anchorectl the following command can be used

anchorectl correction add -i path-to-file.json

You could also achieve something similar using

anchorectl correction add \
--match package=catalina \
--type java \
--replace cpes="cpe:2.3:a:apache:tomcat_catalina:{version}:*:*:*:*:*:*:*" \
--replace purl="pkg:maven/org.apache.tomcat/tomcat-catalina@{version}" \
--replace package="tomcat-catalina" \
--description="Correct Tomcat Catalina package metadata"

Don’t forget you can list, delete and get a correction with the anchorectl

The command to retrieve a list of existing corrections is:

anchorectl correction list

The command to delete a corrections is:

anchorectl correction delete {correction_id}
# {correction_id} is the UUID of the correction you wish to delete

The command to get a correction is:

anchorectl correction get {correction_id}
# {correction_id} is the UUID of the correction you wish to get

The result of the correction can be checked using the image content command of anchorectl. For example to see our above java correction we would run

anchorectl image content -t java Image_sha256_ID -o json

We would now see the tomcat-catalina package content returned with the expected values:

{
  "cpes": [
    "cpe:2.3:a:apache:tomcat_catalina:9.0.88:*:*:*:*:*:*:*"
  ],
  "implementationVersion": "9.0.88",
  "licenses": [
    "https://www.apache.org/licenses/LICENSE-2.0.txt"
  ],
  "location": "/usr/local/tomcat/lib/catalina.jar",
  "mavenVersion": "N/A",
  "origin": "Apache Software Foundation",
  "package": "tomcat-catalina",
  "purl": "pkg:maven/org.apache.tomcat/[email protected]",
  "specificationVersion": "9.0",
  "type": "JAVA-JAR",
  "version": "9.0.88"
}

Note: Don’t forget to replace the Image_sha256_ID with the image ID you’re trying to test.

Corrections may be updated and deleted via the API as well. Creation of a Correction generates a UUID that may be used to reference that Correction later. Refer to the Enterprise Swagger spec for more details.