GCP Hosted Cloud Connector

Access Levels: | Advanced | Enterprise

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 four hours.

To see the latest refresh time in Censys ASM:

Go to the ASM web console and click Integrations.
Scroll down to see the date within the Cloud Service Provider cards.

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:
- In GCP, navigate to the API Console.
- Select a project or create a new one.
- On the left menu, click APIs & Services > Library.
- Search for Cloud Asset API, then select the result for Cloud Asset API.
- 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 ASM UI

Step 1: Configure the integration in Censys

Log in to ASM web console, then click Integrations at the top of the page.
Locate GCP and click Set Up.
In the setup wizard, configure the following:
1. Project ID: Enter your Project ID where you want to create a service account.
2. If you are using a standalone GCP Project:
  1. Select Project ID and enter the ID of the project where you want to create a service account.
3. If you are using a GCP Organization:
  1. Select Organization ID and enter the ID of the project where you want to create a service account.
4. Excluded Fields: You can optionally enter any service types or Projects you wish to exclude from being sent to Censys ASM.
  1. Click Next Step.
5. 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

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.
Click Create Service Account at the top of the page.
Paste in the service account name from your Censys ASM. The service account ID will automatically be filled in. Optionally, add a description.
Click Create and Continue.
Under Grant users access to this service account, click Done.
In GCP, locate the service account you just created. Click on its name to view the service account details.
Click the Permissions tab, then click Grant Access.
In the field under Add principals, paste in the Censys Service Principal.
1. The Service Principal can be found on the Cloud Connector configuration page in Censys ASM.
Under Assign roles, select Service Account Token Creator.
Click Add another role. Select Service account user.
Click Save.
At the top of GCP, click the dropdown menu to navigate to your organization.
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

Go to the ASM web console and click Next Step > Done.

Option 2: Configuring the Cloud Connector via the Censys API

Step 1: Create the hosted connector using Censys API

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.
1. 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.
2. 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.
3. For examples, see the JSON section below.
When your JSON body is ready, create a new hosted connector using the Censys Hosted Connectors API endpoint.
1. Go 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.
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

Log in to your GCP admin console and navigate to the Project where you want to create your Service Account.
Go to IAM and Admin for the project.
Click + Create Service Account.
For the Service Account Name, paste in the value from the Censys API response body's serviceAccountEmail.
Click Done.
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 [email protected] as the new principal.
4. Assign the following roles:
  1. Service Account Token Creator
  2. Service Account User
5. Click Save.
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 one

This example has one 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"
    }
}

Example two

This example has two scopes. The first scope includes all asset types for all projects except reliable-corner-98765 contained within the GCP Organization. The second scope is to scan project reliable-corner-98765, excluding the Container Cluster asset type.

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