Validate your IaC against your Google Cloud organization's policies

This document describes how to validate your infrastructure as code (IaC) against the organization policies and Security Health Analytics detectors that you have defined in your Google Cloud organization. IaC lets you create and manage your cloud resources using languages such as Terraform so that you can deploy the resources using a development workflow. The IaC validation feature supports organization policies and Security Health Analytics detectors only.

Validating your IaC lets you determine whether your new or modified resource definitions violate the existing policies that are applied to your Google Cloud resources (for example, cluster, bucket, or instance). You can define these policies using security postures, but the IaC validation feature analyzes your code against all the policies in your Google Cloud organization. IaC validation helps your developers identify and fix any security issues in the IaC configuration of assets or resources before they are applied to your Google Cloud environment.

The IaC validation feature supports Terraform plan files. You can validate your Terraform plan using Google Cloud CLI, or you can integrate the validation process into your Cloud Build, Jenkins, or GitHub Actions developer workflow.

Before you begin

Complete these tasks to get started with IaC validation.

Activate the Security Command Center Premium tier or Enterprise tier

Verify that the Security Command Center Premium tier or Enterprise tier is activated at the organization level.

Activating Security Command Center enables the securityposture.googleapis.com and securitycentermanagement.googleapis.com APIs.

Set up permissions

  1. Make sure that you have the following role or roles on the organization: Security Posture Shift-Left Validator

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the organization.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role colunn to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the organization.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

    5. In the Select a role list, select a role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

For more information about IaC validation permissions, see IAM for organization-level activations.

Set up Google Cloud CLI

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

To set up the gcloud CLI to use service account impersonation to authenticate to Google APIs, rather than your user credentials, run the following command: 

gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

For more information, see Service account impersonation.

Define your policies

Define your organization policies and Security Health Analytics detectors. To define these policies using a security posture, complete the tasks in Create and deploy a posture.

Create your Terraform code

Use your developer workflows and tools to create a Terraform file that includes the Google Cloud assets that you want to create or modify.

Consider the following:

  • Populate the parent attribute (the project, folder, or organization) of every resource or asset in the Terraform configuration.
  • Modify assets and policies separately. The API doesn't support validation of Terraform plan files which modify both assets and policies at the same time.
  • Use supported asset types and policies only. For a list of supported asset types and policies, see Supported asset types and policies for IaC validation.
  • Review the limitations for IaC validation.
  • Don't include sensitive information such as passwords or other personally identifiable information in your Terraform plan file. If the validation feature encounters fields marked as sensitive in the resource changes, the fields are removed.

After you create your Terraform code, you can run the IaC validation report. You can use the gcloud CLI, Cloud Build, Jenkins, or GitHub Actions.

Use Google Cloud CLI to create an IaC validation report

To create an IaC validation report, complete the following:

  1. In gcloud CLI, run terraform init.

    Verify that you're running Terraform provider version v5.5 or later. If required, upgrade to the latest Google provider version:

    terraform init -upgrade

  2. Convert the Terraform plan file to JSON format:

    terraform plan -out TF_PLAN_FILENAME
terraform show -json TF_PLAN_FILENAME > TF_PLAN_JSON_FILENAME.json

    Replace the following:

    • TF_PLAN_FILENAME: The name for the Terraform plan file.
    • TF_PLAN_JSON_FILENAME: The name of the file that will contain the Terraform plan in JSON format.

  3. Create the IaC validation report:

    gcloud scc iac-validation-reports create PARENT \
  --tf-plan-file=TF_PLAN_JSON_FILENAME.json

    Replace the following:

    • PARENT: The Google Cloud organization in which to create the IaC Validation report. The format is organizations/ORGANIZATION_ID/locations/LOCATION. LOCATION is global.
    • TF_PLAN_JSON_FILENAME: The path to the JSON file that contains the IaC plan that you want to validate.

    For example, to create an IaC validation report under the organizations/3589215982/locations/global organization with an IaC plan included in planFile.json, run the following command:

    gcloud scc iac-validation-reports create organizations/3589215982/locations/global --tf-plan-file=planFile.json

    This command returns the operation details for creating the IAC validation report. To get information about the operation, see View information about a posture deployment operation.

What's next