Security posture YAML file

This page provides an overview of the key-value pairs in the posture.yaml file that you create to define the policies for your security posture. To create a posture YAML file and deploy it in your environment, see Manage a security posture.

Posture YAML file structure

Postures are YAML files that have the following structure:

name: posture_name
state: posture_state
description: posture_description
policy_sets:
- policy_set_id: policy_set_ID
  - description: policy_set_description
  policies:
  - policy_id: policy_id
    compliance_standards:
      - standard: policy_standards
      - control: policy_control
          - description: policy_description
    # Definition for a organization policy
    constraint:
      org_policy_constraint:
        canned_constraint_id: constraint_ID
        policy_rules:
          - org_policy_kind: org_policy_kind_value
          - condition:
              expression: org_policy_expression
              title: org_policy_title
              description: org_policy_description
              location: org_policy_location
    # Definition for a custom organization policy constraint
    constraint:
      org_policy_constraint_custom:
        custom_constraint:
          name: custom_org_constraint_name
          resource_types: custom_org_resource_type
          method_types: custom_org_method_type
          condition: custom_org_condition
          action_type: custom_org_action_type
          display_name: custom_org_constraint_display_name
          description: custom_org_constraint_description
        policy_rules:
          - org_policy_kind: org_policy_kind_value
          - condition:
              expression: org_policy_expression
              title: org_policy_title
              description: org_policy_description
              location: org_policy_location
      # Definition for a Security Health Analytics detector
      constraint:
        security_health_analytics_module:
            module_name: sha_detector_name
            module_enablement_state: sha_detector_enabled
      # Definition for a custom Security Health Analytics detector
      constraint:
        security_health_analytics_custom_module:
            display_name: sha_custom_detector_name
            config:
                predicate:
                    expression: sha_custom_detector_expression
                    title: sha_custom_detector_predicate_title
                    description: sha_custom_detector_predicate_description
                    location: sha_custom_detector_predicate_location
                - custom_output:
                    - property:
                        name: sha_custom_detector_output_name
                        value_expression:
                            expression: sha_custom_detector_output_expression
                            title: sha_custom_detector_output_title
                            description: sha_custom_detector_output_description
                            location: sha_custom_detector_output_location
                resource_selector:
                    - resource_types: sha_custom_detector_resource
            severity: sha_custom_severity_level
              description: sha_custom_detector_description
              recommendation: sha_custom_detector_recommendation
            module_enablement_state: sha_detector_enabled

Description of key-value pairs

The following table provides a description of the key-value pairs in the posture.yaml file.

Key-value pair Description
name: posture_name The posture name, starting with a letter. This value is optional because you specify the posture name when you run the gcloud scc postures create command.
state: posture_state An ENUM that you can set to ACTIVE, DRAFT, or DEPRECATED. For more information about posture states, see Change the state of a posture.
description: posture_description A description of the policy. This value is optional.
policy_set_id: policy_set_ID A unique identifier for the policy set within the posture file. A posture file can include multiple policy sets.
description: policy_set_description A description of the policy set. This value is optional.
policy_id: policy_id A unique identifier for the policy within the policy set. A policy set can include multiple policies.
standard: policy_compliance_standard The name of the compliance standard that this policy supports.
control: policy_compliance_control The particular controls within the compliance standard that this policy supports.
description: policy_compliance_description A description of the compliance standard that this policy supports.
canned_constraint_id: constraint_ID The name of the organization policy constraint. For example, cloudbuild.allowedWorkerPools. Don't include the constraints/ prefix in constraint_ID.
org_policy_kind Values for list organization policies are allow_all, deny_all, allowed_values, denied_values. Value for boolean organization policies is enforce.
org_policy_kind_value Values for the allow_all, deny_all, enforce kind are true or false. The value for allowed_values and denied_values kinds is a list of allowed or denied values respectively.
condition: A condition which determines whether this rule is used in the evaluation of the policy. When set, the expression field in the Expr must include from 1 to 10 subexpressions, joined by the || or && operators. Each subexpression must be of the form resource.matchTag('ORG_ID/tag_key_short_name, 'tag_value_short_name') or resource.matchTagId('tagKeys/key_id', 'tagValues/value_id') where key_name and value_name are the resource names for Label Keys and Values. These names are available from the tag manager service. An example expression is: resource.matchTag('123456789/environment, 'prod') or resource.matchTagId('tagKeys/123', 'tagValues/456').
expression: org_policy_expression The textual representation of an expression in Common Expression Language syntax. This value is optional.
title: org_policy_title The description of the purpose for the expression. This value is optional.
description: org_policy_description The description of the expression. This value is optional.
location: org_policy_location A string that indicates the location of the expression for reporting errors. For example a filename and a position in the file. This value is optional.
name: custom_org_constraint_name The name of the custom constraint, in the format organizations/ORGANIZATION_ID/customConstraints/CONSTRAINT_NAME. For example, organizations/3589215982/customConstraints/custom.disableGkeAutoUpgrade. The CONSTRAINT_NAME cannot be longer than 62 characters. The prefix organizations/{organization_id}/customConstraints/custom is not counted. Defining a custom constraint in the posture file creates a new custom constraint.
resource_types: custom_org_resource_type The fully qualified name of the Google Cloud REST resource that contains the object and field that you want to restrict. There is a maximum of 20 custom constraints per resource type.
method_types: custom_org_method_type The list of RESTful methods for which to enforce the constraint.
condition: custom_org_condition The CEL condition that refers to the supported service resource. This field has a maximum length of 1000 characters.
action_type: custom_org_action_type The action to take if the condition is met.
display_name: custom_org_constraint_display_name A human-friendly name for the constraint. This field has a maximum length of 200 characters.
description: custom_org_constraint_description The description of the constraint to display as an error message when the policy is violated. This field has a maximum length of 2000 characters.
module_name: sha_detector_name The name of a Security Health Analytics detector. For example, BIGQUERY_TABLE_CMEK_DISABLED.
module_enablement_state: sha_detector_enabled Whether the Security Health Analytics detector is enabled. Either ENABLED or DISABLED.
display_name: sha_custom_detector_name The name for the custom module for Security Health Analytics. The name must be between 1 and 128 characters, start with a lowercase letter, and contain alphanumeric characters or underscores only.
expression: sha_custom_detector_expression The CEL expressions that check the properties of the resource types to be scanned.
title: sha_custom_detector_predicate_title The name of the predicate property for the custom module for Security Health Analytics.
description: sha_custom_detector_predicate_description The description of the predicate property for the custom module for Security Health Analytics.
location: sha_custom_detector_predicate_location The location that the predicate property applies to.
name: sha_custom_detector_output_name The name of the custom_output property.
expression: sha_custom_detector_output_expression What expression to return in the output.
title: sha_custom_detector_output_title The title for the output.
description: sha_custom_detector_output_description The description of the output for the custom module for Security Health Analytics.
location: sha_custom_detector_output_location The location that the output applies to.
resource_types: sha_custom_detector_resource The resource types that the custom module scans.
severity: sha_custom_severity_level The severity for the findings that are created by this module.
description: sha_custom_detector_description The vulnerability or misconfiguration that the custom module detects.
recommendation: sha_custom_detector_recommendation A description of how to fix the detected issue.

Sample posture.yaml

createTime: '2024-04-01T15:27:27.188366349Z'
etag: h5ulCqzUqOcaIjKjxHFrOrrZpmneG8A0K1mdO-uHsLM
name: organizations/123/locations/global/postures/mixedcasposture
policySets:
- policies:
  - constraint:
      securityHealthAnalyticsModule:
        moduleEnablementState: ENABLED
        moduleName: BIGQUERY_TABLE_CMEK_DISABLED
    description: enable BIGQUERY_TABLE_CMEK_DISABLED
    policyId: SHA module BIGQUERY_TABLE_CMEK_DISABLED
  - constraint:
      orgPolicyConstraint:
        cannedConstraintId: iam.allowServiceAccountCredentialLifetimeExtension
        policyRules:
        - allowAll: true
        - condition:
            expression: resource.matchTag("123/location", "us-east3")
            title: policy for us-east3
            description: apply policy to us-east3
    policyId: test/123/policies/iam.allowServiceAccountCredentialLifetimeExtension
  - constraint:
      orgPolicyConstraintCustom:
        customConstraint:
          actionType: ALLOW
          condition: resource.management.autoUpgrade == false
          description: Only allow GKE NodePool resource to be created or updated if
            AutoUpgrade is not enabled where this custom constraint is enforced.
          displayName: Disable GKE auto upgrade
          methodTypes:
          - CREATE
          name: organizations/123/customConstraints/custom.gke123
          resourceTypes:
          - container.googleapis.com/NodePool
        policyRules:
        - enforce: true
    policyId: orgPolicycustomconstraint
  - constraint:
      securityHealthAnalyticsModule:
        moduleEnablementState: DISABLED
        moduleName: PUBLIC_BUCKET_ACL
    description: PUBLIC_BUCKET_ACL disabled
    policyId: sha module PUBLIC_BUCKET_ACL
  - constraint:
      securityHealthAnalyticsCustomModule:
        config:
          customOutput: {}
          description: Test Custom Module
          predicate:
            expression: resource.rotationPeriod > duration('2592000s')
          recommendation: Testing custom modules
          resourceSelector:
            resourceTypes:
            - cloudkms.googleapis.com/CryptoKey
          severity: CRITICAL
        displayName: customSHA
        moduleEnablementState: ENABLED
    policyId: sha_custom_module
  - constraint:
      securityHealthAnalyticsCustomModule:
        config:
          customOutput: {}
          description: Test Custom Module
          predicate:
            expression: resource.rotationPeriod > duration('2592000s')
          recommendation: Testing custom modules
          resourceSelector:
            resourceTypes:
            - cloudkms.googleapis.com/CryptoKey
          severity: CRITICAL
        displayName: customSHA2
        moduleEnablementState: ENABLED
    policyId: sha_custom_module_2
  policySetId: PolicySetmix
- policy_set_id: BigQuery detective policy set
  description: SHA module that new customers can automatically enable.
  policies:
  - policy_id: Public dataset
    constraint:
      securityHealthAnalyticsModule:
        moduleEnablementState: ENABLED
        moduleName: PUBLIC_DATASET
state: ACTIVE

Examples

For examples, see the predefined posture templates.

What's next