GCP via API - Advanced

1. About this document

This document provides a step-by-step guide to onboard your Google Cloud Platform into SAFE.

2. Introduction

SAFE allows you to onboard and assess your Google Cloud Platform (GCP) assets. SAFE admins can configure the GCP integration in SAFE using the SAFE REST APIs.

GCP onboarding in SAFE is a 3-step process. Upon successful configuration, SAFE automatically onboard the GCP assets into the "Cloud - GCP" vertical and assesses them.

3. Prerequisites

To configure GCP in SAFE, you need the following privileges:

• Security Command Center must be on the Premium tier
  
  Standard tier

  Support for SCC Standard is not currently available, and configuring SAFE to work with SCC Standard will not work.
• The user must have the SAFE Admin Role.
• The user must have the Admin Role in the GCP console.

4. Configure GCP

4.1. Create a Project

1. Log in to the Google Cloud Platform console at https://console.cloud.google.com.
   
   
2. Click the dropdown menu at the top of the page. (To the right of where it says "Google Cloud")
3. In the pop-up, click the NEW PROJECT button in the top right.
   
   
4. Enter a Project name. 
   • For example: "SAFE Integration"
5. Select the Organization and Location.
   
   Location

   When creating the project, you can put the project anywhere as per your company's convention. However, while setting up the permissions, the project must go in at the Organization level. 
6. Click the CREATE button.
   
7. After the project is created, there will be a pop-in with a link to open the project. Click that link or select the project in the drop-down at the top to move to the next step.

4.2. Enable API Services

1. Click the navigation menu available at the top left corner of the screen.
2. Navigate to APIs & Services > Library.
   
   Option may be hidden

   If APIs & Services option is not pinned, click the "View all products" option and scroll down to find APIs & Services option.
   
   
3. Search for Security Command Center API and click on Security Command Center API from the search results.
   
   
4. Click the ENABLE button to enable the API for this project. 
   1. Once the process completes, it can be verified by revisiting the page. 
   2. The page displays the label "API Enabled."
      
      
5. This process needs to be repeated for all 4 or the required APIs.
   1. Security Command Center API (Completed above)
   2. Cloud Resource Manager API
   3. Security Token Service API
   4. IAM Service Account Credentials API
6. To verify that all the required APIs have been enabled, go to the Enabled APIs & services page and check the table at the bottom of the page for the names of these 4 APIs.
   
   

   
   

4.3. Create a custom role

We need to create a custom IAM role at the organization level that can be assigned to the service account of the project used for SAFE to enable SAFE to read the organization’s Security Command Center findings.

1. Click the navigation menu available at the top left corner of the screen.
2. Navigate to IAM and admin > IAM.
   
   
3. On the IAM and admin page, click the drop-down at the top and ensure the parent Organization is selected.
   
   
    Organization level

   If the role is created in the wrong location, then this integration will not work. It is mandatory that the role is configured at the Organization level. This is so that the permissions are inherited, and SAFE will be able to retrieve the information required. If the role is created inside the Project, then the assessments will not work.
   
4. Click Roles from the left navigation bar.
   
   
5. Click the CREATE ROLE button at the top to create a custom role. 
6. On the Create role page:
   • Enter a Title for the role.
   • Change the ID if needed.
   • Click the ADD PERMISSIONS button.
     
     
     
7. In the Add permissions pop-up, enter the following list in the filter box one by one. Select the checkbox in the search result for the matching result(s), then click the ADD button. Repeat the process for each permission:
   1. resourcemanager.organizations.get
   2. resourcemanager.projects.get
   3. securitycenter.assets.list
   4. securitycenter.findings.list
   5. securitycenter.securityhealthanalyticssettings.calculate
      
      
      Quick tip

      To save time opening a new pop-up for each item, you can use an OR operator to add all the options at once.
      
8. Once all the permissions mentioned in the previous step are added, click the CREATE button.
   
   
9. The new role will now be visible under the list of roles on the IAM Roles page at https://console.cloud.google.com/iam-admin/roles under the Organization view.

4.4. Create a Service Account

1. Click the navigation menu available at the top left corner of the screen.
2. Navigate to IAM and admin > IAM.
   
   
   
3. At the top, click the CREATE SERVICE ACCOUNT button.
   
   
4. Enter a name for the service account and click CREATE AND CONTINUE.
   
   
5. Under the Grant this service account access to the project section, select the custom role created previously from the drop-down and then click CONTINUE.
   
   
6. Under Grant users access to this service account, click DONE to complete the process. 
   • The new service account should be present under the list of service accounts for the project at https://console.cloud.google.com/iam-admin/serviceaccounts.
7. Copy the value for Email as you will need this later.
   
   
8. Click IAM in the left navigation bar.
9. At the top of the table, make sure View by: PRINCIPALS is selected and not ROLES.
10. Click the drop-down at the top and ensure the parent Organization is selected.
11. At the top of the page, click the ADD button.
12. Enter the email from step 7 in the New principals field (You can also type and search for it if you prefer).
13. Under Role, select the role created earlier in section 1.3.
    
    
14. Click the SAVE button. 
    • The new service account can now be seen in the IAM principals table at the Organization level - https://console.cloud.google.com/iam-admin/iam.

4.5. Create a Workload Identity Federation Pool

1. Click the drop-down at the top and select the project you created for SAFE
2. Click the navigation menu available at the top left corner of the screen.
3. Navigate to IAM and admin > Workload Identity Federation
   
   
4. Click the GET STARTED button.
   
   
5. Enter a Name and Description.
   • Make sure that the Enabled Pool switch is enabled. 
6. Click the CONTINUE button.
   
   
7. In the Select a provider drop-down, select AWS.
8. Enter a Provider name and Provider ID.
9. Enter the Safe AWS Account ID as the AWS account ID.
   • You can access this ID by going to the private knowledge base article here.
   • To access this link, you will require a login to the Safe Helpdesk.
     
     
     Do not use your own AWS ID

     This is the Safe AWS ID. This is required to grant access from the Safe AWS infrastructure into your GCP account. Using any other AWS account ID here will result in the integration failing.
     
10. Click the CONTINUE button.
11. Under Configure provider attributes, click on EDIT MAPPING to so the additional settings
    
    
12. Change the value in the AWS box that maps with google.subject to "safe"
    • In the example, this is shown as Google 1 mapping to AWS 1
      
      
13. Click the SAVE button. 
14. On the next page, at the top, click GRANT ACCESS. 
    
    
15. In the "Grant access to service account" pop-up, select the service account that was created in 1.4 and click SAVE.
    
    
16. In the following pop-up, select the Provider you configured in step 8 and click on the DOWNLOAD CONFIG button to save the WIF file to your local disk.
    
    
17. Once downloaded, click the DISMISS button to close the pop-up

5. Configure SAFE

5.1. Switch to the SAFE REST APIs

1. Log into SAFE.
2. In the top-right, click on the help bubble icon
3. From the drop-down menu, select SAFE API
   • This will open the Swagger documentation in a new tab
     
     

5.2. Test if SAFE can connect to GCP

Before configuring SAFE to talk to GCP, we need to make sure that we can connect to the GCP console instance from SAFE. To do that we need to use the POST /api/v3/integrations/test API.

1. Scroll down until you find the Integrations section and click the down arrow on the right to expand the test API.
   
   
2. On the right, click on the Try it out button.
   
   
3. Using the example below, take the contents of the WIF file that was downloaded earlier and replace everything in the "config" section.

{
    "type": "cloud",
    "subtype": "gcp",
    "config": {
        "organizationIds": [
            "your GCP Org ID goes here"
        ],
        "type": "external_account",
        "audience": "//iam.googleapis.com/projects/684949267137/locations/global/workloadIdentityPools/safe-integration-pool/providers/safe-provider",
        "subject_token_type": "urn:ietf:params:aws:token-type:aws4_request",
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/safe-service-account@safe-integration-358814.iam.gserviceaccount.com:generateAccessToken",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
            "environment_id": "aws1",
            "region_url": "http://169.254.169.254/latest/meta-data/placement/availability-zone",
            "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials",
            "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"
        }
    }
}

Response

A 200 OK status response would be returned on a successful test connection with the following response body.

{
  "success": true,
  "message": "Test connection success"
}

5.3. Add GCP to SAFE

Now that the test connection is successful, we must create a new GCP integration within SAFE. We use the POST /api/v3/integrations API for this.

1. As before, find the correct API call in the list, expand it, and click the Try it out button on the right.
2. Take the entire JSON used in the previous test step and add the following values to the config section:
   1. autoSync
      • This is the time interval (in days) for SAFE to sync with GCP. Any value from 1 to 30 can be used.
   2. sensitiveFields
      1. This provides the option to specify which, if any, of the parameters should be encrypted when stored in SAFE. This field is an array of strings and so would accept something like ["audience", "organizationIds"].
3. Once you have everything in place, enter your JSON into the Request body and click the Execute button.

{
  "type": "cloud",
  "subtype": "gcp",
  "config": {
    "autoSync": 1,
    "sensitiveFields": [],
    "organizationIds": [
      "your GCP Org ID goes here"
    ],
    "type": "external_account",
    "audience": "//iam.googleapis.com/projects/684949267137/locations/global/workloadIdentityPools/safe-integration-pool/providers/safe-provider",
    "subject_token_type": "urn:ietf:params:aws:token-type:aws4_request",
    "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/safe-service-account@safe-integration-358814.iam.gserviceaccount.com:generateAccessToken",
    "token_url": "https://sts.googleapis.com/v1/token",
    "credential_source": {
      "environment_id": "aws1",
      "region_url": "http://169.254.169.254/latest/meta-data/placement/availability-zone",
      "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials",
      "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"
    }
  }
}

Response

On a successful save of the new configuration, a 200 OK status response should be returned with the following response body.

{
  "success": true,
  "message": "Integration configuration saved successfully.",
  "data": {
    "id": 1
  }
}

The value in the data.id field is the newly generated ID for this integration. If you have set up multiple integrations, then it is possible you would get a number other than 1 in the response. It may be worth taking note of this number as it will be useful later.

5.4. Trigger an action

We can use the POST /api/v3/integrations/{id}?action={action} API to trigger a number of different actions for the new integration. 

The available actions are:

1. sync
   • Start a sync of the data from GCP to SAFE
2. test
   • Check that the connection to GCP works and there are no errors
3. enable
   • Turn the integration on
4. disable
   • Turn the integration off

Take the Integration ID you received in the earlier response, add the required action, and press Execute.

After triggering a successful sync, you will see a response like this.

{  "success": true,  "message": "Sync is in progress"}{  "success": true,  "message": "Sync is in progress"}

5.5. Checking status

To view the status of the integration as well as all other stored information, we can use the GET /api/v3/integrations/{id} API. This will return all config fields, except any fields that you chose to encrypt.

{
  "id": 1,
  "type": "cloud",
  "subtype": "gcp",
  "config": {
    "type": "external_account",
    "audience": "//iam.googleapis.com/projects/684949267137/locations/global/workloadIdentityPools/safe-integration-pool/providers/safe-provider",
    "autoSync": 1,
    "token_url": "https://sts.googleapis.com/v1/token",
    "organizationIds": [
      "your GCP Org ID would be here"
    ],
    "sensitiveFields": [],
    "credential_source": {
      "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials",
      "region_url": "http://169.254.169.254/latest/meta-data/placement/availability-zone",
      "environment_id": "aws1",
      "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"
    },
    "subject_token_type": "urn:ietf:params:aws:token-type:aws4_request",
    "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/safe-service-account@safe-integration-358814.iam.gserviceaccount.com:generateAccessToken"
  },
  "state": {
    "status": 0,
    "newAssets": 290,
    "lastScanTriggerTs": "2022-08-11T11:22:26.260Z",
    "lastScanCompletionTs": "2022-08-11T11:29:50.116Z"
  },
  "isEnabled": true
}

These are all the possible values for the status.

6. Viewing the results in SAFE

After the integration is completed and the first sync and assessment have taken place, SAFE automatically adds the assets from GCP into SAFE. 

To view the result

1. Go to the Risk Scenario page and click the Group Risk Tab.
2. Click the Cloud GCP Risk scenario from the list.
3. The Cloud GCP Risk scenario page displays the breach likelihood trend, actionable insights, ATT&CK mapping, control view, and attack surface view.
   
   

7. Import Labels from Google Cloud Platform (GCP) into SAFE

Refer to Import Labels from Google Cloud Platform (GCP) into SAFE.

8. FAQs

1. Where do I get the GCP organization ID from?

Answer: The easiest way to get this is in the pop-up when you click the dropdown at the top of the GCP portal to change between Organization and Project. In that window, you will see an ID column, and it is that 12-digit number that you need.

2. I lost the WIF file I downloaded. How do I download it again?

Answer: In the GCP portal, navigate to IAM and admin -> Workload Identity Federation. From there, select the pool that you created for SAFE. On the right, click on CONNECTED SERVICE ACCOUNTS. Here you will get the option to DOWNLOAD the Client library config again.

3. What assessment does SAFE perform on the GCP assets?

Answer: SAFE does not perform any native assessment of the GCP assets. SAFE pulls the findings from Security Command Center and maps those to Configuration Assessment controls in SAFE.

4. How does SAFE map the GCP Security Command Centre responses to SAFE control statuses?

Answer: The status mapping is as follows:

• ACTIVE in GCP translates to Failed in SAFE
• INACTIVE in GCP translates to Qualified in SAFE
• If a finding is marked as MUTED in Security Command Center, the corresponding control is marked as Accepted Failed in SAFE.