The Terraform Forseti module can be used to quickly install and configure Forseti in a fresh cloud project.
A simple setup is provided in the examples folder; however, the usage of the module within your own main.tf file is as follows:
provider "google" {
credentials = "${file("/path/to/credentials.json")}"
}
module "forseti" {
source = "terraform-google-modules/forseti/google"
version = "~> 2.0.0"
gsuite_admin_email = "superadmin@yourdomain.com"
domain = "yourdomain.com"
project_id = "my-forseti-project"
org_id = "2313934234"
}Then perform the following commands on the config folder:
terraform initto get the pluginsterraform planto see the infrastructure planterraform applyto apply the infrastructure buildterraform destroyto destroy the built infrastructure
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| admin_disable_polling | Whether to disable polling for Admin API | string | "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 | string | "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. | string | "false" |
no |
| audit_logging_violations_should_notify | Notify for Audit logging violations | string | "true" |
no |
| bigquery_acl_violations_should_notify | Notify for BigQuery ACL violations | string | "true" |
no |
| bigquery_disable_polling | Whether to disable polling for Big Query API | string | "False" |
no |
| bigquery_enabled | Big Query scanner enabled. | string | "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. | string | "true" |
no |
| blacklist_violations_should_notify | Notify for Blacklist violations | string | "true" |
no |
| bucket_acl_enabled | Bucket ACL scanner enabled. | string | "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 | string | "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 | <map> |
no |
| client_boot_image | GCE Forseti Client role instance size | string | "ubuntu-os-cloud/ubuntu-1804-lts" |
no |
| client_instance_metadata | Metadata key/value pairs to make available from within the client instance. | map | <map> |
no |
| client_private | Private GCE Forseti Client VM (no public IP) | string | "false" |
no |
| client_region | GCE Forseti Client role region size | string | "us-central1" |
no |
| client_ssh_allow_ranges | List of CIDRs that will be allowed ssh access to forseti client | list | <list> |
no |
| client_tags | GCE Forseti Client VM Tags | list | <list> |
no |
| client_type | GCE Forseti Client role instance size | string | "n1-standard-2" |
no |
| cloudasset_disable_polling | Whether to disable polling for Cloud Asset API | string | "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 | string | "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. | string | "true" |
no |
| cloudsql_acl_violations_should_notify | Notify for CloudSQL ACL violations | string | "true" |
no |
| cloudsql_db_name | CloudSQL database name | string | "forseti_security" |
no |
| cloudsql_db_port | CloudSQL database port | string | "3306" |
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-1" |
no |
| composite_root_resources | A list of root resources that Forseti will monitor. This supersedes the root_resource_id when set. | list | <list> |
no |
| compute_disable_polling | Whether to disable polling for Compute API | string | "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. | string | "false" |
no |
| config_validator_violations_should_notify | Notify for Config Validator violations. | string | "true" |
no |
| container_disable_polling | Whether to disable polling for Container API | string | "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 | string | "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 | string | "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 | string | "true" |
no |
| enable_write | Enabling/Disabling write actions | string | "false" |
no |
| enabled_apis_enabled | Enabled APIs scanner enabled. | string | "false" |
no |
| enabled_apis_violations_should_notify | Notify for enabled APIs violations | string | "true" |
no |
| external_project_access_violations_should_notify | Notify for External Project Access violations | string | "true" |
no |
| firewall_rule_enabled | Firewall rule scanner enabled. | string | "true" |
no |
| firewall_rule_violations_should_notify | Notify for Firewall rule violations | string | "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/GoogleCloudPlatform/forseti-security" |
no |
| forseti_run_frequency | Schedule of running the Forseti scans | string | "0 */2 * * *" |
no |
| forseti_version | The version of Forseti to install | string | "v2.14.1" |
no |
| forwarding_rule_enabled | Forwarding rule scanner enabled. | string | "false" |
no |
| forwarding_rule_violations_should_notify | Notify for forwarding rule violations | string | "true" |
no |
| group_enabled | Group scanner enabled. | string | "true" |
no |
| groups_settings_disable_polling | Whether to disable polling for the G Suite Groups API | string | "False" |
no |
| groups_settings_enabled | Groups settings scanner enabled. | string | "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 | string | "true" |
no |
| groups_violations_should_notify | Notify for Groups violations | string | "true" |
no |
| gsuite_admin_email | G-Suite administrator email address to manage your Forseti installation | string | n/a | yes |
| iam_disable_polling | Whether to disable polling for IAM API | string | "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. | string | "true" |
no |
| iam_policy_violations_should_notify | Notify for IAM Policy violations | string | "true" |
no |
| iam_policy_violations_slack_webhook | Slack webhook for IAM Policy violations | string | "" |
no |
| iap_enabled | IAP scanner enabled. | string | "true" |
no |
| iap_violations_should_notify | Notify for IAP violations | string | "true" |
no |
| instance_network_interface_enabled | Instance network interface scanner enabled. | string | "false" |
no |
| instance_network_interface_violations_should_notify | Notify for instance network interface violations | string | "true" |
no |
| inventory_email_summary_enabled | Email summary for inventory enabled | string | "true" |
no |
| inventory_gcs_summary_enabled | GCS summary for inventory enabled | string | "true" |
no |
| inventory_retention_days | Number of days to retain inventory data. | string | "-1" |
no |
| ke_scanner_enabled | KE scanner enabled. | string | "false" |
no |
| ke_version_scanner_enabled | KE version scanner enabled. | string | "true" |
no |
| ke_version_violations_should_notify | Notify for KE version violations | string | "true" |
no |
| ke_violations_should_notify | Notify for KE violations | string | "true" |
no |
| kms_scanner_enabled | KMS scanner enabled. | string | "true" |
no |
| kms_violations_should_notify | Notify for KMS violations | string | "true" |
no |
| kms_violations_slack_webhook | Slack webhook for KMS violations | string | "" |
no |
| lien_enabled | Lien scanner enabled. | string | "true" |
no |
| lien_violations_should_notify | Notify for lien violations | string | "true" |
no |
| location_enabled | Location scanner enabled. | string | "true" |
no |
| location_violations_should_notify | Notify for location violations | string | "true" |
no |
| log_sink_enabled | Log sink scanner enabled. | string | "true" |
no |
| log_sink_violations_should_notify | Notify for log sink violations | string | "true" |
no |
| logging_disable_polling | Whether to disable polling for Logging API | string | "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 |
| 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 | n/a | yes |
| project_id | Google Project ID that you want Forseti deployed into | string | n/a | yes |
| resource_enabled | Resource scanner enabled. | string | "true" |
no |
| resource_violations_should_notify | Notify for resource violations | string | "true" |
no |
| securitycenter_disable_polling | Whether to disable polling for Security Center API | string | "False" |
no |
| securitycenter_max_calls | Maximum calls that can be made to Security Center API | string | "1" |
no |
| securitycenter_period | The period of max calls for the Security Center API (in seconds) | string | "1.1" |
no |
| sendgrid_api_key | Sendgrid.com API key to enable email notifications | string | "" |
no |
| server_access_config | Server instance 'access_config' block | map | <map> |
no |
| server_boot_image | GCE instance image that is being used, currently Ubuntu only support is available | 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 | <list> |
no |
| server_instance_metadata | Metadata key/value pairs to make available from within the server instance. | map | <map> |
no |
| server_private | Private GCE Forseti Server VM (no public IP) | string | "false" |
no |
| server_region | GCP region where Forseti will be deployed | string | "us-central1" |
no |
| server_ssh_allow_ranges | List of CIDRs that will be allowed ssh access to forseti server | list | <list> |
no |
| server_tags | GCE Forseti Server VM Tags | list | <list> |
no |
| server_type | GCE Forseti Server role instance size | string | "n1-standard-2" |
no |
| service_account_key_enabled | Service account key scanner enabled. | string | "true" |
no |
| service_account_key_violations_should_notify | Notify for service account key violations | string | "true" |
no |
| servicemanagement_disable_polling | Whether to disable polling for Service Management API | string | "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 |
| sqladmin_disable_polling | Whether to disable polling for SQL Admin API | string | "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 | string | "False" |
no |
| subnetwork | The VPC subnetwork where the Forseti client and server will be created | string | "default" |
no |
| 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-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 |
- Terraform 0.11.x
- terraform-provider-google plugin v1.12.0
- Python 3.7.x
- terraform-docs (optional) 0.6.0
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.
For this module to work, you need the following roles enabled on the Service Account.
On the organization:
roles/resourcemanager.organizationAdminroles/securityReviewer
On the project:
roles/ownerroles/compute.instanceAdminroles/compute.networkViewerroles/compute.securityAdminroles/iam.serviceAccountAdminroles/serviceusage.serviceUsageAdminroles/iam.serviceAccountUserroles/storage.adminroles/cloudsql.admin
On the host project (when using shared VPC)
roles/compute.securityAdminroles/compute.networkAdmin
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.
For this module to work, you need the following APIs enabled on the Forseti project.
- compute.googleapis.com
- serviceusage.googleapis.com
- cloudresourcemanager.googleapis.com
You can create the service account manually, or by running the following command:
./helpers/setup.sh -p PROJECT_ID -o ORG_IDThis 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 -eUtilizing 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_IDBe sure you have the correct Terraform version (0.11.x), 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.
The following steps need to be performed manually/outside of this module.
Remember to activate the Domain Wide Delegation on the Service Account that Forseti creates for the server operations.
The service account has the form forseti-server-gcp-<number>@<project_id>.iam.gserviceaccount.com.
Please refer to the Forseti documentation for step by step directions.
More information about Domain Wide Delegation can be found here.
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> -eRun
make generate_docs
- (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
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