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 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.

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