This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

False Positives

1 - Hints

Anchore Enterprise includes the ability to read a user-supplied ‘hints’ file to allow users to add software artifacts to Anchore’s analysis report. The hints file, if present, contains records that describe a software package’s characteristics explicitly, and are then added to the software bill of materials (SBOM). For example, if the owner of a CI/CD container build process knows that there are some software packages installed explicitly in a container image, but Anchore’s regular analyzers fail to identify them, this mechanism can be used to include that information in the image’s SBOM, exactly as if the packages were discovered normally.

Hints cannot be used to modify the findings of Anchore’s analyzer beyond adding new packages to the report. If a user specifies a package in the hints file that is found by Anchore’s image analyzers, the hint is ignored and a warning message is logged to notify the user of the conflict.

Configuration

See Configuring Content Hints

Once enabled, the analyzer services will look for a file with a specific name, location and format located within the container image - /anchore_hints.json. The format of the file is illustrated using some examples, below.

OS Package Records

OS Packages are those that will represent packages installed using OS / Distro style package managers. Currently supported package types are rpm, dpkg, apkg for RedHat, Debian, and Alpine flavored package managers respectively. Note that, for OS Packages, the name of the package is unique per SBOM, meaning that only one package named ‘somepackage’ can exist in an image’s SBOM, and specifying a name in the hints file that conflicts with one with the same name discovered by the Anchore analyzers will result in the record from the hints file taking precedence (override).

  • Minimum required values for a package record in anchore_hints.json
    {
        "name": "musl",
        "version": "1.1.20-r8",
        "type": "apkg"
    }
  • Complete record demonstrating all of the available characteristics of a software package that can be specified
    {
        "name": "musl",
        "version": "1.1.20",
        "release": "r8",
        "origin": "Timo Ter\u00e4s <[email protected]>",
        "license": "MIT",
        "size": "61440",
        "source": "musl",
        "files": ["/lib/ld-musl-x86_64.so.1", "/lib/libc.musl-x86_64.so.1", "/lib"],
        "type": "apkg"
    }

Non-OS/Language Package Records

Non-OS / language package records are similar in form to the OS package records, but with some extra/different characteristics being supplied, namely the location field. Since multiple non-os packages can be installed that have the same name, the location field is particularly important as it is used to distinguish between package records that might otherwise be identical. Valid types for non-os packages are currently java, python, gem, npm, nuget, go, binary. For the latest types that are available, see the anchorectl image content <someimage> output, which lists available types for any given deployment of Anchore Enterprise.

  • Minimum required values for a package record in anchore_hints.json
    {
        "name": "wicked",
        "version": "0.6.1",
        "type": "gem"
    }
  • Complete record demonstrating all of the available characteristics of a software package that can be specified
    {
        "name": "wicked",
        "version": "0.6.1",
        "location": "/app/gems/specifications/wicked-0.9.0.gemspec",
        "origin": "schneems",
        "license": "MIT",
        "source": "http://github.com/schneems/wicked",
        "files": ["README.md"],
        "type": "gem"
    }

Putting it all together

Using the above examples, a complete anchore_hints.json file, when discovered by Anchore Enterprise located in /anchore_hints.json inside any container image, is provided here:

{
    "packages": [
    {
        "name": "musl",
        "version": "1.1.20-r8",
        "type": "apkg"
    },
    {
        "name": "wicked",
        "version": "0.6.1",
        "type": "gem"
    }
    ]
}

With such a hints file in an image based for example on alpine:latest, the resulting image content would report these two package/version records as part of the SBOM for the analyzed image, when viewed using anchorectl image content <image> -t os and anchorectl image content <image> -t gem to view the musl and wicked package records, respectively.

Note about using the hints file feature

The hints file feature is disabled by default, and is meant to be used in very specific circumstances where a trusted entity is entrusted with creating and installing, or removing an anchore_hints.json file from all containers being built. It is not meant to be enabled when the container image builds are not explicitly controlled, as the entity that is building container images could override any SBOM entry that Anchore would normally discover, which affects the vulnerability/policy status of an image. For this reason, the feature is disabled by default and must be explicitly enabled in configuration only if appropriate for your use case.

2 - Corrections

When Anchore analyzes an image, it reports a Software Bill of Materials (SBOM) to be stored and later scanned in order to match package metadata against known vulnerabilities. One aspect of the SBOM is a best effort guess of the CPE (Common Platform Enumeration) for a given package. The Anchore analyzer builds a list of CPEs for each package based on the metadata that is available (ex. for Java packages, the manifest, which contains multiple different version specifications among other metadata), but sometimes gets this wrong.

For example, Java Spring packages are generally reported as follows:

  • Spring Core, version 5.1.4
    • cpe:2.3:a:*:spring-core:5.1.4:*:*:*:*:*:*:*

However, since Spring is a framework built by Pivotal Software, the CPE referenced in the NVD database looks more like:

  • cpe:2.3:a:pivotal_software:spring_security:5.1.4:*:*:*:*:*:*:*

To facilitate this correction, Anchore provides the Correction feature. Now, a user can provide a correction that will update a given package’s metadata so that attributes (including CPEs) can be corrected when Anchore does a vulnerability scan

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

{
  "description": "Update Spring Core CPE",
  "match": {
    "type": "java",
    "field_matches": [
        {
            "field_name": "package",
            "field_value": "spring-core"
        },
        {
            "field_name": "implementation-version",
            "field_value": "5.1.4.RELEASE"
        }
    ]
  },
  "replace": [
      {
          "field_name": "cpes",
          "field_value": "cpe:2.3:a:pivotal_software:spring_security:5.1.4:*:*:*:*:*:*:*"
      }
  ],
  "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.
  • 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",
    "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.

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=spring-core \
--match implementation-version="5.1.4.RELEASE" \
--type java \
--replace cpes="cpe:2.3:pivotal_software:spring_security:5.1.4:*:*:*:*:*:*:*" \
--replace description="Update Spring Core CPE"

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 see the spring-core package returned as having the CPE cpe:2.3:a:pivotal_software:spring_security:5.1.4:*:*:*:*:*:*:*

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.

CPE Templating

CPE replacement can be templated based on the other fields of the package as well. In the above example, a replacement could have been provided as follows:

{
  "field_name": "cpes",
  "field_value": "cpe:2.3:a:pivotal_software:spring_security:{implementationVersion}:*:*:*:*:*:*:*" 
}

For the “cpes” field only, Anchore Enterprise can recognize a templated field via curly braces “{}”. Package JSON keys contained here will be replaced with their corresponding value.