REST Resource: projects.platforms.policies

Resource: PlatformPolicy

A Binary Authorization platform policy for deployments on various platforms.

JSON representation 
{
  "name": string,
  "description": string,
  "updateTime": string,

  // Union field policy_details can be only one of the following:
  "gkePolicy": {
    object (GkePolicy)
  }
  // End of list of possible types for union field policy_details.
}
Fields
name

string

Output only. The relative resource name of the Binary Authorization platform policy, in the form of projects/*/platforms/*/policies/*.
description

string

Optional. A description comment about the policy.
updateTime

string (Timestamp format)

Output only. Time when the policy was last updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
Union field policy_details. Platform-specific policy details. The detail should be consistent with the platform value in the URL. policy_details can be only one of the following:
gkePolicy

object (GkePolicy)

Optional. GKE platform-specific policy.

GkePolicy

A Binary Authorization policy for a GKE cluster. This is one type of policy that can occur as a PlatformPolicy.

JSON representation 
{
  "imageAllowlist": {
    object (ImageAllowlist)
  },
  "checkSets": [
    {
      object (CheckSet)
    }
  ]
}
Fields
imageAllowlist

object (ImageAllowlist)

Optional. Images exempted from this policy. If any of the patterns match the image being evaluated, the rest of the policy will not be evaluated.
checkSets[]

object (CheckSet)

Optional. The CheckSet objects to apply, scoped by namespace or namespace and service account. Exactly one CheckSet will be evaluated for a given Pod (unless the list is empty, in which case the behavior is "always allow"). If multiple CheckSet objects have scopes that match the namespace and service account of the Pod being evaluated, only the CheckSet with the MOST SPECIFIC scope will match.

CheckSet objects must be listed in order of decreasing specificity, i.e. if a scope matches a given service account (which must include the namespace), it must come before a CheckSet with a scope matching just that namespace. This property is enforced by server-side validation. The purpose of this restriction is to ensure that if more than one CheckSet matches a given Pod, the CheckSet that will be evaluated will always be the first in the list to match (because if any other matches, it must be less specific).

If checkSets is empty, the default behavior is to allow all images.

If checkSets is non-empty, the last checkSets entry must always be a CheckSet with no scope set, i.e. a catchall to handle any situation not caught by the preceding CheckSet objects.

ImageAllowlist

Images that are exempted from normal checks based on name pattern only.

JSON representation 
{
  "allowPattern": [
    string
  ]
}
Fields
allowPattern[]

string

Required. A disjunction of image patterns to allow. If any of these patterns match, then the image is considered exempted by this allowlist.

CheckSet

A conjunction of policy checks, scoped to a particular namespace or Kubernetes service account.

In order for evaluation of a CheckSet to return "allowed" for a given image in a given Pod, one of the following conditions must be satisfied:

  • The image is explicitly exempted by an entry in imageAllowlist, OR
  • ALL of the checks evaluate to "allowed".
JSON representation 
{
  "displayName": string,
  "scope": {
    object (Scope)
  },
  "imageAllowlist": {
    object (ImageAllowlist)
  },
  "checks": [
    {
      object (Check)
    }
  ]
}
Fields
displayName

string

Optional. A user-provided name for this CheckSet. This field has no effect on the policy evaluation behavior except to improve readability of messages in evaluation results.
scope

object (Scope)

Optional. The scope to which this CheckSet applies. If unset or an empty string (the default), applies to all namespaces and service accounts. See the Scope message documentation for details on scoping rules.
imageAllowlist

object (ImageAllowlist)

Optional. Images exempted from this CheckSet. If any of the patterns match the image being evaluated, no checks in the CheckSet will be evaluated.
checks[]

object (Check)

Optional. The checks to apply. The ultimate result of evaluating the check set will be "allow" if and only if every check in checks evaluates to "allow".

If checks is empty, the default behavior is "always allow".

Scope

A scope specifier for CheckSet objects.

JSON representation 
{

  // Union field scope can be only one of the following:
  "kubernetesServiceAccount": string,
  "kubernetesNamespace": string
  // End of list of possible types for union field scope.
}
Fields
Union field scope. A specific type of scope specifier. scope can be only one of the following:
kubernetesServiceAccount

string

Optional. Matches a single Kubernetes service account, e.g. my-namespace:my-service-account. kubernetesServiceAccount scope is always more specific than kubernetesNamespace scope for the same namespace.
kubernetesNamespace

string

Optional. Matches all Kubernetes service accounts in the provided namespace, unless a more specific kubernetesServiceAccount scope already matched.

Check

A single check to perform against a Pod. Checks are grouped into CheckSet objects, which are defined by the top-level policy.

JSON representation 
{
  "displayName": string,
  "imageAllowlist": {
    object (ImageAllowlist)
  },

  // Union field check can be only one of the following:
  "alwaysDeny": boolean,
  "simpleSigningAttestationCheck": {
    object (SimpleSigningAttestationCheck)
  },
  "trustedDirectoryCheck": {
    object (TrustedDirectoryCheck)
  },
  "imageFreshnessCheck": {
    object (ImageFreshnessCheck)
  },
  "vulnerabilityCheck": {
    object (VulnerabilityCheck)
  },
  "slsaCheck": {
    object (SlsaCheck)
  },
  "sigstoreSignatureCheck": {
    object (SigstoreSignatureCheck)
  }
  // End of list of possible types for union field check.
}
Fields
displayName

string

Optional. A user-provided name for this check. This field has no effect on the policy evaluation behavior except to improve readability of messages in evaluation results.
imageAllowlist

object (ImageAllowlist)

Optional. Images exempted from this check. If any of the patterns match the image url, the check will not be evaluated.
Union field check. The specific type and configuration of check to perform. check can be only one of the following:
alwaysDeny

boolean

Optional. A special-case check that always denies. Note that this still only applies when the scope of the CheckSet applies and the image isn't exempted by an image allowlist.

This check is primarily useful for testing, or to set the default behavior for all unmatched scopes to "deny".
simpleSigningAttestationCheck

object (SimpleSigningAttestationCheck)

Optional. Require a SimpleSigning-type attestation for every image in the deployment.
trustedDirectoryCheck

object (TrustedDirectoryCheck)

Optional. Require that an image lives in a trusted directory.
imageFreshnessCheck

object (ImageFreshnessCheck)

Optional. Require that an image is no older than a configured expiration time. Image age is determined by its upload time.
vulnerabilityCheck

object (VulnerabilityCheck)

Optional. Require that an image does not contain vulnerabilities that violate the configured rules, such as based on severity levels.
slsaCheck

object (SlsaCheck)

Optional. Require that an image was built by a trusted builder (such as Google Cloud Build), meets requirements for Supply chain Levels for Software Artifacts (SLSA), and was built from a trusted source code repostitory.
sigstoreSignatureCheck

object (SigstoreSignatureCheck)

Optional. Require that an image was signed by Cosign with a trusted key. This check requires that both the image and signature are stored in Artifact Registry.

SimpleSigningAttestationCheck

Require a signed DSSE attestation with type SimpleSigning.

JSON representation 
{
  "attestationAuthenticators": [
    {
      object (AttestationAuthenticator)
    }
  ],
  "containerAnalysisAttestationProjects": [
    string
  ]
}
Fields
attestationAuthenticators[]

object (AttestationAuthenticator)

Required. The authenticators required by this check to verify an attestation. Typically this is one or more PKIX public keys for signature verification.

Only one authenticator needs to consider an attestation verified in order for an attestation to be considered fully authenticated. In otherwords, this list of authenticators is an "OR" of the authenticator results.

At least one authenticator is required.
containerAnalysisAttestationProjects[]

string

Optional. The projects where attestations are stored as Container Analysis Occurrences, in the format projects/[PROJECT_ID]. Only one attestation needs to successfully verify an image for this check to pass, so a single verified attestation found in any of containerAnalysisAttestationProjects is sufficient for the check to pass.

When fetching Occurrences from Container Analysis, only AttestationOccurrence kinds are considered. In the future, additional Occurrence kinds may be added to the query.

Maximum number of containerAnalysisAttestationProjects allowed in each SimpleSigningAttestationCheck is 10.

AttestationAuthenticator

An attestation authenticator that will be used to verify attestations. Typically this is just a set of public keys.

Conceptually, an authenticator can be treated as always returning either "authenticated" or "not authenticated" when presented with a signed attestation (almost always assumed to be a DSSE attestation). The details of how an authenticator makes this decision are specific to the type of 'authenticator' that this message wraps.

JSON representation 
{
  "displayName": string,

  // Union field authenticator can be only one of the following:
  "pkixPublicKeySet": {
    object (PkixPublicKeySet)
  }
  // End of list of possible types for union field authenticator.
}
Fields
displayName

string

Optional. A user-provided name for this AttestationAuthenticator. This field has no effect on the policy evaluation behavior except to improve readability of messages in evaluation results.
Union field authenticator. The specific type of authentication configured by this authenticator. authenticator can be only one of the following:
pkixPublicKeySet

object (PkixPublicKeySet)

Optional. A set of raw PKIX SubjectPublicKeyInfo format public keys. If any public key in the set validates the attestation signature, then the signature is considered authenticated (i.e. any one key is sufficient to authenticate).

PkixPublicKeySet

A bundle of PKIX public keys, used to authenticate attestation signatures.

Generally, a signature is considered to be authenticated by a PkixPublicKeySet if any of the public keys verify it (i.e. it is an "OR" of the keys).

JSON representation 
{
  "pkixPublicKeys": [
    {
      object (PkixPublicKey)
    }
  ]
}
Fields
pkixPublicKeys[]

object (PkixPublicKey)

Required. pkixPublicKeys must have at least one entry.

TrustedDirectoryCheck

A trusted directory check, which rejects images that do not come from the set of user-configured trusted directories.

JSON representation 
{
  "trustedDirPatterns": [
    string
  ]
}
Fields
trustedDirPatterns[]

string

Required. List of trusted directory patterns. A pattern is in the form "registry/path/to/directory". The registry domain part is defined as two or more dot-separated words, e.g., us.pkg.dev, or gcr.io. Additionally, * can be used in three ways as wildcards: 1. leading * to match varying prefixes in registry subdomain (useful for location prefixes); 2. trailing * after registry/ to match varying endings; 3. trailing ** after registry/ to match "/" as well. For example: -- gcr.io/my-project/my-repo is valid to match a single directory -- *-docker.pkg.dev/my-project/my-repo or *.gcr.io/my-project are valid to match varying prefixes -- gcr.io/my-project/* will match all direct directories in my-project -- gcr.io/my-project/** would match all directories in my-project -- gcr.i* is not allowed since the registry is not completely specified -- sub*domain.gcr.io/nginx is not valid because only leading * or trailing * are allowed. -- *pkg.dev/my-project/my-repo is not valid because leading * can only match subdomain -- **-docker.pkg.dev is not valid because one leading * is allowed, and that it cannot match /

ImageFreshnessCheck

An image freshness check, which rejects images that were uploaded before the set number of days ago to the supported repositories.

JSON representation 
{
  "maxUploadAgeDays": integer
}
Fields
maxUploadAgeDays

integer

Required. The max number of days that is allowed since the image was uploaded. Must be greater than zero.

VulnerabilityCheck

An image vulnerability check, which rejects images that violate the configured vulnerability rules.

JSON representation 
{
  "allowedCves": [
    string
  ],
  "blockedCves": [
    string
  ],
  "maximumUnfixableSeverity": enum (MaximumAllowedSeverity),
  "maximumFixableSeverity": enum (MaximumAllowedSeverity),
  "containerAnalysisVulnerabilityProjects": [
    string
  ]
}
Fields
allowedCves[]

string

Optional. A list of specific CVEs to ignore even if the vulnerability level violates maximumUnfixableSeverity or maximumFixableSeverity. CVEs are listed in the format of Container Analysis note id. For example: - CVE-2021-20305 - CVE-2020-10543 The CVEs are applicable regardless of note provider project, e.g., an entry of CVE-2021-20305 will allow vulnerabilities with a note name of either projects/goog-vulnz/notes/CVE-2021-20305 or projects/CUSTOM-PROJECT/notes/CVE-2021-20305.
blockedCves[]

string

Optional. A list of specific CVEs to always raise warnings about even if the vulnerability level meets maximumUnfixableSeverity or maximumFixableSeverity. CVEs are listed in the format of Container Analysis note id. For example: - CVE-2021-20305 - CVE-2020-10543 The CVEs are applicable regardless of note provider project, e.g., an entry of CVE-2021-20305 will block vulnerabilities with a note name of either projects/goog-vulnz/notes/CVE-2021-20305 or projects/CUSTOM-PROJECT/notes/CVE-2021-20305.
maximumUnfixableSeverity

enum (MaximumAllowedSeverity)

Required. The threshold for severity for which a fix isn't currently available. This field is required and must be set.
maximumFixableSeverity

enum (MaximumAllowedSeverity)

Required. The threshold for severity for which a fix is currently available. This field is required and must be set.
containerAnalysisVulnerabilityProjects[]

string

Optional. The projects where vulnerabilities are stored as Container Analysis Occurrences. Each project is expressed in the resource format of projects/[PROJECT_ID], e.g., projects/my-gcp-project. An attempt will be made for each project to fetch vulnerabilities, and all valid vulnerabilities will be used to check against the vulnerability policy. If no valid scan is found in all projects configured here, an error will be returned for the check.

Maximum number of containerAnalysisVulnerabilityProjects allowed in each VulnerabilityCheck is 10.

MaximumAllowedSeverity

Maximum allowed severity level which is compared to an image's effective severity defined by Container Analysis: https://cloud.google.com/container-analysis/docs/container-scanning-overview#sources.

Enums
MAXIMUM_ALLOWED_SEVERITY_UNSPECIFIED Not specified.
BLOCK_ALL Block any vulnerability.
MINIMAL Allow only minimal severity.
LOW Allow only low severity and lower.
MEDIUM Allow medium severity and lower.
HIGH Allow high severity and lower.
CRITICAL Allow critical severity and lower.
ALLOW_ALL Allow all severity, even vulnerability with unspecified severity.

SlsaCheck

A SLSA provenance attestation check, which ensures that images are built by a trusted builder using source code from its trusted repositories only.

JSON representation 
{
  "rules": [
    {
      object (VerificationRule)
    }
  ]
}
Fields
rules[]

object (VerificationRule)

Specifies a list of verification rules for the SLSA attestations. An image is considered compliant with the SlsaCheck if any of the rules are satisfied.

VerificationRule

Specifies verification rules for evaluating the SLSA attestations including: which builders to trust, where to fetch the SLSA attestations generated by those builders, and other builder-specific evaluation rules such as which source repositories are trusted. An image is considered verified by the rule if any of the fetched SLSA attestations is verified.

JSON representation 
{
  "trustedBuilder": enum (TrustedBuilder),
  "attestationSource": {
    object (AttestationSource)
  },
  "configBasedBuildRequired": boolean,
  "trustedSourceRepoPatterns": [
    string
  ]
}
Fields
trustedBuilder

enum (TrustedBuilder)

Each verification rule is used for evaluation against provenances generated by a specific builder (group). For some of the builders, such as the Google Cloud Build, users don't need to explicitly specify their roots of trust in the policy since the evaluation service can automatically fetch them based on the builder (group).
attestationSource

object (AttestationSource)

Specifies where to fetch the provenances attestations generated by the builder (group).
configBasedBuildRequired

boolean

If true, require the image to be built from a top-level configuration. trustedSourceRepoPatterns specifies the repositories containing this configuration.
trustedSourceRepoPatterns[]

string

List of trusted source code repository URL patterns. These patterns match the full repository URL without its scheme (e.g. https://). The patterns must not include schemes. For example, the pattern source.cloud.google.com/my-project/my-repo-name matches the following URLs: - source.cloud.google.com/my-project/my-repo-name - git+ssh://source.cloud.google.com/my-project/my-repo-name - https://source.cloud.google.com/my-project/my-repo-name A pattern matches a URL either exactly or with * wildcards. * can be used in only two ways: 1. trailing * after hosturi/ to match varying endings; 2. trailing ** after hosturi/ to match / as well. * and ** can only be used as wildcards and can only occur at the end of the pattern after a /. (So it's not possible to match a URL that contains literal *.) For example: - github.com/my-project/my-repo is valid to match a single repo - github.com/my-project/* will match all direct repos in my-project - github.com/** matches all repos in GitHub

TrustedBuilder

Supported builders (group).

Enums
BUILDER_UNSPECIFIED Should never happen.
GOOGLE_CLOUD_BUILD The whole Google Cloud Build (GCB) builder group, including all GCB builder types.

AttestationSource

Specifies the locations for fetching the provenance attestations.

JSON representation 
{
  "containerAnalysisAttestationProjects": [
    string
  ]
}
Fields
containerAnalysisAttestationProjects[]

string

The IDs of the Google Cloud projects that store the SLSA attestations as Container Analysis Occurrences, in the format projects/[PROJECT_ID].

Maximum number of containerAnalysisAttestationProjects allowed in each AttestationSource is 10.

SigstoreSignatureCheck

A Sigstore signature check, which verifies the Sigstore signature associated with an image.

JSON representation 
{
  "sigstoreAuthorities": [
    {
      object (SigstoreAuthority)
    }
  ]
}
Fields
sigstoreAuthorities[]

object (SigstoreAuthority)

Required. The authorities required by this check to verify the signature. A signature only needs to be verified by one authority to pass the check.

SigstoreAuthority

A Sigstore authority, used to verify signatures that are created by Sigstore.

An authority is analogous to an attestation authenticator, verifying that a signature is valid or invalid.

JSON representation 
{
  "displayName": string,

  // Union field authority can be only one of the following:
  "publicKeySet": {
    object (SigstorePublicKeySet)
  }
  // End of list of possible types for union field authority.
}
Fields
displayName

string

Optional. A user-provided name for this SigstoreAuthority. This field has no effect on the policy evaluation behavior except to improve readability of messages in evaluation results.
Union field authority. The specific authority type. authority can be only one of the following:
publicKeySet

object (SigstorePublicKeySet)

Required. A simple set of public keys. A signature is considered valid if any keys in the set validate the signature.

SigstorePublicKeySet

A bundle of Sigstore public keys, used to verify Sigstore signatures.

A signature is authenticated by a SigstorePublicKeySet if any of the keys verify it.

JSON representation 
{
  "publicKeys": [
    {
      object (SigstorePublicKey)
    }
  ]
}
Fields
publicKeys[]

object (SigstorePublicKey)

Required. publicKeys must have at least one entry.

SigstorePublicKey

A Sigstore public key.

SigstorePublicKey is the public key material used to authenticate Sigstore signatures.

JSON representation 
{
  "publicKeyPem": string
}
Fields
publicKeyPem

string

The public key material in PEM format.

Methods

create

 Creates a platform policy, and returns a copy of it.

delete

 Deletes a platform policy.

get

 Gets a platform policy.

list

 Lists platform policies owned by a project in the specified platform.

replacePlatformPolicy

 Replaces a platform policy.