The procedure below describes how to create Lacework GCP integrations by running a python script called app.py in the GCP Cloud Shell.
This new app.py script has the following features:
- Supports creating Lacework GCP Compliance and Audit Trail integrations. A single script run creates a single Lacework GCP Compliance integration and optionally one or more Lacework GCP Audit Trail integrations. In a script run, you must create a Lacework GCP Compliance integration and you cannot create just Lacework GCP Audit Trail integration(s).
- Supports entering the configuration settings interactively from prompts or by specifying a configuration YAML file. Even if you enter the configuration settings interactively, the script saves the settings into a YAML file. The script retrieves input settings from the configuration YAML file and uses GCP deployment manager to create the Lacework-required GCP resources in the setup project.
- Supports rolling back the changes made in GCP if the script encounters a problem. If the script determines that the current GCP user does not have adequate privileges or the script fails to create all the required GCP resources, the script rolls back any resource changes it made.
You can download the app.py script and additional files from the Lacework csp-integrations GitHub repository as described in more detail below.
The script creates a Google-managed service account that is associated with the setup project and is in the following format: YourProjectNumber@cloudservices.gserviceaccount.com. If Audit Trail integration is configured, the script grants permissions for the setup project to monitor audit logging in selected projects. This account is not listed under Service Accounts in the GCP Console. For more information, see Google-managed service accounts in https://cloud.google.com/iam/docs/service-accounts. Lacework does not need access to this Google-managed service account.
Requirements
This python app.py script supports Python 2.7.
Decide if you want to integrate at the GCP organization or project level. If integrating at the organization level, all GCP projects in that organization are monitored.
This script prompts if you have a valid Lacework API token. Decide how you will generate the valid Lacework API token.
- If you answer no to this prompt, the script prompts you to provide a Lacework access key file that you create and download from the Lacework Console. For instructions, see Access Keys and Tokens APIs.
- If you answer yes to this prompt, the script prompts you to provide Lacework API token. To acquire a Lacework API token, follow the instructions in Access Keys and Tokens APIs.
This API token is used to create the Lacework integration that is visible from the Lacework Console.
You must identify the project ID of a setup project where the resource deployment occurs. If you are monitoring at the project level, the setup project must be the same project that is monitored by Lacework for compliance or audit logging. The script prompts you to enter the project ID of the setup project. For more information about the GCP project ID, see Google Cloud Platform Overview.
Lacework requires that the GCP user that will run the script to have certain GCP permissions in the setup project as listed below.
If your GCP account does not have these roles, contact your GCP administrator. To see if you have these roles, see Check Your Roles.
The GCP user that runs the app.py script requires the following GCP permissions in the setup project:
- deploymentmanager.deployments.create
- deploymentmanager.deployments.delete
- deploymentmanager.deployments.get
- deploymentmanager.manifests.get
- deploymentmanager.manifests.list
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
- resourcemanager.projects.setIamPolicy
- serviceusage.services.disable
- serviceusage.services.enable
- serviceusage.services.get
If you are integrating at the organization level, the GCP user that runs the app.py script requires the following GCP permissions in the setup project:
- resourcemanager.organizations.get
- resourcemanager.organizations.getIamPolicy
- resourcemanager.organizations.setIamPolicy
If you are creating an Audit Trail integration, the GCP user that runs the app.py script requires the following GCP audit permissions for all the projects that you want to audit:
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
- resourcemanager.projects.setIamPolicy
NOTE: These permissions are only required by the GCP user that is running the app.py script and not by the Google-managed service account created by the script.
When integrating with an Audit Trail, decide if you have an existing bucket that you want to use for audit logging or if you want the script to create a new bucket. If you want to use an existing bucket, the setup project requires the following GCP bucket permissions:
- storage.buckets.create
- storage.buckets.delete
- storage.buckets.list
Check Your Roles
Verify that your GCP account has the required permissions listed above before running the script.
- Log in to the GCP Console and click the Home button located in the top left corner.
- Select IAM & admin > IAM.
- Click the down arrow in the top menu bar.
The Select from dialog appears. - From the Select from the drop-down, select an organization that contains your GCP setup project. The setup project is where the resource deployment will occur.
- Select the ALL tab.
- In the Select from panel, locate and double-click the setup project.
- Click the Home button located in the top left corner.
- Select IAM & admin > Roles.
- Click the Filter table field, select the Permissions option from the drop-down, and enter each of the permissions listed above.
- Verify that you have each of the permissions listed above.
If you do not have all the required permissions, your GCP administrator may need to create new custom role(s) or identify a set of existing roles with these required permissions and grant your GCP account these roles for the setup project before you can run the script. For instructions, see the Grant Roles with Required Permissions to Setup Project. For more information about creating custom roles, see https://cloud.google.com/iam/docs/creating-custom-roles. For more information about GCP permissions, see https://cloud.google.com/iam/docs/permissions-reference.
Enable the Cloud Resource Manager API
You must enable the Cloud Resource Manager API before running the python app.py script.
- Log in to the GCP Console and click the Home button.
- Select APIs & Services > Library.
- In the Search for APIs & Services field, enter Resource Manager.
- Click Cloud Resource Manager API.
- Click ENABLE.
- If you are prompted to enable billing, click ENABLE BILLING.
Open the GCP Cloud Shell, Download the Scripts and Install the Required Python Packages
- Log in to the GCP Console.
In the top right corner of the GCP console, select Activate Cloud Shell.
The GCP Cloud Shell opens at the bottom of your console.
- Click the Cloud Shell and enter the following command to get the scripts from GitHub. The csp-integrations directory is created with the scripts and files required to run the python script.
$ git clone https://github.com/lacework/csp-integrations.git
- Go to the directory that contains the GCP scripts.
$ cd csp-integrations/gcp-cli/
- Install the required versions of the python packages.
$ pip install --user -r requirements.txt
Run the Script
You can have the script prompt for the configuration settings or you can specify the path to a configuration settings YAML file.
Lacework recommends first running the script interactively to generate the first YAML configuration file. After the creation of a first integration, you can alter the existing YAML configuration file with the settings for the new integration, rerun the script again and select the option to specify the path to the configuration settings YAML file.
To run the script:
- Go to the directory that contains the GCP scripts.
$ cd csp-integrations/gcp-cli/
- In the GCP Cloud Shell, start the script.
$ python app.py
Follow the prompts to enter your configuration settings. The script saves the configuration settings into a YAML file. If you accept the settings, the script calls the GCP deployment manager that retrieves the required input settings from the configuration YAML file and creates the Lacework required resources in GCP.
The generated configuration YAML file called configCustom.yml and is created in the gcp-cli directory.
If you specified that the script should automatically create the GCP integrations, the script creates GCP integration(s) in your Lacework Application using the GCP deployment manager. After the GCP compliance integration is created, the script also generates a compliance report.
The script also creates a file called deploymentOutput.txt that contains the settings required to create GCP integrations in Lacework. If you specified that the script should not automatically create GCP integrations or the creation of the GCP integrations(s) failed, you can create the integration(s) manually as described in the procedures listed below.
If the creation of the GCP integration(s) fail, check the deploymentOutput.txt file for missing permissions and error messages. Fix any problems and create the integration(s) manually.
To create the GCP integration(s) manually, see the following procedures:
- See Create the GCP Compliance Integration on the Lacework Console in GCP Compliance Integration - Manually using the GCP Console
- See Create the GCP Audit Log Integration on the Lacework Console in
GCP Audit Trail Log Integration (Beta) - Manually using the GCP Console
GCP Privileges or Resource Creation Script Failures
If the script determines it does not have adequate privileges or it fails to create all the required GCP resources, the script fails and writes the error to a log file called laceworkIntegrationScript.log. The script also automatically rolls back any Lacework-required resources that it created. If you also want to roll back any of the enabled APIs or permissions, enter the following command.
$ python app.py --rollback true
WARNING: If running the script again after a failure, change the specified setup prefix.
Roles and Permissions Granted to Lacework
The script creates a Google-managed service account in the following format: YourProjectNumber@cloudservices.gserviceaccount.com. Lacework does not need access to this Google-managed service account.
The script grants the IAM roles to this service account as listed in the following table.
Role | When Granted? |
---|---|
Deployment Manager Type Viewer | Always |
Deployment Manager Viewer | Always |
Deployment Manager Editor | Always |
Pub/Sub Admin | Always |
Project IAM Admin | Always |
Organization Resource Manager Admin | When integrating at the organization level |
Logging Admin | When integrating Audit Logs: 1) If you are integrating Audit Logs at the organization level, the Logging Admin role is granted to the specified organization. 2) If you are integrating Audit Logs at the project level, the Logging Admin role is granted to the specified project. |