Compare Base Image Policy Checks

This feature provides a mechanism to compare the policy checks for an image with those of a base image. You can read more about base images and how to find them here. Base comparison uses the same policy and tag to evaluate both images to ensure a fair comparison. The API yields a response similar to the policy checks API with an additional element within each triggered gate check to indicate whether the result is inherited from the base image.

Usage

This functionality is currently available via the Enterprise UI and API.

API

Refer to API Access section for the API specification. The policy check API (GET /v2/images/{imageDigest}/check) has an optional base_digest query parameter that can be used to specify an image to compare policy findings to. When this query parameter is provided each of the finding’s inherited_from_base field will be filled in with true or false to denote if the finding is present in the provided image. If no image is provided than the inherited_from_base field will be null to indicate no comparison was performed.

Example request using curl to retrieve policy check for an image digest sha256:xyz and tag p/q:r and compare the results to a base image digest sha256:abc

curl -X GET -u {username:password} "http://{servername:port}/v2/images/sha256:xyz/check?tag=p/q:r&base_digest=sha256:abc"

Example output:

{
    "image_digest": "sha256:xyz",
    "evaluated_tag": "p/q:r",
    "evaluations": [
        {
            "comparison_image_digest": "sha256:abc",
            "details": {
                "findings": [
                    {
                        "trigger_id": "41cb7cdf04850e33a11f80c42bf660b3",
                        "gate": "dockerfile",
                        "trigger": "instruction",
                        "message": "Dockerfile directive 'HEALTHCHECK' not found, matching condition 'not_exists' check",
                        "action": "warn",
                        "policy_id": "48e6f7d6-1765-11e8-b5f9-8b6f228548b6",
                        "recommendation": "",
                        "rule_id": "312d9e41-1c05-4e2f-ad89-b7d34b0855bb",
                        "allowlisted": false,
                        "allowlist_match": null,
                        "inherited_from_base": true
                    },
                    {
                        "trigger_id": "CVE-2019-5435+curl",
                        "gate": "vulnerabilities",
                        "trigger": "package",
                        "message": "MEDIUM Vulnerability found in os package type (APKG) - curl (CVE-2019-5435 - http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5435)",
                        "action": "warn",
                        "policy_id": "48e6f7d6-1765-11e8-b5f9-8b6f228548b6",
                        "recommendation": "",
                        "rule_id": "6b5c14e7-a6f7-48cc-99d2-959273a2c6fa",
                        "allowlisted": false,
                        "allowlist_match": null,
                        "inherited_from_base": false
                    }
                ]
                ...
            }
            ...
        }
        ...
    ]
}

Dockerfile directive 'HEALTHCHECK' not found, matching condition 'not_exists' check is triggered by both images and hence inherited_from_base is marked true
MEDIUM Vulnerability found in os package type (APKG) - curl (CVE-2019-5435 - http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5435) is not triggered by the base image and therefore the value of inherited_from_base is false

Last modified June 3, 2024