Configure artifact guard policies

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms . Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions .

This document describes how to create and manage artifact guard policies. For an overview of the service, features, and benefits, see the Artifact guard overview .

Before you begin

Before you can create an artifact guard policy, you must enable artifact guard in Security Command Center and obtain the required Identity and Access Management (IAM) roles and permissions.

Then, you can create a policy in the Google Cloud console or using Google Cloud CLI .

Enable artifact guard

Follow the steps in Configure Security Command Center services to enable artifact guard.

Required role

To get the permissions that you need to use artifact guard, ask your administrator to grant you the following Identity and Access Management (IAM) role on your project or organization:

• Artifact Scan Guard Evaluation Admin ( roles/artifactscanguard.policyEvaluator )

This role can be granted using the Google Cloud console or by running the following Google Cloud CLI command:

   
gcloud  
organizations  
add-iam-policy-binding  
 PROJECT_ID 
  
 \ 
  
--member = 
 "serviceAccount: YOUR_SERVICE_ACCOUNT_EMAIL 
" 
  
 \ 
  
--role = 
 "roles/artifactscanguard.policyEvaluator" 
  
 \ 
 

   
gcloud  
organizations  
add-iam-policy-binding  
 ORGANIZATION_ID 
  
 \ 
  
--member = 
 "serviceAccount: YOUR_SERVICE_ACCOUNT_EMAIL 
" 
  
 \ 
  
--role = 
 "roles/artifactscanguard.policyEvaluator" 
  
 \ 
 

For more information about granting roles, see Manage access to projects, folders, and organizations .

For more artifact guard roles, see Artifact guard roles and permissions .

Create a policy in the Google Cloud console

To create an artifact guard policy in the Google Cloud console, follow these steps:

1. In the Google Cloud console, go to Security > Rules, and click Create artifact guard policyor Create policy.

2. Enter a Policy IDand Descriptionfor the policy, then click Continue.

3. Select policy scopes and actions:

   • CI/CD platform

     • Select connector(s): The connectors this policy should be associated with. For every CI/CD build associated with the selected connectors, this policy will be evaluated.
     • Policy action: Select the action to take when the policy is violated.
       • Block builds failing the policy
       • Pass builds with alerts: CI/CD scanner policy evaluation results are displayed in the connected build pipelines.

   • Registry

     • Container Analysis Projects: This is only applicable to organizations, not projects. Add the Google Cloud projects you want this policy to be applied to.
     • Artifact Registry repositories: Select the repositories you want this policy to be applied to. These must be valid Artifact Registry repositories. If left blank, the policy will be applied to all repositories.
     • Policy Action: Select the action to take when the policy is violated.
       • Audit only: The policy is evaluated and any violations are logged for auditing purposes without blocking the resource. To see any violations, you must call the API using ListArtifactPoliciesEvaluations and GetArtifactPoliciesEvaluation .
       • Admission control: If a violation occurs while the policy is evaluated, the resource is blocked from proceeding.
         • Set Binary Authorization policies to dry run mode: See Enable dry-run mode for more information.
         • Binary Authorization Projects: This is only applicable to organizations, not projects. Add the Google Cloud projects you want admission control to be applied to.
         • GKE clusters: If left blank, admission control is applied to all GKE clusters.
         • Override Binary Authorization policies: This checkbox must be selected to update the Binary Authorization policy for admission control.

   • Runtime

     • Runtime projects: This is only applicable to organizations, not projects. Add runtime projects that contain GKE clusters.
     • GKE clusters: Select the GKE clusters you want this policy to be applied to. If left blank, the policy will be applied to all GKE clusters in the selected projects.

4. Define the policy rule. A policy rule is a set of criteria that determines which vulnerabilities and packages are allowed in your environment. A policy rule includes the following:

   • Severity threshold: Set the minimum severity level for a vulnerability to be included in policy evaluation. Vulnerabilities must meet or exceed this threshold to be included.

     For example, configuring the rule to Mediumincludes all Medium, High, and Criticalvulnerabilities in the assessment.

   • Vulnerability count threshold: Sets the maximum number of allowed vulnerabilities after other policy filters are applied. The policy is violated only if the count of these specific, filtered vulnerabilities exceeds the limit.

     For example, if you set a Severity threshold of High, exclude vulnerabilities with unavailable fixes, and set a count threshold of five, a build fails if it contains more than five fixable vulnerabilities that are rated Highor Critical.

   • Vulnerability status: Specify whether to include only vulnerabilities for which a fix is available. This allows prioritized remediation by targeting all vulnerabilities or only fixable ones.

   • Exceptions and Restrictions: These sections let you create specific allowances or blocks that override the general policy.

     • Exempted CVEs: Specify CVEs that are deemed acceptable in your environment for a specified duration. This is helpful for implementing temporary workarounds. You can set an expiration date for these exceptions. After this date, the vulnerability is no longer permitted and causes the policy to fail.
     • Restricted CVEs: Specify CVEs to always block, regardless of their severity rating. This is particularly useful for denoting vulnerabilities that present a unique risk to your specific application or infrastructure.
     • Allowed packages: List packages considered secure. Package version can be defined; otherwise, all versions are allowed.
     • Restricted packages: List packages to restrict. Restricted packages cause the policy to fail. Package version can be defined; otherwise, all versions are restricted.

5. Click Create.

Available artifact guard policies are listed in the table on the Rulespage.

Create a policy using Google Cloud CLI

This section outlines the gcloud CLI commands available for artifact guard and how to use them.

Google Cloud CLI prerequisites

• Ensure your gcloud CLI version is 559.0.0 or higher.
• Set your project as the config project.

To do this, run the following gcloud CLI commands:

   
gcloud  
components  
update  
--version = 
 559 
.0.0  
gcloud  
config  
 set 
  
project  
 PROJECT_ID 
 

Google Cloud CLI commands

gcloud  
alpha  
scc  
artifact-guard  
policies  
create  
 \ 
  
 ( 
 POLICY 
  
--location = 
 LOCATION 
  
 ( 
--organization = 
 ORGANIZATION_ID 
  
 | 
  
--project = 
 PROJECT_NUMBER 
 )) 
  
 \ 
  
--policy-file-path = 
 PATH_TO_FILE 

gcloud  
alpha  
scc  
artifact-guard  
policies  
describe  
 \ 
  
 ( 
 POLICY 
  
--location = 
 LOCATION 
  
 ( 
--organization = 
 ORGANIZATION_ID 
  
 | 
  
--project = 
 PROJECT_NUMBER 
 )) 

gcloud  
alpha  
scc  
artifact-guard  
policies  
list  
 PARENT 

gcloud  
alpha  
scc  
artifact-guard  
policies  
delete  
 \ 
  
 ( 
 POLICY 
  
--location = 
 LOCATION 
  
 ( 
--organization = 
 ORGANIZATION_ID 
  
 | 
  
--project = 
 PROJECT_NUMBER 
 )) 
  
 \ 
  
 [ 
--etag = 
 ETAG 
 ] 

gcloud  
alpha  
scc  
artifact-guard  
policies  
update  
 \ 
  
 ( 
 POLICY 
  
--location = 
 LOCATION 
  
 ( 
--organization = 
 ORGANIZATION_ID 
  
 | 
  
--project = 
 PROJECT_NUMBER 
 )) 
  
 \ 
  
--policy-file-path = 
 PATH_TO_FILE 
  
 [ 
--allow-missing ] 
  
 \ 
  
 [ 
--update-mask = 
 UPDATE_MASK 
 ] 

YAML file

A YAML file for a artifact guard policy definition must follow this template:

   
 displayName 
 : 
  
< Human readable display name for the policy 
>  
 description 
 : 
  
< Description of the policy 
>  
 vulnerabilityPolicy 
 : 
  
 # (at least one of these rules must be defined) 
  
 exemptedCves 
 : 
  
 - 
  
 id 
 : 
  
< cve-id-1 
>  
 gracePeriodExpirationTime 
 : 
  
< optional-grace-period-expiration-time 
>  
 - 
  
 id 
 : 
  
< cve-id-2 
>  
 gracePeriodExpirationTime 
 : 
  
< optional-grace-period-expiration-time 
>  
 maxAllowedSeverity 
 : 
  
< The maximum severity allowed in the detected 
  
 vulnerabilities. The severity values can be LOW, MEDIUM, HIGH, CRITICAL 
>  
 maximumAllowedVulnerabilities 
 : 
  
< The maximum number of vulnerabilities that 
  
 can be detected 
>  
 excludeUnfixable 
 : 
  
< Whether to exclude the vulnerabilities without an 
  
 available fix from the purview of the policy evaluation 
>  
 restrictedCves 
 : 
  
 - 
  
< restricted-cve-id-1 
>  
 - 
  
< restricted-cve-id-2 
>  
 allowedPackages 
 : 
  
 - 
  
 name 
 : 
  
< allowed_package_name_1 
>  
 version 
 : 
  
< optional_version_of_allowed_package_1. If unspecified, all the 
  
 versions of the package are allowed 
>  
 - 
  
 name 
 : 
  
< allowed_package_name_2 
>  
 version 
 : 
  
< optional_version_of_allowed_package_2 
>  
 restrictedPackages 
 : 
  
 - 
  
 name 
 : 
  
< restricted_package_name_1 
>  
 version 
 : 
  
< optional_version_of_restricted_package_1. If unspecified, all 
  
 the versions of the package are restricted 
>  
 - 
  
 name 
 : 
  
< restricted_package_name_2 
>  
 version 
 : 
  
< optional_version_of_restricted_package_2 
>  
 scope 
 : 
  
 pipeline 
 : 
  
 connectorIds 
 : 
  
 - 
  
< connector_id_1 
>  
 - 
  
< connector_id_2 
>  
 enforcementAction 
 : 
  
< action to take in case the policy evaluation fails. 
  
 The supported values are AUDIT_ONLY or BLOCK_BUILD 
>  
 registry 
 : 
  
 projectIds 
 : 
  
 - 
  
< project_id_1 
>  
 garRepositoryNamePatterns 
 : 
  
 - 
  
< repository_name_pattern_1 
>  
 imageNamePatterns 
 : 
  
 - 
  
< image_name_pattern_1 
>  
 enforcementAction 
 : 
  
< AUDIT_ONLY or ADMISSION_CONTROL 
>  
 admissionControl 
 : 
  
 deploymentProjectIds 
 : 
  
 - 
  
< project_id_1 
>  
 gkeClusterNames 
 : 
  
 - 
  
< cluster_name_1 
>  
 dryRun 
 : 
  
< bool 
>  
 overrideBinauthzPolicy 
 : 
  
< bool 
>  
 runtime 
 : 
  
 deploymentProjectIds 
 : 
  
 - 
  
< project_id_1 
>  
 gkeClusterNames 
 : 
  
 - 
  
< cluster_name_1 
>  
 dryRun 
 : 
  
< bool 
>  
 overrideBinauthzPolicy 
 : 
  
< bool 
>  
 enforcementAction 
 : 
  
< AUDIT_ONLY or BLOCK_DEPLOYMENT 
>  
 enablementState 
 : 
  
< The enablement state of the policy. The supported values are 
  
 ACTIVE, INACTIVE 
> 

The following is a sample artifact guard policy file:

   
 displayName 
 : 
  
 'A 
  
 sample 
  
 policy' 
  
 description 
 : 
  
 Vulnerability Policy 
  
 vulnerabilityPolicy 
 : 
  
 exemptedCves 
 : 
  
 - 
  
 id 
 : 
  
 CVE-2022-40897 
  
 gracePeriodExpirationTime 
 : 
  
 '2026-09-10T18:58:08Z' 
  
 - 
  
 id 
 : 
  
 CVE-2024-6345 
  
 maxAllowedSeverity 
 : 
  
 MEDIUM 
  
 maximumAllowedVulnerabilities 
 : 
  
 5 
  
 excludeUnfixable 
 : 
  
 true 
  
 restrictedCves 
 : 
  
 - 
  
 CVE-2013-4392 
  
 - 
  
 CVE-2024-4143 
  
 allowedPackages 
 : 
  
 - 
  
 name 
 : 
  
 systemd 
  
 version 
 : 
  
 '257.7' 
  
 - 
  
 name 
 : 
  
 util-linux 
  
 restrictedPackages 
 : 
  
 - 
  
 name 
 : 
  
 ncurses 
  
 version 
 : 
  
 6.5+20250216 
  
 - 
  
 name 
 : 
  
 setuptools 
  
 scope 
 : 
  
 pipeline 
 : 
  
 connectorIds 
 : 
  
 - 
  
 organizations/123/locations/global/connectors/demoConnector 
  
 enforcementAction 
 : 
  
 BLOCK_BUILD 
  
 registry 
 : 
  
 projectIds 
 : 
  
 - 
  
 projects/my-registry-project-id 
  
 - 
  
 projects/another-registry-project 
  
 garRepositoryNamePatterns 
 : 
  
 - 
  
 us-west1-docker.pkg.dev/my-registry-project-id/my-repo 
  
 - 
  
 gcr.io/team-a/internal-artifacts 
  
 imageNamePatterns 
 : 
  
 - 
  
 my-repo/service-a:.* 
  
 - 
  
 my-repo/service-b:v1\..* 
  
 enforcementAction 
 : 
  
 ADMISSION_CONTROL 
  
 admissionControl 
 : 
  
 deploymentProjectIds 
 : 
  
 - 
  
 projects/my-deployment-project 
  
 gkeClusterNames 
 : 
  
 - 
  
 //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-a 
  
 - 
  
 //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-b 
  
 dryRun 
 : 
  
 true 
  
 overrideBinauthzPolicy 
 : 
  
 true 
  
 runtime 
 : 
  
 deploymentProjectIds 
 : 
  
 - 
  
 projects/my-deployment-project 
  
 gkeClusterNames 
 : 
  
 - 
  
 //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-a 
  
 - 
  
 //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-b 
  
 dryRun 
 : 
  
 false 
  
 overrideBinauthzPolicy 
 : 
  
 false 
  
 enforcementAction 
 : 
  
 BLOCK_DEPLOYMENT 
  
 enablementState 
 : 
  
 ACTIVE 
 

Performance and limitations

• Maximum policies per parent resource: A parent resource (organization or project) can define a maximum of 1,000 policies. This includes all types of security policies configured within artifact guard.
• Maximum vulnerability policies per parent resource: Within the overall policy limit, there's a limit on the number of policies focused on vulnerability findings. A parent resource (organization or project) can have a maximum of 500 policies that target vulnerabilities.
• Maximum policies per pipeline: For each individual CI/CD pipeline where artifact guard policies are integrated for build time enforcement, a maximum of 100 policies is allowed.
• Maximum updates per policy per week: For each policy, a maximum of 100 updates can be made every week.
• Maximum pipeline connectors per policy: Each policy can have a maximum of 100 pipeline connectors associated with it.
• Maximum Exempted and Restricted CVEs per policy: Each policy can exempt and restrict a maximum of 100 CVEs.
• Maximum Allowed and Restricted packages per policy: Each policy can allow and restrict a maximum of 100 packages.

For additional constraints, see Troubleshooting .

Troubleshooting

This section outlines artifact guard policy fields and common errors with their resolutions.

Policy validation

Artifact guard validates policy definitions when you create or update policies. If validation fails, artifact guard rejects the request and provides a detailed error message.

General policy fields

Vulnerability Policy

Policy scope

Pipeline scope

Registry scope

Runtime scope

The runtime scope allows artifact guard to monitor container images actively running within your GKE environment. When a policy is applied to this scope, Security Command Center vulnerability findings are automatically enhanced with policy metadata for images deployed in the specified projects or clusters.

If a container image running in a monitored GKE cluster violates a policy, the ArtifactGuardPolicies metadata is added to the Security Command Center vulnerability finding message, as follows:

  // 
  
 Added 
  
 to 
  
 the 
  
 SCC 
  
 'message Finding' 
 ArtifactGuardPolicies 
  
 artifact_guard_policies 
  
 = 
  
 X 
 ; 
 message 
  
 ArtifactGuardPolicies 
  
 { 
  
 string 
  
 resource_id 
  
 = 
  
 1 
 ; 
  
 // 
  
 e 
 . 
 g 
 . 
 , 
  
 // 
 us 
 - 
 docker 
 . 
 pkg 
 . 
 dev 
 / 
 google 
 - 
 samples 
 / 
 containers 
 / 
 gke 
 / 
 security 
 /... 
  
 repeated 
  
 Policy 
  
 failing_policies 
  
 = 
  
 2 
 ; 
 } 
 message 
  
 Policy 
  
 { 
  
 enum 
  
 Type 
  
 { 
  
 TYPE_UNSPECIFIED 
  
 = 
  
 0 
 ; 
  
 VULNERABILITY 
  
 = 
  
 1 
 ; 
  
 } 
  
 Type 
  
 type 
  
 = 
  
 1 
 ; 
  
 string 
  
 policy_id 
  
 = 
  
 2 
 ; 
  
 // 
  
 e 
 . 
 g 
 . 
 , 
  
 organizations 
 / 
 3392779 
 / 
 locations 
 / 
 global 
 / 
 policies 
 / 
 prod 
 - 
 policy 
  
 string 
  
 failure_reason 
  
 = 
  
 3 
 ; 
  
 // 
  
 e 
 . 
 g 
 . 
 , 
  
 severity 
 = 
 HIGH 
  
 AND 
  
 max_vuln_count 
 = 
 2 
 } 
 

Enforcement action

For BLOCK_BUILD and BLOCK_DEPLOYMENT actions, the policy evaluation returns a recommended enforcement action. However, you must configure the actual enforcement in the pipeline configuration using this recommendation.

Policy deletion

Active policies cannot be deleted and result in a FAILED_PRECONDITION error. To delete a policy, first set its state to Inactive .

Common errors

The following table outlines some common errors and how to resolve them.

Common operational issues

Besides policy content validation failures, issues can arise with the underlying Google Cloud control plane. These issues can affect API requests, long-running operations, and resource states, typically appearing as specific error codes or unusual behavior.