Skip to main content

Google Cloud

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

By integrating Shisho Cloud and Google Cloud, you can perform security scans on your Google Cloud projects and organizations. This integration can be done in the following three steps:

  1. Create a service account that Shisho Cloud can impersonate and the associated resources.
  2. Grant the created service account the necessary permissions to perform security inspections on the Google Cloud project.
  3. Register the information of the created service account and related resources with Shisho Cloud.

First, create a service account, identity pool, and identity provider in any Google Cloud project for use from Shisho Cloud, following one of the procedures below.

info

Even if you want to inspect multiple Google Cloud projects, this process only needs to be done once. That is, you only need one service account, identity pool, and identity provider for Shisho Cloud.

After changing the values in the # Input values section at the beginning of the script appropriately, run the following script to create the necessary resources (ID provider and IAM roles):

#!/bin/bash

set -eu

# Input values
############

# Google Cloud Project ID
PROJECT_ID="your-google-cloud-project-id"

# Shisho Cloud Organization ID
SHISHO_ORG_ID="you-shisho-organization-id"

# ID of the identity pool to be created; no need to change unless there's a specific reason
POOL_ID="shisho-cloud"

# ID of the identity provider to be created; no need to change unless there's a specific reason
PROVIDER_ID="shisho-cloud"

# Name of the service account to be created; no need to change unless there's a specific reason
SERVICE_ACCOUNT_NAME="shisho-cloud"

# Creation
############

TOKEN_ENDPOINT_URL="https://tokens.cloud.shisho.dev"
PROJECT_NUMBER="$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")"

# Ensure to enable APIs that needs to be enabled on the project that includes the service account to integrate with Shisho Cloud.
gcloud services enable \
bigquery.googleapis.com \
cloudasset.googleapis.com \
cloudkms.googleapis.com \
cloudresourcemanager.googleapis.com \
compute.googleapis.com \
container.googleapis.com \
dns.googleapis.com \
essentialcontacts.googleapis.com \
logging.googleapis.com \
iamcredentials.googleapis.com \
iam.googleapis.com \
pubsub.googleapis.com \
serviceusage.googleapis.com \
storage-component.googleapis.com \
sqladmin.googleapis.com \
--project "$PROJECT_ID"


# Create a Workload Identity Pool & Provider
gcloud iam workload-identity-pools create "$POOL_ID" \
--project="$PROJECT_ID" \
--description="An identity pool for Shisho Cloud audit jobs. Visit https://shisho.dev/docs/ja/g/getting-started/integrate-apps/googlecloud for further details." \
--location=global \
--display-name="$POOL_ID"

gcloud iam workload-identity-pools providers create-oidc "$PROVIDER_ID" \
--project="$PROJECT_ID" \
--location="global" \
--workload-identity-pool="$POOL_ID" \
--description="An identity provider for Shisho Cloud audit jobs. Visit https://shisho.dev/docs/ja/g/getting-started/integrate-apps/googlecloud for further details." \
--display-name="$PROVIDER_ID" \
--attribute-mapping="google.subject=assertion.sub,attribute.organization_id=assertion.organization_id,attribute.workflow_id=assertion.workflow_id,attribute.job_id=assertion.job_id" \
--attribute-condition="assertion.organization_id == '$SHISHO_ORG_ID'" \
--issuer-uri="$TOKEN_ENDPOINT_URL"

# Create a service account that can be impersonated IDs in the pool
gcloud iam service-accounts create "$SERVICE_ACCOUNT_NAME" \
--description="A service account that Shisho Cloud impersonates and use for listing up projects, resources, and their settings. Visit https://shisho.dev/docs/ja/g/getting-started/integrate-apps/googlecloud for further details." \
--project "$PROJECT_ID"

gcloud iam service-accounts add-iam-policy-binding "$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
--project="$PROJECT_ID" \
--role="roles/iam.workloadIdentityUser" \
--member="principalSet://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/*"

# Post-processing
echo "Visit https://cloud.shisho.dev/${SHISHO_ORG_ID}/settings/integrations/googlecloud and add a federation with:"
echo "- Service Account Email: ${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
echo "- Pool Project Number: ${PROJECT_NUMBER}"
echo "- Pool ID: ${POOL_ID}"
echo "- Provider ID: ${PROVIDER_ID}"

After the execution is complete, information about the following created resources will be output after Visit https://cloud.shisho.dev .... Please keep this information for use in the later step "Registering information to Shisho Cloud".

  • A service account named shisho-cloud
  • An identity provider named shisho-cloud
  • An identity pool named shisho-cloud

Once the service account is created, make note of the created service account's email address. The email address should look something like shisho-cloud@<project-name>.iam.gserviceaccount.com if you used the above scripts as they are.

Also, along with the service account's email address, please note the project number of the Google Cloud project where you created the service account and related resources. This is typically a 12-digit number and can be found on the welcome page of the Google Cloud console.

Granting Privileges to the Service Account

At this point, you are almost ready for Shisho Cloud to use the Google Cloud service account. Next, let's grant the service account the access rights to the actual targets you want to conduct security scans on.

If you want to manage the security of a single project

There may be cases where, instead of continuously inspecting an entire Google Cloud organization or folder with Shisho Cloud, you want to select projects and set access rights to Shisho Cloud for them. In this case, refer to the following code sample and grant the created service account the following roles for that project:

  • roles/iam.securityReviewer (Security Reviewer)
  • roles/bigquery.metadataViewer (BigQuery Metadata Viewer)
  • roles/orgpolicy.policyViewer (Organization Policy Viewer)
  • roles/browser (Browser)
  • roles/accessapproval.viewer (Access Approval Viewer)
  • roles/firebaseauth.viewer (Firebase Authentication Viewer)
  • roles/serviceusage.serviceUsageConsumer (Service Usage Consumer)
  • roles/compute.viewer (Compute Viewer)
info

The roles granted here basically allow you to read only the configuration values of resources, and in principle, do not include permission to view data in data storage (Cloud Storage, Cloud SQL, etc.). However, the compute.viewer role exceptionally includes access to VM screenshots and serial port output. If this is not desired, you can choose not to grant the permission, but some features may not work. If you want to check the detailed permissions included in a role, please refer to the Google Cloud official documentation.

After checking the value in the Input values section, you can grant permission to the service account by running the following command:

#!/bin/bash

set -eu

# Input values
############

# Google Cloud Project ID where the created service account resides
PROJECT_ID="your-google-cloud-project-id"

# Service account name you created; leave as is if you ran the above script as is
SERVICE_ACCOUNT_NAME="shisho-cloud"

# Grant permissions
############
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--role="roles/iam.securityReviewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--role="roles/bigquery.metadataViewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--role="roles/orgpolicy.policyViewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--role="roles/browser" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--role="roles/accessapproval.viewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--role="roles/firebaseauth.viewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--role="roles/serviceusage.serviceUsageConsumer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

If you want to manage the security of a folder or the entire Google Cloud organization

If you want Shisho Cloud to protect all projects in a folder or all projects included in your Google Cloud organization, grant the following roles for that folder/organization to the service account you created:

  • roles/iam.securityReviewer (Security Reviewer)
  • roles/bigquery.metadataViewer (BigQuery Metadata Viewer)
  • roles/orgpolicy.policyViewer (Organization Policy Viewer)
  • roles/browser (Browser)
  • roles/accessapproval.viewer (Access Approval Viewer)
  • roles/firebaseauth.viewer (Firebase Authentication Viewer)
  • roles/serviceusage.serviceUsageConsumer (Service Usage Consumer)
  • roles/compute.viewer (Compute Viewer)

You can grant roles from the gcloud CLI, Terraform, or the web console, just like "If you want to manage the security of a single project."

For example, if you want to grant permissions at the organizational unit level, you can do the following:

After checking the value in the Input Values section, you can grant permissions to the service account to your Google Cloud organization by running the following command:

#!/bin/bash

set -eu

# 入力値
############

# Google Cloud Project ID where the created service account resides
PROJECT_ID="your-google-cloud-project-id"

# Google Cloud Organization ID to review
# It should come from `gcloud organizations list`.
ORGANIZATION_ID="000000000000"

# Service account name you created; leave as is if you ran the above script as is
SERVICE_ACCOUNT_NAME="shisho-cloud"

# Grant permissions
############
gcloud organizations add-iam-policy-binding "$ORGANIZATION_ID" \
--role="roles/iam.securityReviewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud organizations add-iam-policy-binding "$ORGANIZATION_ID" \
--role="roles/bigquery.metadataViewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud organizations add-iam-policy-binding "$ORGANIZATION_ID" \
--role="roles/orgpolicy.policyViewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud organizations add-iam-policy-binding "$ORGANIZATION_ID" \
--role="roles/browser" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud organizations add-iam-policy-binding "$ORGANIZATION_ID" \
--role="roles/accessapproval.viewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud organizations add-iam-policy-binding "$ORGANIZATION_ID" \
--role="roles/firebaseauth.viewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud organizations add-iam-policy-binding "$ORGANIZATION_ID" \
--role="roles/serviceusage.serviceUsageConsumer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud organizations add-iam-policy-binding "$ORGANIZATION_ID" \
--role="roles/compute.viewer" \
--condition=None \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com"

Registering Information to Shisho Cloud

In the steps so far, you have completed setting up the service account that Shisho Cloud will use during the inspection, as well as the service account's access rights. Finally, click the "Settings" button on the "Google Cloud" card displayed on the "Gear icon > Integrations" screen, and enter the necessary information by following the on-screen instructions. If you set up with the gcloud CLI (including using it on Cloud Shell), you will mainly need the values (1) - (4) output after the script execution.

When you have completed the input, the service account should appear on the setting page with a check mark, like the following:

If you see this, the Google Cloud integration setup is complete. Shisho Cloud is now able to access your Google Cloud account!

info

Due to Google Cloud's caching specifications, Shisho Cloud may not be able to access Google Cloud for a few minutes after integration. If the configuration is not completed immediately, please wait up to 5 minutes.

warning

If you are unable to successfully integrate Google Cloud by following the above steps, please feel free to contact the service provider (Flatt Security).

Reference: Technical Details of Google Cloud Integration

The setup procedure described above uses Google Cloud's Workload Identity Federation feature, along with service accounts. Workload Identity Federation is a framework for granting external identities the authority to act as service accounts on Google Cloud.

Shisho Cloud takes advantage of this framework to retrieve configuration settings for Google Cloud resources without a service account key. This is roughly equivalent to the mechanism of OIDC-based Google Cloud/Google Cloud integration that GitHub Actions has.

Functions and Concepts Setup

Of this framework, two functions/concepts are actually used to have Shisho Cloud perform security scans:

  • Workload Identity Pool
  • Workload Identity Provider

In the setup procedure described above, we first prepared a Workload Identity Pool. This is to associate external identities (external from Google's point of view, here the identity representing the workflow execution on Shisho Cloud) with principals within Google Cloud.

A Workload Identity Provider was then registered with the Workload Identity Pool. This is used to map and verify information (such as ID tokens) representing external identities with identities within the Workload Identity Pool. In the case of Shisho Cloud, since an ID token is issued for each workflow execution, the Workflow Identity Provider created is configured to associate that token with a principal on Google Cloud.

Flow of Access to the Google Cloud Environment

When Shisho Cloud actually tries to access Google Cloud, Shisho Cloud sends the ID token it issued to the Security Token Service API (STS) that Google Cloud has. The STS that received the ID token verifies the token.

One of the validations performed here is the verification of the JWT signature. The public key required for verification is provided at Shisho Cloud's JWKs endpoint, which is registered during the Workload Identity Federation configuration process.

The verification also verifies the information (claims) in the JWT payload. This is based on the mapping information and verification logic registered with the Workload Identity Pool Provider.

If the above verification is successful, the STS returns a short-lived access token to Google Cloud to Shisho Cloud. Shisho Cloud then passes this access token to the IAM API to request another access token to act as a service account. In the setup procedure described above, we granted the service account the Workload Identity User role, which is the setting to allow such requests.

Finally, Shisho Cloud obtains an access token with the authority to act as a service account. In the setup procedure described above, we granted the service account roles such as roles/iam.securityReviewer, so Shisho Cloud is now able to read the configuration settings of Google Cloud resources.