Trusted image policies ensure the integrity and security of container images and VMs deployed into Kubernetes environments. Using these policies, you can be assured that your images are from a trusted source, are built on approved and validated base images, and are free from unauthorized modifications.
Trusted image policies ensure the integrity and security of container images and VMs deployed into Kubernetes environments. This topic details the policy enforcement logic that Cortex uses to determine if an image is trusted, what action to take, and which issues to generate.
Images are evaluated to see if they:
Match the trusted image policy criteria.
Should be allowed or prevented, based on policy criteria and scope.
Should trigger the creation of security or posture issues when untrusted.
Note
Registry scanning is for finding problems that are objectively issues regardless of context, organization, or scope. Trust, however, is subjective. Depending on the scope and other factors, an issue may or may not be problematic, and can change over time depending on the context.
When defining a trusted image policy, you determine what actions should be taken if an image is not trusted.
Create an Issue. The image is allowed to run, but a violation is recorded as a posture and/or security issue. For the purposes of this documentation, we refer to this as an issue-only action.
The primary purpose of trusted image policies with the issue-only action is auditing and compliance. These violations are identified by Cortex periodic scans.
The issue-only action assesses trust across a range of assets, including Kubernetes workloads (which are cloud-agnostic, supporting AWS, Azure, GCP, OCI), virtual machines (VMs).
Prevent and Create an Issue. Images created after this policy is enabled will be blocked from running if they don't meet the trust criteria, and a violation will also be recorded as a security issue. For images that were already running—and which don't meet the trust criteria—a posture issue is created.For the purposes of this documentation, we will refer to this as the prevent action.
These issues block deployment in real-time.
The prevent action is cloud-agnostic (supports AWS, Azure, GCP, OCI) and enforced at the Kubernetes cluster level via the admission controller.
Consider the following prerequisite:
All trusted image policies are designed for runtime security enforcement. However, to ensure that policies with the prevent action can successfully block untrusted images, the policy's scope must be on a Kubernetes cluster where the admission controller is enabled.
The evaluation of trusted image policies is based on logic that determines the following critical outcomes: Which container images are trusted in a given scope and which violations result in the creation of security and posture issues.
Utilizing an "OR-based" approach
Cortex utilizes an "OR-based" approach, with no explicit priority or rule order when resolving policy conflicts.
This enables Cortex to prioritize the most permissive result among conflicting policies with prevent actions, while enforcing the most restrictive result between policies with issue-only actions.
Prevent actions: Minimizing prevention, and allowing as many images as possible to be trusted, is desirable in order to avoid blocking workloads from running.
Issue creation: Minimizing the number of issues generated is desirable to avoid issue redundancy, unnecessary analysis, and issue handling.
Understanding the approach and the logic behind it helps you create policies efficiently.
Recommendations include:
When possible, the optimal way to define all trust criteria is to define the criteria in one policy.
If you are defining cluster-level trust criteria along with other options at the namespace/registry level, understand that because there are no priority/order options, you must plan your policies accordingly.
Trusting and allowing images by scope
Trusted image policies provide granular control by ensuring that policies only impact the specific environment (scope) for which they are defined. An image can be trusted in one scope and untrusted in another. For example, a third party image may be trusted in your Development environment but immediately untrusted in your Production environment.
If you have not defined any trusted image policies for a specific scope, the default behavior is that all images within that scope are implicitly trusted However, once a policy is defined for a scope, any image not explicitly trusted by that policy is automatically untrusted.
Policy enforcement is directly tied to the defined scope. When you define the Asset Group scope for a policy (for example, a specific cluster's Test namespace), the policy applies only to the resources within that exact definition. The more narrowly defined your scope, the more targeted the policy's enforcement will be, ensuring the enforcement does not affect unrelated resources.
If multiple policies with prevent actions cover the same scope, the logic is additive (allow-wins). As long as at least one of those policies results in the image being trusted, the image will be allowed to run.
Note
Trusted image policies do not override other policies and their rules, such as malware policies, misconfiguration policies, and secrets policies.
Generating issues
The following points clarify the logic for generating runtime security issues and posture issues based on your defined policies:
Runtime security issues:
A runtime security issue is generated only if an image is untrusted by all policies. If at least one policy trusts the image, no runtime security issue is created. Additionally, each policy with a prevent action that identifies an issue will generate only one corresponding runtime security issue.
Posture issues:
For policies with the prevent action:
if an image is prevented from running, no posture issues are created by any policy within that scope.
Posture issues are created if images that are running violate any policy within the scope.
For policies with the issue-only action, posture issues are created at the granular level of one issue per untrusted image per policy that fails the trust criteria. The posture Issues are created on the relevant asset type and are titled accordingly:
Kubernetes workload asset type: The issue title will be Untrusted image running in Kubernetes workload X.
Virtual machine asset type: The issue title will be Untrusted image running in Virtual Machine Y.
For each issue regardless of asset type, the description will be either:
For untrusted images:
[AssetType] [AssetName] is running the image {ImageName}. that does not comply with the trust criteria defined in the Trusted Images policy [PolicyName].
For cases when there's missing information:
[AssetType] [AssetName] is running the image {ImageName}. Information is missing to determine compliance with the trust criteria defined in the Trusted Images policy [PolicyName].
The issues will also include the image name, a link to the image asset page, the relevant Kubernetes hierarchy (cluster and namespace) for Kubernetes workloads only, and more.
Policy evaluation: Handling unknown, missing or partial image data
Situations may arise where insufficient information is available at the time of deployment to conclusively arrive at a trust verdict. This means Cortex cannot confirm an image's trusted or untrusted status. Examples of such situations where there is a lack of complete image metadata include:
Initial discovery or missing scan data: If an image is being evaluated for the first time, some vital information may be temporarily unavailable that would generally have been derived from a prior comprehensive scan, such as the image's Base Layer data or its CLI scan status.
Partial deployment metadata: The trust criteria specified in your trusted image policy may include image metadata that is not present in the deployment file. For example, a policy might mandate a specific tag, but the Kubernetes deployment resource uses only the image digest (SHA) and omits the tag.
Cortex handles these situations differently based on the policy's action:
For policies with issue-only actions: Cortex creates a posture issue and a runtime security issue, flagging the image as potentially untrusted due to insufficient data. The image is allowed to deploy, but the issue prompts the user to investigate the data gap.
For policies with prevent actions: Cortex relies on the user-defined Action when trust verdict is unavailable value in the policy's action section.
Caution
The default behavior for the prevent action when trust criteria are unavailable is Create an Issue. Be aware that changing this default will mean an incomplete deployment file can block a workload.
Policy decision logic for workloads
Situations might arise where within the same workload, multiple images or multiple policies yield conflicting trust results. When these conflicts occur—such as one policy trusting an image while another prevents it, or a single deployment containing both trusted and untrusted images—Cortex relies on the following defined logic to determine the final deployment outcome and what issues, if any, are generated.
For policies with issue-only actions: Any time an image fails the trust criteria for an Issue-only action policy, a Posture Issue is created. This action is non-blocking; the image is allowed to deploy regardless of the issue.
For policies with prevent actions:
Conflicting allow vs. prevent policies: If multiple prevent action policies apply to a single image within a workload, and one policy allows the image while another does not trust it, the image is ultimately trusted and allowed to run. This follows the "Allow-Wins" principle.
Conflicting Images within the same workload: If a single workload (meaning, one deployment) contains both trusted and untrusted images, the entire deployment is blocked. The security risk posed by the single untrusted image prevents the entire workload from running.
This section provides examples that help illustrate the policy enforcement logic described above.
This example illustrates how Cortex determines how to allow or prevent images, and create issues, when multiple policies conflict.
User deploys the docker.io/library/alpine:1.2.3 image.
Trusted image policies are validated at set periodic scan intervals or when a resource is deployed.
Two trusted image policies with prevent actions evaluate the image to determine its trust status. Cortex uses an "OR-based" evaluation for conflicting prevent action policies to determine if the image is trusted.
Policy 1 allows the image because the image is in the docker.io registry. So even though Policy 2 does not trust the image, the trust verdict is trusted and image deployment proceeds.
No runtime security issues are created because the image is trusted by one policy—namely, Policy 1.
No posture issues are created because:
There are no policies with issue-only actions—only policies with prevent actions.
The user defined two trusted registries, and a trusted image comes from one of them.
The user does not anticipate any further issues.
This example illustrates how Cortex determines how images are prevented from deployment in cases where a data verdict is unavailable.
User deploys the production:alpine@sha256:554443 image with the base image of base2.
Trusted image policies are validated at set periodic scan intervals or when a resource is deployed.
Three policies with prevent actions evaluate the image to determine its trust status. Cortex uses an "OR-based" evaluation for conflicting policies to determine if the image is trusted.
Policy 1's criteria production/alpine:1.2.3 only partially match the deployed image's full image identifier, production:alpine@sha256:554443. For example, the deployed image is missing the tag.
If the image developer built the image, pushed it to the registry, and tagged it as :1.2.3, and that specific content generated the digest sha256:554443..., then they are a match at that moment in time. But this could change, so there is no definitive trust verdict.
Because policy 1 has a prevent action with the additional Action when trust verdict is unavailable option set to Prevent and create an issue, the image is untrusted.
Policy 2, with its issue-only action, only trusts base1 images, so this policy considers the image untrusted.
Policy 3, with its issue-only action, requires the image to have been scanned by a CLI scanner, so the image is untrusted.
Because all three policies do not trust the image, the image is prevented and deployment does not proceed.
A runtime security issue is created because of at least one policy does not trust the image. Only one runtime security issue is created, even though three policies don't trust the image.
No posture issues are created because the image was prevented. Posture images must be actionable, and no actions can be taken on a prevented image.
This example illustrates how Cortex determines how images are allowed to deploy in cases where a data verdict is unavailable.
User deploys the production:alpine@sha256:554443 image with the base image of base2.
Trusted image policies are validated at set periodic scan intervals or when a resource is deployed.
Three policies evaluate the image to determine its trust status. Cortex uses an "OR-based" evaluation for conflicting policies to determine if the image is trusted.
Policy 1's criteria production/alpine:1.2.3 only partially match the deployed image's full image identifier, production:alpine@sha256:554443. For example, the image is missing the tag.
If the image developer built the image, pushed it to the registry, and tagged it as :1.2.3, and that specific content generated the digest sha256:554443..., then they are a match at that moment in time. But this could change, so there is no definitive trust verdict.
Because policy 1 has a prevent action with the additional Action when trust verdict is unavailable option set to Create an issue, the image is trusted.
Policy 2, with its issue-only action, only trusts base1 images, so the policy considers the image is untrusted.
Policy 3, with its issue-only action, requires the image to have been scanned by a CLI scanner, so the image is considered untrusted.
The image is allowed and deployment proceeds, because one of the three policies trusts the image and Cortex uses an "OR-based" approach.
No runtime security issue is created because of the trust verdict is to trust and allow.
No posture issues are created because the image was prevented. Posture images must be actionable, and no actions can be taken on a prevented image.