Skip to content
A Terraform module for installing Forseti on GCP
HCL Ruby Shell Smarty Other
Branch: master
Clone or download
hshin-g Add gcloud command to set project in Cloudshell tutorial (#316)
* Add set project gcloud command

* add project ID

* update gcloud command

* fix syntax

* Update example version

* Change version number
Latest commit 045c098 Oct 15, 2019

README.md

Terraform Forseti Install

The Terraform Forseti module can be used to quickly install and configure Forseti in a fresh cloud project.

Compatibility

This module is meant for use with Terraform 0.12. If you haven't upgraded and need a Terraform 0.11.x-compatible version of this module, the last released version intended for Terraform 0.11.x is 2.3.0.

Usage

Example setups are included in the examples, but you can can also get started using a Cloud Shell Tutorial.

Open in Cloud Shell

Simple usage of the module within your own main.tf file is as follows:

    module "forseti" {
      source  = "terraform-google-modules/forseti/google"
      version = "~> 3.0"

      gsuite_admin_email = "superadmin@yourdomain.com"
      domain             = "yourdomain.com"
      project_id         = "my-forseti-project"
      org_id             = "2313934234"
    }

The default VM size and Cloud SQL size have been increased to n1-standard-8 and db-n1-standard-4 to account for larger GCP environments.

To size the instances up or down, update the following variables in your main.tf file:

server_type = {VM SIZE}

cloudsql_type = {CLOUD SQL SIZE}

Please refer to the VM sizing guide and the Cloud SQL sizing guide to find what works best for your environment.

Inputs

Name Description Type Default Required
admin_disable_polling Whether to disable polling for Admin API bool "false" no
admin_max_calls Maximum calls that can be made to Admin API string "14" no
admin_period The period of max calls for the Admin API (in seconds) string "1.0" no
appengine_disable_polling Whether to disable polling for App Engine API bool "false" no
appengine_max_calls Maximum calls that can be made to App Engine API string "18" no
appengine_period The period of max calls for the App Engine API (in seconds) string "1.0" no
audit_logging_enabled Audit Logging scanner enabled. bool "false" no
audit_logging_violations_should_notify Notify for Audit logging violations bool "true" no
bigquery_acl_violations_should_notify Notify for BigQuery ACL violations bool "true" no
bigquery_disable_polling Whether to disable polling for Big Query API bool "false" no
bigquery_enabled Big Query scanner enabled. bool "true" no
bigquery_max_calls Maximum calls that can be made to Big Query API string "160" no
bigquery_period The period of max calls for the Big Query API (in seconds) string "1.0" no
blacklist_enabled Audit Logging scanner enabled. bool "true" no
blacklist_violations_should_notify Notify for Blacklist violations bool "true" no
bucket_acl_enabled Bucket ACL scanner enabled. bool "true" no
bucket_cai_lifecycle_age GCS CAI lifecycle age value string "14" no
bucket_cai_location GCS CAI storage bucket location string "us-central1" no
buckets_acl_violations_should_notify Notify for Buckets ACL violations bool "true" no
cai_api_timeout Timeout in seconds to wait for the exportAssets API to return success. string "3600" no
client_access_config Client instance 'access_config' block map(any) <map> no
client_boot_image GCE Forseti Client boot image string "ubuntu-os-cloud/ubuntu-1804-lts" no
client_instance_metadata Metadata key/value pairs to make available from within the client instance. map(string) <map> no
client_private Private GCE Forseti Client VM (no public IP) bool "false" no
client_region GCE Forseti Client region string "us-central1" no
client_ssh_allow_ranges List of CIDRs that will be allowed ssh access to forseti client list(string) <list> no
client_tags GCE Forseti Client VM Tags list(string) <list> no
client_type GCE Forseti Client machine type string "n1-standard-2" no
cloud_profiler_enabled Enable the Cloud Profiler bool "false" no
cloudasset_disable_polling Whether to disable polling for Cloud Asset API bool "false" no
cloudasset_max_calls Maximum calls that can be made to Cloud Asset API string "1" no
cloudasset_period The period of max calls for the Cloud Asset API (in seconds) string "1.0" no
cloudbilling_disable_polling Whether to disable polling for Cloud Billing API bool "false" no
cloudbilling_max_calls Maximum calls that can be made to Cloud Billing API string "5" no
cloudbilling_period The period of max calls for the Cloud Billing API (in seconds) string "1.2" no
cloudsql_acl_enabled Cloud SQL scanner enabled. bool "true" no
cloudsql_acl_violations_should_notify Notify for CloudSQL ACL violations bool "true" no
cloudsql_db_name CloudSQL database name string "forseti_security" no
cloudsql_db_port CloudSQL database port string "3306" no
cloudsql_disk_size The size of data disk, in GB. Size of a running instance cannot be reduced but can be increased. string "25" no
cloudsql_net_write_timeout See MySQL documentation: https://dev.mysql.com/doc/refman/5.7/en/server-system-variables.html#sysvar_net_write_timeout string "240" no
cloudsql_private Whether to enable private network and not to create public IP for CloudSQL Instance bool "false" no
cloudsql_proxy_arch CloudSQL Proxy architecture string "linux.amd64" no
cloudsql_region CloudSQL region string "us-central1" no
cloudsql_type CloudSQL Instance size string "db-n1-standard-4" no
cloudsql_user_host The host the user can connect from. Can be an IP address or IP address range. Changing this forces a new resource to be created. string "%" no
composite_root_resources A list of root resources that Forseti will monitor. This supersedes the root_resource_id when set. list(string) <list> no
compute_disable_polling Whether to disable polling for Compute API bool "false" no
compute_max_calls Maximum calls that can be made to Compute API string "18" no
compute_period The period of max calls for the Compute API (in seconds) string "1.0" no
config_validator_enabled Config Validator scanner enabled. bool "false" no
config_validator_violations_should_notify Notify for Config Validator violations. bool "true" no
container_disable_polling Whether to disable polling for Container API bool "false" no
container_max_calls Maximum calls that can be made to Container API string "9" no
container_period The period of max calls for the Container API (in seconds) string "1.0" no
crm_disable_polling Whether to disable polling for CRM API bool "false" no
crm_max_calls Maximum calls that can be made to CRN API string "4" no
crm_period The period of max calls for the CRM API (in seconds) string "1.2" no
cscc_source_id Source ID for CSCC Beta API string "" no
cscc_violations_enabled Notify for CSCC violations bool "false" no
domain The domain associated with the GCP Organization ID string n/a yes
enable_cai_bucket Create a GCS bucket for CAI exports bool "true" no
enable_write Enabling/Disabling write actions bool "false" no
enabled_apis_enabled Enabled APIs scanner enabled. bool "false" no
enabled_apis_violations_should_notify Notify for enabled APIs violations bool "true" no
excluded_resources A list of resources to exclude during the inventory phase. list(string) <list> no
external_project_access_violations_should_notify Notify for External Project Access violations bool "true" no
firewall_rule_enabled Firewall rule scanner enabled. bool "true" no
firewall_rule_violations_should_notify Notify for Firewall rule violations bool "true" no
folder_id GCP Folder that the Forseti project will be deployed into string "" no
forseti_email_recipient Email address that receives Forseti notifications string "" no
forseti_email_sender Email address that sends the Forseti notifications string "" no
forseti_home Forseti installation directory string "$USER_HOME/forseti-security" no
forseti_repo_url Git repo for the Forseti installation string "https://github.com/forseti-security/forseti-security" no
forseti_run_frequency Schedule of running the Forseti scans string "null" no
forseti_version The version of Forseti to install string "v2.22.0" no
forwarding_rule_enabled Forwarding rule scanner enabled. bool "false" no
forwarding_rule_violations_should_notify Notify for forwarding rule violations bool "true" no
group_enabled Group scanner enabled. bool "true" no
groups_settings_disable_polling Whether to disable polling for the G Suite Groups API bool "false" no
groups_settings_enabled Groups settings scanner enabled. bool "true" no
groups_settings_max_calls Maximum calls that can be made to the G Suite Groups API string "5" no
groups_settings_period the period of max calls to the G Suite Groups API string "1.1" no
groups_settings_violations_should_notify Notify for groups settings violations bool "true" no
groups_violations_should_notify Notify for Groups violations bool "true" no
gsuite_admin_email G-Suite administrator email address to manage your Forseti installation string "" no
iam_disable_polling Whether to disable polling for IAM API bool "false" no
iam_max_calls Maximum calls that can be made to IAM API string "90" no
iam_period The period of max calls for the IAM API (in seconds) string "1.0" no
iam_policy_enabled IAM Policy scanner enabled. bool "true" no
iam_policy_violations_should_notify Notify for IAM Policy violations bool "true" no
iam_policy_violations_slack_webhook Slack webhook for IAM Policy violations string "" no
iap_enabled IAP scanner enabled. bool "true" no
iap_violations_should_notify Notify for IAP violations bool "true" no
instance_network_interface_enabled Instance network interface scanner enabled. bool "false" no
instance_network_interface_violations_should_notify Notify for instance network interface violations bool "true" no
inventory_email_summary_enabled Email summary for inventory enabled bool "false" no
inventory_gcs_summary_enabled GCS summary for inventory enabled bool "true" no
inventory_retention_days Number of days to retain inventory data. string "-1" no
ke_scanner_enabled KE scanner enabled. bool "false" no
ke_version_scanner_enabled KE version scanner enabled. bool "true" no
ke_version_violations_should_notify Notify for KE version violations bool "true" no
ke_violations_should_notify Notify for KE violations bool "true" no
kms_scanner_enabled KMS scanner enabled. bool "true" no
kms_violations_should_notify Notify for KMS violations bool "true" no
kms_violations_slack_webhook Slack webhook for KMS violations string "" no
lien_enabled Lien scanner enabled. bool "true" no
lien_violations_should_notify Notify for lien violations bool "true" no
location_enabled Location scanner enabled. bool "true" no
location_violations_should_notify Notify for location violations bool "true" no
log_sink_enabled Log sink scanner enabled. bool "true" no
log_sink_violations_should_notify Notify for log sink violations bool "true" no
logging_disable_polling Whether to disable polling for Logging API bool "false" no
logging_max_calls Maximum calls that can be made to Logging API string "9" no
logging_period The period of max calls for the Logging API (in seconds) string "1.0" no
mailjet_enabled Enable mailjet_rest library bool "false" no
manage_rules_enabled A toggle to enable or disable the management of rules bool "true" no
network The VPC where the Forseti client and server will be created string "default" no
network_project The project containing the VPC and subnetwork where the Forseti client and server will be created string "" no
org_id GCP Organization ID that Forseti will have purview over string "" no
policy_library_home The local policy library directory. string "$USER_HOME/policy-library" no
policy_library_repository_url The git repository containing the policy-library. string "" no
policy_library_sync_enabled Sync config validator policy library from private repository. bool "false" no
policy_library_sync_gcs_directory_name The directory name of the GCS folder used for the policy library sync config. string "policy_library_sync" no
policy_library_sync_git_sync_tag Tag for the git-sync image. string "v3.1.2" no
policy_library_sync_ssh_known_hosts List of authorized public keys for SSH host of the policy library repository. string "" no
project_id Google Project ID that you want Forseti deployed into string n/a yes
resource_enabled Resource scanner enabled. bool "true" no
resource_name_suffix A suffix which will be appended to resource names. string "null" no
resource_violations_should_notify Notify for resource violations bool "true" no
securitycenter_max_calls Maximum calls that can be made to Security Center API string "14" no
securitycenter_period The period of max calls for the Security Center API (in seconds) string "1.0" no
sendgrid_api_key Sendgrid.com API key to enable email notifications string "" no
server_access_config Server instance 'access_config' block map(any) <map> no
server_boot_disk_size Size of the GCE instance boot disk in GBs. string "100" no
server_boot_disk_type GCE instance boot disk type, can be pd-standard or pd-ssd. string "pd-ssd" no
server_boot_image GCE Forseti Server boot image - Currently only Ubuntu is supported string "ubuntu-os-cloud/ubuntu-1804-lts" no
server_grpc_allow_ranges List of CIDRs that will be allowed gRPC access to forseti server list(string) <list> no
server_instance_metadata Metadata key/value pairs to make available from within the server instance. map(string) <map> no
server_private Private GCE Forseti Server VM (no public IP) bool "false" no
server_region GCE Forseti Server region string "us-central1" no
server_ssh_allow_ranges List of CIDRs that will be allowed ssh access to forseti server list(string) <list> no
server_tags GCE Forseti Server VM Tags list(string) <list> no
server_type GCE Forseti Server machine type string "n1-standard-8" no
service_account_key_enabled Service account key scanner enabled. bool "true" no
service_account_key_violations_should_notify Notify for service account key violations bool "true" no
servicemanagement_disable_polling Whether to disable polling for Service Management API bool "false" no
servicemanagement_max_calls Maximum calls that can be made to Service Management API string "2" no
servicemanagement_period The period of max calls for the Service Management API (in seconds) string "1.1" no
serviceusage_disable_polling Whether to disable polling for Service Usage API bool "false" no
serviceusage_max_calls Maximum calls that can be made to Service Usage API string "4" no
serviceusage_period The period of max calls for the Service Usage API (in seconds) string "1.1" no
sqladmin_disable_polling Whether to disable polling for SQL Admin API bool "false" no
sqladmin_max_calls Maximum calls that can be made to SQL Admin API string "1" no
sqladmin_period The period of max calls for the SQL Admin API (in seconds) string "1.1" no
storage_bucket_location GCS storage bucket location string "us-central1" no
storage_disable_polling Whether to disable polling for Storage API bool "false" no
subnetwork The VPC subnetwork where the Forseti client and server will be created string "default" no
violations_slack_webhook Slack webhook for any violation. Will apply to all scanner violation notifiers. string "" no

Outputs

Name Description
forseti-client-service-account Forseti Client service account
forseti-client-storage-bucket Forseti Client storage bucket
forseti-client-vm-ip Forseti Client VM private IP address
forseti-client-vm-name Forseti Client VM name
forseti-cloudsql-connection-name Forseti CloudSQL Connection String
forseti-server-git-public-key-openssh The public OpenSSH key generated to allow the Forseti Server to clone the policy library repository.
forseti-server-service-account Forseti Server service account
forseti-server-storage-bucket Forseti Server storage bucket
forseti-server-vm-ip Forseti Server VM private IP address
forseti-server-vm-name Forseti Server VM name
suffix The random suffix appended to Forseti resources

Requirements

Installation Dependencies

Service Account

In order to execute this module you must have a Service Account with the following roles assigned. There is a helpful setup script documented below which can automatically create this account for you.

IAM Roles

For this module to work, you need the following roles enabled on the Service Account.

On the organization:

  • roles/resourcemanager.organizationAdmin
  • roles/securityReviewer

On the project:

  • roles/owner
  • roles/compute.instanceAdmin
  • roles/compute.networkViewer
  • roles/compute.securityAdmin
  • roles/iam.serviceAccountAdmin
  • roles/serviceusage.serviceUsageAdmin
  • roles/iam.serviceAccountUser
  • roles/storage.admin
  • roles/cloudsql.admin

On the host project (when using shared VPC)

  • roles/compute.securityAdmin
  • roles/compute.networkAdmin

GSuite Admin

To use the IAM exploration functionality of Forseti, you will need a Super Admin on the Google Admin console. This admin's email must be passed in the gsuite_admin_email variable.

APIs

For this module to work, you need the following APIs enabled on the Forseti project.

  • compute.googleapis.com
  • serviceusage.googleapis.com
  • cloudresourcemanager.googleapis.com

Install

Create the Service Account and enable required APIs

You can create the service account manually, or by running the following command:

./helpers/setup.sh -p PROJECT_ID -o ORG_ID

This will create a service account called cloud-foundation-forseti-<suffix>, give it the proper roles, and download service account credentials to ${PWD}/credentials.json. Note, that using this script assumes that you are currently authenticated as a user that can create/authorize service accounts at both the organization and project levels.

This script will also activate necessary APIs required for terraform to run.

If you are using the real time policy enforcer, you will need to generate a service account with a few extra roles. This can be enabled with the -e flag:

./helpers/setup.sh -p PROJECT_ID -o ORG_ID -e

Utilizing a shared VPC via a host project is supported with the -f flag:

./helpers/setup.sh -p PROJECT_ID -f HOST_PROJECT_ID -o ORG_ID

Terraform

Be sure you have the correct Terraform version (0.12), you can choose the binary here:

Additionally, you will need to export TF_WARN_OUTPUT_ERRORS=1 to work around a known issue with Terraform when running terraform destroy.

Manual steps

The following steps need to be performed manually/outside of this module.

GSuite Scanning

To enable GSuite groups and users scanning, you must activate Domain Wide Delegation on the Service Account used for Forseti server VM: forseti-server-gcp-<number>@<project_id>.iam.gserviceaccount.com.

Please refer to the Forseti documentation for step by step directions.

CSCC Integration

To send Forseti notifications to the Cloud Security Command Center, you need to enable the Forseti add-on in the CSCC.

After activating the add-on, copy the integration's source_id and paste it into the cscc_source_id field in your Terraform configuration.

Run terraform apply again to complete the configuration.

Cleanup

Remember to cleanup the service account used to install Forseti either manually, or by running the command:

./scripts/cleanup.sh -p PROJECT_ID -o ORG_ID -s cloud-foundation-forseti-<suffix>

This will deprovision and delete the service account, and then delete the credentials file.

If the service account was provisioned with the roles needed for the real time policy enforcer, you can set the -e flag to clean up those roles as well:

./scripts/cleanup.sh -p PROJECT_ID -o ORG_ID -S cloud-foundation-forseti-<suffix> -e

Autogeneration of documentation from .tf files

Run

make generate_docs

Additional Documentation included

  • (test/README.md): Overview on howto run the test suite
  • (test/integration/gcp/README.md): Detailed information about the base test suite
  • (examples/simple/README.md): Overview of basic usage of the module

File structure

The project has the following folders and files:

  • (/): root folder
  • (/examples): examples for using this module
  • (/main.tf): main file for this module, contains all the resources to create
  • (/variables.tf): all the variables for the module
  • (/test): all integration tests are located here
  • (/README.md): this file
You can’t perform that action at this time.