Skip to content
Switch branches/tags
Go to file
…eti (#402)

Config Validator (and this library) are no longer part of the forseti-security library, since they have broader applicability.
10 contributors

Users who have contributed to this file

@t12g @morgante @gkowalski-google @melinath @kojnp @e-koma @red2k18 @katze120 @briantkennedy @AdrienWalkowiak

Config Validator | Setup & User Guide

Go from setup to proof-of-concept in under 1 hour

Table of Contents


As your business shifts towards an infrastructure-as-code workflow, security and cloud administrators are concerned about misconfigurations that may cause security and governance violations.

Cloud Administrators need to be able to put up guardrails that follow security best practices and help drive the environment towards programmatic security and governance while enabling developers to go fast.

Config Validator allows your administrators to enforce constraints that validate whether deployments can be provisioned while still enabling developers to move quickly within these safe guardrails. Validator accomplishes this through a three key components:

One way to define constraints

Constraints are defined so that they can work across an ecosystem of pre-deployment and monitoring tools. These constraints live in your organization's repository as the source of truth for your security and governance requirements. You can obtain constraints from the Policy Library, or build your own constraint templates.

Pre-deployment check

Check for constraint violations during pre-deployment and provide warnings or halt invalid deployments before they reach production. The pre-deployment logic that Config Validator uses will be built into a number of deployment tools. For details, check out Terraform Validator.

Ongoing monitoring

Frequently scan the platform for constraint violations and send notifications when a violation is found. The monitoring logic that Config Validator uses will be built into a number of monitoring tools. For example, check out How to Use Config Validator with Forseti.

The following guide will walk you through initial setup steps and instructions on how to use Config Validator. By the end, you will have a proof-of-concept to experiment with and to build your foundation upon.

How to set up constraints with Policy Library

Get started with the Policy Library repository

The Policy Library repository contains the following directories:

  • policies
    • constraints: This is initially empty. You should place your constraint files here.
    • templates: This directory contains pre-defined constraint templates.
  • validator: This directory contains the .rego files and their associated unit tests. You do not need to touch this directory unless you intend to modify existing constraint templates or create new ones. Running make build will inline the Rego content in the corresponding constraint template files.

Google provides a sample repository with a set of pre-defined constraint templates. You can duplicate this repository into a private repository. First you should create a new private git repository. For example, if you use GitHub then you can use the GitHub UI. Then follow the steps below to get everything setup.

Note: If you are planning on using the Policy Library Sync feature of Forseti, then you should also add a read-only user to the private repository which will be used by Forseti.

This policy library can also be made public, but it is not recommended. By making your policy library public, it would be allowing others to see what you are and ARE NOT scanning for.

Duplicate Policy Library Repository

To run the following commands, you will need to configure git to connect securely. It is recommended to connect with SSH. Here is a helpful resource for learning about how this works, including steps to set this up for GitHub repositories; other providers offer this feature as well.

export GIT_REPO_ADDR="${YOUR_GITHUB_USERNAME}/policy-library.git"
git clone --bare
cd policy-library.git
git push --mirror ${GIT_REPO_ADDR}
cd ..
rm -rf policy-library.git
git clone ${GIT_REPO_ADDR}

Setup Constraints

Then you need to examine the available constraint templates inside the templates directory. Pick the constraint templates that you wish to use, create constraint YAML files corresponding to those templates, and place them under policies/constraints. Commit the newly created constraint files to your Git repository. For example, assuming you have created a Git repository named "policy-library" under your GitHub account, you can use the following commands to perform the initial commit:

cd policy-library
# Add new constraints...
git add --all
git commit -m "Initial commit of policy library constraints"
git push -u origin master

Pull in latest changes from Public Repository

Periodically you should pull any changes from the public repository, which might contain new templates and Rego files.

git remote add public
git pull public master
git push origin master

Instantiate constraints

The constraint template library only contains templates. Templates specify the constraint logic, and you must create constraints based on those templates in order to enforce them. Constraint parameters are defined as YAML files in the following format:

kind: # place constraint template kind here
  name: # place constraint name here
  severity: # low, medium, or high
    target: [] # put the constraint application target here
    exclude: [] # optional, default is no exclusions
  parameters: # put the parameters defined in constraint template here

The target field is specified in a path-like format. It specifies where in the GCP resources hierarchy the constraint is to be applied. For example:

Target Description
organizations/** All organizations
organizations/123/** Everything in organization 123
organizations/123/folders/** Everything in organization 123 that is under a folder
organizations/123/folders/456 Everything in folder 456 in organization 123
organizations/123/folders/456/projects/789 Everything in project 789 in folder 456 in organization 123

The exclude field follows the same pattern and has precedence over the target field. If a resource is in both, it will be excluded.

The schema of the parameters field is defined in the constraint template, using the OpenAPI V3 schema. This is the same validation schema in Kubernetes's custom resource definition. Every template contains a validation section that looks like the following:

        type: string
        type: array
        items: string

According to the template above, the parameter field in the constraint file should contain a string named mode and a string array named instances. For example:

  mode: allowlist
    - //
    - //

These parameters specify that two VM instances may have external IP addresses. The are exempt from the constraint since they are allowlisted.

Here is a complete example of a sample external IP address constraint file:

kind: GCPExternalIpAccessConstraintV1
  name: forbid-external-ip-allowlist
  severity: high
    target: ["organizations/**"]
    mode: "allowlist"
    - //
    - //

How to use Terraform Validator

Install Terraform Validator

The released binaries are available under the gs://terraform-validator Google Cloud Storage bucket for Linux, Windows, and Mac. They are organized by release, for example:

$ gsutil ls -r "gs://terraform-validator/releases/v*"

To download the binary, you need to install the gsutil tool first. The following command downloads the Linux version of Terraform Validator from vX.X.X release to your local directory:

gsutil cp gs://terraform-validator/releases/vX.X.X/terraform-validator-linux-amd64 .
chmod 755 terraform-validator-linux-amd64

The full list of releases, with release notes, is available on Github.

For local development environments

These instructions assume you have forked a branch and is working locally.

Generate a Terraform plan for the current environment by running:

terraform plan -out=tfplan.tfplan
terraform show -json ./tfplan.tfplan > ./tfplan.json

To validate the Terraform plan based on the constraints specified under your local policy library repository, run:

terraform-validator-linux-amd64 validate tfplan.json --policy-path=${POLICY_PATH}

The policy-path flag is set to the local clone of your Git repository that contains the constraints and templates. This is described in the "How to set up constraints with Policy Library" section.

Terraform Validator also accepts an optional --project flag which is set to the Terraform Google provider project. See the provider docs for more info. If it is not set, Terraform Validator will attempt to parse the provider project from the provider configuration.

If violations are found, a list will be returned of the affected resources and a brief message about the violations:

Found Violations:

Constraint iam_domain_restriction on resource // IAM policy for // contains member from unexpected domain:

Constraint iam_domain_restriction on resource // IAM policy for // contains member from unexpected domain:

If all constraints are validated, the command will return "No violations found." You can then apply a plan locally on a development environment:

terraform apply

For Production Environments

These instructions assume that the developer has merged their local branch back with master. We want to make sure the master deployment into production is validated.

In your continuous integration (CI) tool, you should install Terraform validator. Then you can add a step to any workflow which will validate a Terraform plan and reject it if violations are found. Terraform validator will return a 2 exit code if violations are found or 0 if no violations were found. Therefore, you should configure your CI to only proceed to the next step (for example, terraform apply) or merge if the validator exits successfully.

How to Use Config Validator with Forseti

Deploy Forseti

Follow the documentation on the Forseti Security website to deploy Forseti on GCE. As part of the Terraform configuration, you will need to enable Config Validator. Follow the documentation on the Forseti Security website to set up Config Validator.

Provide Policies to Forseti Server

The recommended practice is to store the Policy Library in a VCS such as GitHub or other git repository. This supports the idea of policy as code and requires work to setup the repository and connect it with Forseti. Once the repository is setup, then Forseti will automatically sync policy updates to the Forseti Server to be used by future scans.

The default behavior of Forseti is to sync the Policy Library from the Forseti Server GCS bucket. This requires little setup, but involves manual work to create the folder and copy the policies to GCS.

Follow the documentation on the Forseti Security website to sync policies from the GCS to the Forseti server, and from Git Repository to the Forseti server.

End to end workflow with sample constraint

In this section, you will apply a constraint that enforces IAM policy member domain restriction using Cloud Shell.

First click on this link to open a new Cloud Shell session. The Cloud Shell session has Terraform pre-installed and the Policy Library repository cloned. Once you have the session open, the next step is to copy over the sample IAM domain restriction constraint:

cp samples/iam_service_accounts_only.yaml policies/constraints

Let's take a look at this constraint:

kind: GCPIAMAllowedPolicyMemberDomainsConstraintV1
  name: service_accounts_only
  severity: high
    target: ["organizations/**"]

It specifies that only members from domain can be present in an IAM policy. To verify that it works, let's attempt to create a project. Create the following Terraform file:

provider "google" {
  version = "~> 1.20"
  project = "your-terraform-provider-project"

resource "random_id" "proj" {
  byte_length = 8

resource "google_project" "sample_project" {
  project_id      = "validator-${random_id.proj.hex}"
  name            = "config validator test project"

resource "google_project_iam_binding" "sample_iam_binding" {
  project = "${google_project.sample_project.project_id}"
  role    = "roles/owner"

  members = [

Make sure to specify your Terraform provider project and email address. Then initialize Terraform and generate a Terraform plan:

terraform init
terraform plan -out=test.tfplan
terraform show -json ./test.tfplan > ./tfplan.json

Since your email address is in the IAM policy binding, the plan should result in a violation. Let's try this out:

gsutil cp gs://terraform-validator/releases/v0.1.0/terraform-validator-linux-amd64 .
chmod 755 terraform-validator-linux-amd64
./terraform-validator-linux-amd64 validate tfplan.json --policy-path=policy-library

The Terraform validator should return a violation. As a test, you can relax the constraint to make the violation go away. Edit the policy-library/policies/constraints/iam_service_accounts_only.yaml file and append your email domain to the domains allowlist:

kind: GCPIAMAllowedPolicyMemberDomainsConstraintV1
  name: service_accounts_only
  severity: high
    target: ["organizations/**"]
      - your-domain-here

Then run Terraform plan and validate the output again:

terraform plan -out=test.tfplan
terraform show -json ./test.tfplan > ./tfplan.json
./terraform-validator-linux-amd64 validate tfplan.json --policy-path=policy-library

The command above should result in no violations found.

Contact Info

Questions or comments? Please contact