# Ratify policy for evaluation of container image SBOM at admission

## Overview

### Problem/Motivation

Ratify is a verification engine that enables you to verify the security metadata of artifacts and deploy only those that comply with your policies. While Ratify supports the verification of the integrity and authenticity of container images, it’s important to note that trusted images may contain non-compliant software, such as certain licenses or software that are not allowed according to your organization’s security and compliance rules. Deploying non-compliant images poses a security and compliance issue.

### User stories

Alice is a security engineer at Contoso who is responsible for ensuring that the container images running in K8s clusters are secure and compliant. To achieve this, she has installed OPA Gatekeeper and Ratify in the K8s clusters to configure admission policies that prevent deploying untrusted, vulnerable, and non-compliant container images. While she has enforced the integrity policy to ensure that only trusted images are deployed, she has not found policies to prevent the deployment of non-compliant images. Therefore, she would like to have a policy that verifies the software bill of materials (SBOM) of container images to ensure that they are compliant with Contoso’s security and compliance rules.

To ensure that SBOMs are trusted, Alice configures the policy to validate their signatures.

To comply with Contoso’s strict security and compliance rules, Alice configures the policy to prevent deployment of images that contains software with disallowed licenses. Additionally, Alice configures the policy to prevent deployment of images that contains a list of software that are disallowed.

Alice is aware of VEX documents that can be used to filter out vulnerable software based on the SBOM, so she would like the policy to evaluate VEX documents by default, provided VEX documents are available.

Alice seeks flexible policy enforcement. In the production environment, she denies image deployment if policy evaluation fails. However, for testing and development environments, she configures the policy to allow image deployment with auditing logs even when policy evaluation fails.

Since Contoso’s security and compliance rules may change over time, Alice wants to update the policy configuration at real time.

### Goals/Non-Goals

Goals:
- Provide users with a built-in rego policy that prevents deploying non-compliant and vulnerable images
- Support SBOMs in standard formats, such as SPDX and Cyclonedx
- Users can update the parameters in real-time.
- Support VEX documents, like openVEX, cyclonedx VEX
- The configuration used for image signature verification is also used for signature verification.

Non-goals:

- Support non-standard SBOM generated by different tools
- Support non-rego policy

### Proposal

The proposal aims to enhance Ratify by adding support for verifying new types of data, namely SBOMs in standard formats such as SPDX and CycloneDx. A built-in rego policy will be provided to users, and they will only need to update policy parameters to achieve the goal of preventing deployment of non-compliant and vulnerable images.

### User Experience

#### Set up the policy for SBOMs verification in K8s

The following describes the procedure of setting up policies for a fresh installation
1. Install Gatekeeper.
1. Install Ratify with built-in rego policies.
1. Apply the policy of preveneting deployment non-compliant and vulnerable images
1. Configure enforcement actions based on different environments
- For testing environment, set `enforcementAction` to `warn` or `dryrun` in Gatekeeper constraint. To apply the parameter, run the command `kubectl apply -f constraint_warn.yaml` or `kubectl apply -f constraint_dryrun.yaml`.
- For development environment, set `enforcementAction` to `warn` or `dryrun` in Gatekeeper constraint. To apply the parameter, run the command `kubectl apply -f constraint_warn.yaml` or `kubectl apply -f constraint_dryrun.yaml`.
- For production environment, set `enforcementAction` to `deny` in Gatekeeper constraint. To apply the parameter, run the command `kubectl apply -f constraint_deny.yaml`.
1. Pass values to parameters defined by the policy. Assuming these parameters are listed in file `policy_sbom_parameters.yaml`.
| Parameters | Description | Default |
| ----------------- | ---------------------------------------------------------------------------------------------------- | ------- |
| signature.enabled | Whether validating signatures or not, if enabled, use the same signature verification from the image | true |
| licenseDenylist | A list of licenses that are disallowed, for example, GPLv3 | "" |
| softwareDenyList | A list of software that are disallowed, "name[>,=,<][version]" for example log4j, log4j<=2.14 | "" |

To apply the parameters, run the following command:

`kubectl apply -f verifier_sbom_settings.yaml`

#### Update policy configuration at real-time

Assuming policy parameters are configured in file `verifier_sbom_settings.yaml`. At runtime, users update this file with new values, and then run the following command:

`kubectl apply -f verifier_sbom_settings.yaml`

#### Workflow in Rego policy for SBOMs verification

The following steps shows the workflow in the Rego policy.

1. Check whether the target image has SBOMs.
- If there are no SBOMs, whether the deployment of the image is denied or not depends on the enforcement actions.
- If there are SBOMs, continue to the next step.
1. Check the parameter `signature.enabled` for signature verification.
- If signature verification is required, use the same signature verification from the image.
- If verification fails, whether the deployment of the image is denied or not depends on the enforcement actions.
- If verification succeeds, continue to the next step.
- If signature verification is not enabled, continue to the next step.
1. Check whether there are license in the license deny list based on the value of parameter `licenseDenyList`.
- If there is any license in the deny list, whether the deployment of the image is denied or not depends on the enforcement actions.
- If there are no licenses in the deny list, continue to the next step.
1. Check whether there are software in the software deny list based on the value of parameter `softwareDenyList`.
- If there is any software in the deny list, whether the deployment of the image is denied or not depends on the enforcement actions.
- If there is no software in the deny list, verification succeeds with a successful log.
1. Check whether VEX documents exist or not
- If yes, check whether there are vulnerable software.
- If yes, whether the deployment of the image is denied or not depends on the enforcement actions.
- If no, verification succeeds with a successful log.
- If no, verification succeeds with a successful log

#### Error messages

| Scenarios | Error messages |
| ----------------------------------------------------------------| ------------------------------------------------------------------------------------------------------- |
| SBOM is not found | SBOM is not found for the image `reference_by_digest` |
| SBOM is not in SPDX or CycloneDx format | The SBOM format is not supported. Please use the SPDX or CycloneDx format. Image: `reference_by_digest` |
| Signature verification is enabled, but signatures are not found | Signatures are not found or signature types are not supported for the image `reference_by_digest` |
| Signature verification failure | Failed to validate signature of type `Type`, signature manifest `Reference`, reason: `Reason` |
| Found licenses in the license deny list | The image contains licenses `Licenses` that are not allowed, image: `reference_by_digest` |
| Found software in the software deny list | The image contains software `name` and `version` that are not allowed, image: `reference_by_digest` |
| Found vulnerable software according to VEX documents | The image contains vulnerable software `name` and `version`, image: `reference_by_digest` |

Note: The error messages are just examples, we need to polish them according to error messages guideline, which is under review now.

## Requirements

### Functional Requirements

| Feature | Priority |
| ------------------------------------------------------------| -------- |
| New parameterized Rego policy for verifying SBOM | P0 |
| Support assessing software license deny list | P0 |
| Support assessing software packages deny list | P0 |
| Support SBOM in SPDX format | P0 |
| Update the value of policy parameters in real-time | P0 |
| Support VEX documents in openVex format | P1 |
| Support VEX documents in cyclonedx VEX format | P1 |
| Support verifying SBOM in CycloneDx format | P1 |

### Test Requirements

#### Performance

Assumptions:
- One SBOM for each image
- Every SBOM is signed with 1 signature
- Each image has 1 signature
- A new version of image is published every 30 days
- One Pod has 10 images

Based on the assumptions, after image is stored in a registry for consumption and before a new version is published, it could have 1 SBOM + 1 SBOM signatures + 1 image signature = 3 referrers. We could combine this with vuln policy performance testing.

Variables:
- The Size of a SBOM: 1M, 2M, 3M (need suggestions on rational sizes)
- Ratify instance: single instance, HA

Targets:
- What is maximum number of pods supported (with acceptable request duration) for a single Ratify instance, and what is the corresponding request duration in P95, CPU resource utiliaztion, MEM resource utilization for 200 Pods, 2000 pods and up to the limit. Test different size of vulnerability reports.
- What is maximum number of pods supported (with acceptable request duration) for Ratify HA with 3 replicas, and what is the request duration in P95, CPU resource utiliaztion, MEM resource utilization for 200 Pods, 2000 pods and up to the limit. Test different size of vulnerability reports.