Configure artifact guard policies

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 policy or Create policy.

2. Enter a Policy ID and Description for 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 Medium includes all Medium, High, and Critical vulnerabilities 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 High or 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 Rules page.

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: