Overview

The Censys Cloud Connector for Google Cloud Platform (GCP) enumerates your cloud environment, ensuring that Censys Attack Surface Management (ASM) is always up to date so your security teams are working with the most current data. This integration consults a single API to find all public assets.

Data refresh frequency

Cloud Connectors refresh more often than other connections. After you set up Cloud Connectors, your data will refresh as often as every 4 hours. 

To see the latest refresh time in Censys ASM, click Integrations in the top navigation menu, then view the date within the Cloud Service Provider cards.

How to configure the Censys Cloud Connector for GCP

There are two options for configuring Censys Cloud Connectors for GCP: using the Censys ASM UI, or via the Censys API.

Prerequisites

You will need the following before you get started:

• The name of the GCP project where the Service Account will be created
• The Organization IDs and/or Project IDs you wish to use
• Cloud Asset API in GCP enabled
  • To enable Cloud Asset API:
    1. In GCP, navigate to the API Console.
    2. Select a project or create a new one.
    3. In the left menu, click APIs & Services > Library.
    4. Search for "Cloud Asset API," then select the result for Cloud Asset API.
    5. Click Enable.
• Optionally, you may need:
  • A list of accounts or services you wish to exclude from being sent to Censys ASM

The following users and permissions are required:

• Censys ASM user with the workspace role "Manager"
• GCP Admin with the following privileges:
  • Ability to create a Service Account
  • Permissions to grant IAM Access at the organization level

These are the least privileged permissions required to access your cloud resources and import them into Censys.

Option 1: Configuring the Cloud Connector in the Censys UI

Step 1: Configure the integration in Censys

1. Log in to Censys ASM, then click Integrations at the top of the page.

2. Locate GCP and click Set Up. 

3. In the setup wizard, configure the following:

   • Project ID: Enter your Project ID where you want to create a service account.

   • If you are using a standalone GCP Project:
     • Select Project ID and enter the ID of the project where you want to create a service account.
   • If you are using a GCP Organization: 
     
     • Select Organization ID and enter the ID of the project where you want to create a service account.
   • Excluded Fields: Optionally, enter any service types or Projects you wish you exclude from being sent to Censys ASM.

4. Click Next Step.

   • On the next page, your Service Account Name and Principal are displayed. You will need these in the next steps.

Step 2: Configure the role in GCP

1. Log in to your GCP admin console. Use the resource selector to switch to the project where your service account will be created, then navigate to IAM & Admin > Service Accounts.
   

2. Click +Create Service Account at the top of the page.
   
3. Paste in the service account name from your Censys ASM. The service account ID will automatically fill in. Optionally, add a a description. Click Create and Continue.
4. Under "Grant users access to this service account" click Done. 
5. In GCP, locate the service account you just created. Click on its name to view the service account details.
6. Click the Permissions tab, then click Grant Access.
7. In the field under "Add principals," paste in the Censys Service Principal. 
   • The Service Principal can be found on the Cloud Connector configuration page in Censys ASM.
8. Under "Assign roles," select Service Account Token Creator.
9. Click +Add another role. Select Service account user.
   
10. Click Save.
11. At the top of GCP, click the dropdown to navigate to your organization.
12. For each Organization and Project provided as a scope, grant your new Service Account access:
    1. At the top of GCP, click the dropdown to navigate to the Organization or Project, then navigate to IAM > Permissions.
    2. At the bottom of the page, click +Grant access.
    3. Under "Add principals," paste the value of the Service Account Name.
    4. Under "Assign roles," select the Cloud Asset Viewer role.
    5. Click Save.

Step 3: Finish configuration in Censys

1. Navigate back to Censys ASM.
2. Click Next Step, then click Done.

Option 2: Configuring the Cloud Connector via the Censys API

Step 1: Creating the hosted connector using Censys API

1. Craft a JSON body with the appropriate scopes describing how you want the Hosted Cloud Connector to scan your AWS environments. Any combination of Organizations and standalone accounts is acceptable.
   • To include a GCP Organization, provide the Organization ID, the ID of the project where you want to create a Service Account, and any optional Project or service type exclusions.
   • To include a standalone GCP Project, provide the Project ID, the ID of the project where you want to create a Service Account, and any optional service type exclusions.
   • For examples, see the JSON Examples section below.
2. When your JSON body is ready, create a new hosted connector using the Censys Hosted Connectors API endpoint.
   1. Navigate to the Integrations Marketplace.
   2. Copy your API Key to your clipboard.
   3. Follow the link to API Documentation.
   4. Click Authorize and paste in your API key. Click Authorize > Close.
   5. Expand the hosted connectors header to expose the Hosted Connector endpoints.
   6. Expand the POST /v1/hosted-connectors endpoint.
      1. Click Try it out, then replace the example value with your own JSON body.
      2. Click Execute.
3. Censys will return a response body that includes a serviceAccountEmail. In the next step, you will create a Service Account using this email.

Step 2: Create a service account in GCP and grant permissions

1. Log in to your GCP admin console and navigate to the Project where you want to create your Service Account. 
2. Navigate to IAM and Admin for the project.
3. Click +Create Service Account.
4. For the Service Account Name, paste in the value from the Censys API response body's serviceAccountEmail.
5. Click Done.
6. Grant the Censys Service Account access to the new Service Account.
   1. Select the Service Account you just created, then click Permissions.
   2. Click Grant Access.
   3. Paste in censys-hosted-cc@censys-cc.iam.gserviceaccount.com as the new principal.
   4. Assign the following roles:

      • Service Account Token Creator

      • Service Account User
   5. Click Save.
7. For each Organization and Project provided as a scope, grant your new Service Account access.
   1. Navigate to the Organization or Project, then navigate to IAM.
   2. Click +Grant access.
   3. Paste the value of serviceAccountEmail as the new principal.
   4. Assign the Cloud Asset Viewer role.
   5. Click Save.

JSON Examples

Example 1

This example has 1 scope that includes all asset types, for all projects contained within the GCP Organization.

{
    "gcp": {
        "scopes": [
            {
                "organization": {
                    "organizationId": "123456789012",
                    "excludedProjects": []
                },
                "excludedAssetTypes": []
            }
        ],
        "serviceAccountProject": "series-stumble-45632"
    }
}

{
    "gcp": {
        "scopes": [
            {
                "organization": {
                    "organizationId": "123456789012",
                    "excludedProjects": [
                        "reliable-corner-98765"
                    ]
                },
                "excludedAssetTypes": []
            },
            {
                "project": {
                    "projectId": "reliable-corner-98765"
                },
                "excludedAssetTypes": [
                    "CONTAINER_CLUSTER"
                ]
            }
        ],
        "serviceAccountProject": "series-stumble-45632"
    }
}