Skip to content
This repository has been archived by the owner on Oct 20, 2023. It is now read-only.

Latest commit

 

History

History
425 lines (367 loc) · 29.7 KB

README.md

File metadata and controls

425 lines (367 loc) · 29.7 KB

Notice of Archiving

Dear Forseti users,

We are writing to inform you that we plan to archive the Forseti-Security repository.

Over the past few years, GCP Security has introduced a host of new features and capabilities that have addressed many security challenges targeted by Forseti. With low community engagement and limited improvements in the last two years, we have decided to place Forseti Security in archive. Note that other repos such as Forseti Real-Time-Enforcer and Resource-Policy-Evaliation-Library have also been automatically archived in February 2023 following no activities.

We plan to complete the archiving process by the end of June 2023.

What does this mean for you?

  • The Forseti-Security repository will be read-only, meaning that users will not be able to modify or contribute additional code.
  • You will however be able to fork or clone the repository and continue to use it however bearing ownership of your instance.
  • There will be no additional support from Google on Forseti. We are moving the existing support teams to new projects.

We thank you for your active engagement over the last few years.


Forseti Terraform Module

The Forseti Terraform module is the only supported method of deploying Forseti Security. The default infrastructure for Forseti is Google Compute Engine. For more information on installing Forseti on Google Kubernetes Engine (GKE), please see the detailed guide on the Forseti Security website.

Google Cloud Shell Walkthrough

A Google Cloud Shell Walkthrough has been setup to make it easy for users who are new to Forseti and Terraform. This walkthrough provides a set of instructions to get a default installation of Forseti setup that can be used in a production environment.

If you are familiar with Terraform and would like to run Terraform from a different machine, you can skip this walkthrough and move onto the How to Deploy section.

Open in Google Cloud Shell

How to Deploy

Install Terraform

Terraform version 0.12 is required for this module, which can be downloaded from the Terraform website. Terraform version 0.12.20 or greater is recommended.

Google Credentials

In order to run this module you will need to be authenticated as a user that has access to the project and can create/authorize service accounts at both the organization and project levels. To login to GCP from a shell, run:

gcloud auth login

Create a new Project

Create a new GCP project to deploy Forseti into. The Google Project Factory Terraform module can be used to provision the project with the required APIs enabled, along with a Shared VPC connection.

Create the Service Account and Enable Required APIs

The Service Account and required APIs can be setup automatically with a provided script. To perform these steps manually, review the Requirements section.

These commands will download and run the helper script. The script will create a service account called cloud-foundation-forseti-<suffix>, and assign it the proper roles. The service account credentials will be downloaded to ${PWD}/credentials.json.

source <(curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/setup.sh) -p PROJECT_ID -o ORG_ID

Usage for a Shared VPC

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

source <(curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/setup.sh) -f HOST_PROJECT_ID -p PROJECT_ID -o ORG_ID

Usage for GKE

Deploying Forseti on GKE is supported with the -k flag:

source <(curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/setup.sh) -k -p PROJECT_ID -o ORG_ID

Usage for Real-time Enforcer

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:

source <(curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/setup.sh) -e -p PROJECT_ID -o ORG_ID

Terraform Configuration

Example configurations are included in the examples directory. You can copy these examples or use the snippet below as a starting point to your own custom configuration.

The default Forseti Server VM machine type and Cloud SQL machine type have been set to n1-standard-8 and db-n1-standard-4 to account for larger GCP environments. These can be changed by providing the server_type and cloudsql_type variables.

Create a file named main.tf in an empty directory and copy the contents below into the file.

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

      gsuite_admin_email = "[email protected]"
      domain             = "yourdomain.com"
      project_id         = "my-forseti-project"
      org_id             = "2313934234"
    }

Forseti provides many optional settings for users to customize for their environment and security requirements. View the list of inputs to see all of the available options.

Run Terraform

Forseti is ready to be installed! First you will need to initialize Terraform to download the module dependencies.

terraform init

The configuration can now be applied which will determine the necessary actions to perform on the GCP project.

terraform apply

Review the Terraform plan and enter yes to perform these actions.

Cleanup

Remember to cleanup the service account used to deploy Forseti. A provided helper script will delete the service account, and delete the credentials files.

curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/cleanup.sh |
bash -s -- -p PROJECT_ID -o ORG_ID -s cloud-foundation-forseti-<suffix>

Usage for Real-Time Enforcer

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:

curl -sSL https://raw.githubusercontent.com/forseti-security/terraform-google-forseti/modulerelease521/helpers/cleanup.sh |
bash -s -- -e -p PROJECT_ID -o ORG_ID -s cloud-foundation-forseti-<suffix>

Forseti Configuration

Now that Forseti has been deployed, there are additional steps that you can follow to further configure Forseti. Some of the commonly used features are listed below:

Requirements

This section describes in detail the requirements necessary to deploy Forseti. The setup helper script automates the service account creation and enabling the APIs for you. Read through this section if you are not using the setup script.

Service Account

In order to execute this module you must have a Service Account with the following IAM roles assigned.

Organization Roles

  • roles/iam.securityReviewer
  • roles/resourcemanager.organizationAdmin

Project Roles

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

Host Project Roles (when using shared VPC)

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

Required APIs

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

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

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 Blacklist 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_enabled Enable Client VM bool "true" no
client_instance_metadata Metadata key/value pairs to make available from within the client instance. map(string) <map> no
client_labels Client instance labels 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_service_account Service account email to assign to the Client VM. If empty, a new Service Account will be created string "" no
client_shielded_instance_config Client instance 'shielded_instance_config' block if using shielded VM image map(string) "null" 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_availability_type Whether instance should be set up for high availability (REGIONAL) or single zone (ZONAL). string "null" no
cloudsql_db_name CloudSQL database name string "forseti_security" no
cloudsql_db_password CloudSQL database password string "" no
cloudsql_db_port CloudSQL database port string "3306" no
cloudsql_db_user CloudSQL database user string "forseti_security_user" 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_labels CloudSQL instance labels map(string) <map> 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_image The image of the Config Validator to use string "gcr.io/forseti-containers/config-validator" no
config_validator_image_tag The tag of the Config Validator image to use string "e018e7c" 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_service_networking Create a global service networking peering connection at the VPC level 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_logging Enable firewall logging bool "false" 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_scripts The local Forseti scripts directory string "$USER_HOME/forseti-scripts" no
forseti_version The version of Forseti to install string "v2.25.1" no
forwarding_rule_enabled Forwarding rule scanner enabled. bool "false" no
forwarding_rule_violations_should_notify Notify for forwarding rule violations bool "true" no
gcs_labels GCS bucket labels map(string) <map> no
google_cloud_sdk_version Version of the Google Cloud SDK to install string "335.0.0-0" 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_firewall_rules Create client firewall rules string "true" 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_branch The specific git branch containing the policies. string "master" 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
retention_enabled Retention scanner enabled. bool "false" no
retention_violations_should_notify Notify for retention violations bool "true" no
retention_violations_slack_webhook Slack webhook for retention violations string "" no
role_enabled Role scanner enabled. bool "false" no
role_violations_should_notify Notify for role violations bool "true" no
role_violations_slack_webhook Slack webhook for role violations string "" no
rules_path Path for Scanner Rules config files; if GCS, should be gs://bucket-name/path string "/home/ubuntu/forseti-security/rules" 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_labels Server instance labels 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_service_account Service account email to assign to the Server VM. If empty, a new Service Account will be created string "" no
server_shielded_instance_config Server instance 'shielded_instance_config' block if using shielded VM image map(string) "null" 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_class GCS storage bucket storage class. Supported values include: STANDARD, MULTI_REGIONAL, REGIONAL, NEARLINE, COLDLINE string "STANDARD" 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
verify_policy_library Verify the Policy Library is setup correctly for the Config Validator scanner bool "true" no
violations_slack_webhook Slack webhook for any violation. Will apply to all scanner violation notifiers. string "" no

Outputs

Name Description
forseti-cai-storage-bucket Forseti CAI storage bucket
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-cloudsql-instance-ip The IP of the master CloudSQL instance
forseti-cloudsql-password CloudSQL password
forseti-cloudsql-user CloudSQL user
forseti-server-git-public-key-openssh The public OpenSSH key generated to allow the Forseti Server to clone the policy library repository.
forseti-server-google-cloud-sdk-version Version of the Google Cloud SDK installed on the Forseti server
forseti-server-service-account Forseti Server service account
forseti-server-storage-bucket Forseti Server storage bucket
forseti-server-vm-internal-dns Forseti Server internal DNS
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

File structure

The project has the following folders and files:

  • build/: Google Cloud Build configuration
  • docs/: Additional documentation
  • examples/: examples for using this module
  • helpers/: Helper scripts
  • modules/: Private and sub-modules
  • test/: All integration tests are located here
  • CHANGELOG.md: A list of changes made for each release
  • CONTRIBUTING.md: Information on how to contribute to this project
  • LICENSE: License terms and conditions
  • main.tf: Main Terraform configuration file for this module, contains all the resources to install Forseti
  • README.md: This readme file
  • variables.tf: All the variables for the module