This article explains how to connect Google Cloud Platform (GCP) to Expel Workbench.
Prerequisites
Before starting the procedure below, you must have:
-
A Google Cloud Platform admin account.
- Elevated yourself to admin in Google Cloud Platform.
-
A Google Workspace integration onboarded in Workbench. This is essential, even if you are not a Google Workspace customer, as Google tracks OAuth 2.0 token grants for Google Cloud Platform in the Google Workspace Admin Audit Logs.
- GCloud command-line tool installed.
Quick Start
Setup includes the following steps (select any step for detailed instructions):
- Create a Google Cloud Platform Project
- Activate the Cloud Asset API on the New Project
- Create a Service Account
- Create Cloud Asset Custom Role and Add to Service Account
- Configure a PubSub Topic and Subscription
- Create the Aggregated Organization Log Sinks
- Enable Event Threat Detection (optional)
- Register Google Cloud Platform in Workbench
Step 1: Create a Google Cloud Platform Project
Create a project and name it "expel-integration". Use it to host the rest of the integration’s resources.
Step 2: Activate the Cloud Asset API on the New Project
-
Go to https://console.cloud.google.com/apis/library/cloudasset.googleapis.com.
-
Select the name of your new project.
-
If the Cloud Asset API isn't enabled, select Enable.
Step 3: Create a Service Account
-
Log in to the GCP console and navigate to the expel-integration project.
-
From the navigation menu, go to IAM & Admin > Service Accounts.
-
Create a new service account and enter the details:
-
Service account name - enter "expel-gcp-integration".
-
Service account ID - [auto-filled]
-
Service account description - enter "used by Expel".
-
-
Grant the service account Pub/Sub Subscriber and BigQuery Job User permissions.
-
Generate a JSON private key and download it.
Step 4: Create Cloud Asset Custom Role and Add to Service Account
-
Open Google Cloud Platform.
-
Make sure you are under the Organization and not a project.
-
Navigate to IAM & Admin > Roles.
-
Select Create Role.
-
Enter the Title, Description, and ID.
-
Select Add Permissions.
-
Add the following to the requested permissions:
-
cloudasset.assets.listResource
-
cloudasset.assets.listIamPolicy
-
cloudasset.assets.listOrgPolicy
-
cloudasset.assets.listAccessPolicy
-
cloudasset.assets.listOSInventories
-
- Select Add.
-
After you are done adding permissions, select Create.
-
The next step is adding the Service Account with the Role to IAM. You may need to log out and back in to see the new role as an option.
-
Verify you are still under the Organization and not a project.
-
Navigate to IAM & Admin > IAM.
-
Select Add.
-
Paste in the Service Account Email (expel-gcp-integration@expel-integration.iam.gserviceaccount.com if following this guide's nomenclature) as the new Principal.
Step 5: Configure a PubSub Topic and Subscription
Configuring a PubSub topic and subscription creates a middle-man for the sink and Expel receiving alerts. WIthout this step, Expel Workbench can't receive alerts from Google Cloud.
-
Navigate to Pub/Sub > Topics.
-
Create a new topic.
-
Topic ID - expel-integration-topic
-
Select Add a default subscription. This creates a subscription that you change in the next step.
Make note of the full topic name as we'll use it later. It follows this format:
projects/[project-id]/topics/expel-integration-topic
-
-
Navigate to Pub/Sub > Subscriptions. The expel-integration-topic-sub subscription created in the previous step appears in your list of subscriptions.
-
Change the Acknowledgement deadline to 600 seconds and keep the default values for the rest of the options.
-
Make note of the full subscription name because we use it later. It follows this format:
projects/[project-id]/subscriptions/expel-integration-topic-sub
Step 6: Create the Aggregated Organization Log Sinks
Note
Organization sinks can't be created from the Google Cloud console, so we use the gcloud command-line tool.
-
Log in to GCP.
$ gcloud auth login
-
List the organizations and take note of the org ID.
$ gcloud organizations list
-
Create the pub/sub org sink.
-
Use this command to filter activity logs:
$ gcloud logging sinks create expel-org-sink-pubsub pubsub.googleapis.com/projects/[project-id]/topics/expel-integration-topic --include-children --organization=[org-id] --log-filter="logName=~\"cloudaudit\.googleapis\.com\%2Factivity\" AND protoPayload.serviceName!=\"k8s\.io\""
This automatically creates a new service account which must be granted Pub/Sub Publisher permissions on the integration’s topic:
Created [https://logging.googleapis.com/v2/organizations/000000000000/sinks/expel-org-sink]. -
Grant serviceAccount:o278854420484-586207@gcp-sa-logging.iam. gserviceaccount.com the Pub/Sub Publisher role on the topic.
More information about sinks can be found at https://cloud.google.com/logging/docs/export/configure_export_v2
-
-
From the console, navigate to PubSub > Topics > expel-integration-topic. Use the Permissions tab to add the service account created above as a member.
Step 7: Enable Event Threat Detection (optional)
Event Threat Detection is a service offered by Google Cloud Platform at an additional cost (at the time of writing, it is included in the SCC Premium Tier). If you do not use this service, skip this section and proceed to Step 8. Learn more about Event Threat Detection.
Linking Event Threat Detection with Expel Workbench is a two-part process. You must enable Continuous Exports to Cloud Logging directed at a specific project and then create a Log Sink that routes logs to the Expel Pub/Sub topic.
Create Continuous Exports for Cloud Logging
To log findings:
-
In the Google Cloud console, navigate to the Security Command Center page.
-
Make sure you are under the Organization and not a project.
-
Select Settings.
-
Select the Continuous Exports tab.
-
Under Export name, select Logging Export.
- Under Sinks, set Log Findings to Logging.
- Review the destination Logging project, as there are different options depending on what is configured:
- If you have no Logging Project currently defined, set the Logging Project to the Expel project created in Step 1.
- If you have an existing Logging Project defined and you want to use that existing project, don't change this setting, but do note the logging project name for use in the next section.
- Select Save.
Create a Sink for Event Threat Detection
- If you are using an existing logging project for ETD findings, you should ensure you are under the existing project before following these steps. Otherwise, navigate to the Expel project created in Step 1.
- Navigate to Log Router.
- Create a new sink:
- Name - enter "ETD to Expel".
- Description - enter "Send Event Threat Detection logs to Expel".
- Sink Destination - select the Pub/Sub topic created previously in Step 5.
-
Choose logs to include in Log Sink - use the filter
resource.type="threat_detector"
. - Preview the logs (this will open a new tab) to ensure previous steps were completed correctly and that you can verify the filter selects the threat_detector (ETD) logs. If the preview shows the correct ETD logs, then go back to the original tab and select Create Sink.
- Add the permission needed to allow either the existing or the new project to publish to the Expel pub/sub topic:
- From the Console, navigate to PubSub > Topics > expel-integration-topic.
- Select the Permissions tab.
- If you are using an existing logging project, add the role of Pub/Sub Publisher for the service account associated with the existing logging project.
- If you are using the Expel project, add the role of Pub/Sub Publisher for the service account associated with the Expel project.
Verify Log Events are Flowing to the Pub/Sub Topic
- Go to either the Expel project or existing project used for logging from the above steps.
- Navigate to Log Router and locate the Log Sinks section.
- Look for the Log Sink created in the above steps (“ETD to Expel”). Look at the Column named Volume and verify you see more than zero for volume to indicate the Log Sink is routing logs to the Pub/Sub topic.
Step 8: Add Google Cloud Platform as a Security Device in Workbench
-
Navigate to Organization Settings > Security Devices.
-
Select Add Security Device.
-
Search for and select Google Cloud Platform.
-
Fill in the Connection Settings as follows:
-
Auth JSON - enter the JSON key from Step 3.
-
Subscription Name - enter the full PubSub subscription name from Step 5.
-
Organization ID - enter your GCP Organization ID.
-
- Select Save.
- Your device should be created successfully within a few seconds. A few reminders:
- After your connection is healthy, it will take some time for your device to begin polling and receiving data.
- To check on the status, select the downward arrow for your device in the first column and choose View details. You can then scroll to the Connection section to see if your device is fully connected.
- Polling will happen first; data will be received after that. You must refresh the page to see updates.
- If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, contact our Support team for help.
- To check if alerts are coming through, navigate to Dashboards > Alert Analysis. Scroll to the device you want to check and select the Expel Alerts tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we tune your device.