Integrate IaC validation with Cloud Build

You can write a build config that instructs Cloud Build to validate the infrastructure as code (IaC) that is part of your build. Validating IaC lets you determine whether your Terraform resource definitions violate the existing organization policies and Security Health Analytics detectors that are applied to your Google Cloud resources.

For more information about IaC validation, see Validate your IaC against your Google Cloud organization's policies.

Before you begin

Complete these tasks to get started with IaC validation using Cloud Build.

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
    • Log Writer
    • Storage Writer
    • Storage Reader

    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 the row that has your email address.

      If your email address isn't in that column, then you do not have any roles.

    4. In the Role column for the row with your email address, check 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 email address.
    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.

Enable the Cloud Build API

  1. Enable the Cloud Build API.

    Enable the API

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

For instructions, see Create your Terraform code.

Validate your IAC in Cloud Build

Add the following tasks to your cloudbuild.yaml file:

  1. Initialize Terraform:

    - name: hashicorp/terraform
  args:
    - '-c'
    - |
      terraform init \
        -backend-config="bucket=STATE_BUCKET" \
        -backend-config="prefix=REPOSITORY_NAME" \
  dir: FOLDER
  id: Terraform Init
  entrypoint: sh

    Replace the following:

    • STATE_BUCKET with the name of the Cloud Storage bucket to store the Terraform state in
    • REPOSITORY_NAME with the repository that hosts your Terraform code.
    • FOLDER with the name of the folder to save the Terraform artifacts to.

  2. Create a plan file:

    - name: hashicorp/terraform
  args:
    - '-c'
    - |
      terraform plan -out tf.plan
  dir: FOLDER
  id: Terraform Plan
  entrypoint: sh

  3. Convert the plan file to JSON format:

    - name: hashicorp/terraform
  args:
    - '-c'
    - |
      terraform show -json tf.plan > plan.json
  dir: FOLDER
  id: Terraform Show
  entrypoint: sh

  4. Create the IaC validation report:

    - name: gcr.io/cloud-builders/gcloud
  args:
    - '-c'
    - |
      gcloud scc iac-validation-reports create \
      organizations/ORGANIZATION_ID/locations/global --tf-plan-file=plan.json \
      --format="json(response.iacValidationReport)" > IaCScanReport_$BUILD_ID.json
  dir: FOLDER
  id: Run IaC scan
  entrypoint: /bin/bash

    Replace ORGANIZATION_ID with your organization's ID.

  5. If you're using Cloud Storage, upload the JSON results file to Cloud Storage:

    - name: gcr.io/cloud-builders/gsutil
  args:
    - cp
    - IaCScanReport_$BUILD_ID.json
    - SCAN_RESULT_FILE_BUCKET
  dir: FOLDER
  id: Upload report file

    Replace SCAN_RESULT_FILE_BUCKET with the Cloud Storage bucket to upload the results file to.

  6. To view the results in SARIF format, complete the following:

    1. Convert the file:

      - name: golang
  args:
    - '-c'
    - |
      go run github.com/google/gcp-scc-iac-validation-utils/SARIFConverter@latest \
        --inputFilePath=IaCScanReport_$BUILD_ID.json
        --outputFilePath=IaCScanReport_$BUILD_ID.sarif.json
  dir: FOLDER
  id: Convert to SARIF format
  entrypoint: /bin/bash

    2. Optional: upload the file to Cloud Storage:

      - name: gcr.io/cloud-builders/gsutil
  args:
    - cp
    - IaCScanReport_$BUILD_ID.sarif.json
    - SCAN_RESULT_FILE_BUCKET
  dir: FOLDER
  id: Upload report file

  7. Validate the results. Complete this step on the results JSON file that you haven't converted to SARIF format:

    - name: golang
  args:
    - '-c'
    - |
      go run github.com/google/gcp-scc-iac-validation-utils/ReportValidator@latest \
        --inputFilePath=IaCScanReport_$BUILD_ID.json --failure_expression=FAILURE_CRITERIA
  dir: FOLDER
  id: Validate results
  entrypoint: /bin/bash

    Replace FAILURE_CRITERIA with the failure threshold criteria that determines when the build fails. The threshold criteria is based on the number of critical, high, medium, and low severity issues that the IaC validation scan encounters. FAILURE_CRITERIA specifies how many issues of each severity are permitted, and also specifies how the issues are aggregated (either AND or OR). For example, if you want the build to fail if it encounters one critical issue or one high severity issue, set the FAILURE_CRITERIA to Critical:1,High:1,Operator:OR. The default is Critical:1,High:1,Medium:1,Low:1,Operator:OR, which means that if the IaC validation scan encounters a violation of any severity, the build must fail.

  8. If the build fails, resolve any violations within your Terraform code.

What's next