Google Cloud
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 two steps:
- Create a service account that Shisho Cloud can use (impersonate) and the associated resources.
- Grant the created service account the privileges required to perform security inspections on the Google Cloud project.
- Register the information of the created service account and related resources with Shisho Cloud.
Shisho Cloud does not require a service account key, but instead accesses Google Cloud by issuing short-lived credentials as needed through Workload Identity Federation. This is roughly equivalent to the OIDC-based Google Cloud/Google Cloud integration mechanism provided by GitHub Action.
Creation of the Service Account and Related Resources
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.
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.
- gcloud CLI
- Terraform
After changing the values in the # Input values
section appropriately, run the following script to create the necessary resources (ID providers 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}"
Upon completion, the following should have been created:
- A service account named
shisho-cloud
- An identity provider named
shisho-cloud
- An identity pool named
shisho-cloud
After changing the value of variable shisho_cloud_org_id
to the ID of your Shisho Cloud organization, include the following Terraform implementation in your Terraform project and then run terraform apply
.
The sample code assumes that you have specified the Google Cloud project ID for the project
variable, which has been defined as follows:
variable "project" {
type = string
}
If such a variable is defined under a different name, please replace the references to var.project
in the sample code as needed.
If such a variable is not defined, set the GOOGLE_PROJECT
environment variable and either use the sample code after removing var.project
or replace var.project
directly with the project ID.
locals {
# Please change the following to your Shisho Cloud organization ID:
shisho_cloud_org_id = "your-shisho-organization-id"
}
# Ensure to enable APIs that needs to be enabled on the project that includes the service account to integrate with Shisho Cloud.
resource "google_project_service" "bigquery" {
project = var.project
service = "bigquery.googleapis.com"
}
resource "google_project_service" "cloudasset" {
project = var.project
service = "cloudasset.googleapis.com"
}
resource "google_project_service" "cloudkms" {
project = var.project
service = "cloudkms.googleapis.com"
}
resource "google_project_service" "resourcemanager" {
project = var.project
service = "cloudresourcemanager.googleapis.com"
}
resource "google_project_service" "compute" {
project = var.project
service = "compute.googleapis.com"
}
resource "google_project_service" "container" {
project = var.project
service = "container.googleapis.com"
}
resource "google_project_service" "dns" {
project = var.project
service = "dns.googleapis.com"
}
resource "google_project_service" "essentialcontacts" {
project = var.project
service = "essentialcontacts.googleapis.com"
}
resource "google_project_service" "logging" {
project = var.project
service = "logging.googleapis.com"
}
resource "google_project_service" "iamcredentials" {
project = var.project
service = "iamcredentials.googleapis.com"
}
resource "google_project_service" "iam" {
project = var.project
service = "iam.googleapis.com"
}
resource "google_project_service" "pubsub" {
project = var.project
service = "pubsub.googleapis.com"
}
resource "google_project_service" "serviceusage" {
project = var.project
service = "serviceusage.googleapis.com"
}
resource "google_project_service" "storage-component" {
project = var.project
service = "storage-component.googleapis.com"
}
resource "google_project_service" "sqladmin" {
project = var.project
service = "sqladmin.googleapis.com"
}
# Create a service account
resource "google_service_account" "shisho_cloud" {
project = var.project
account_id = "shisho-cloud"
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."
}
# Create an identity pool
resource "google_iam_workload_identity_pool" "shisho_cloud" {
project = var.project
workload_identity_pool_id = "shisho-cloud"
description = "An identity pool for Shisho Cloud audit jobs. Visit https://shisho.dev/docs/ja/g/getting-started/integrate-apps/googlecloud for further details."
}
# Create an identity provider
resource "google_iam_workload_identity_pool_provider" "shisho_cloud" {
project = var.project
workload_identity_pool_provider_id = "shisho-cloud"
workload_identity_pool_id = google_iam_workload_identity_pool.shisho_cloud.workload_identity_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."
oidc {
issuer_uri = "https://tokens.cloud.shisho.dev"
}
attribute_mapping = {
"google.subject" = "assertion.sub"
"attribute.organization_id" = "assertion.organization_id"
"attribute.workflow_id" = "assertion.workflow_id"
"attribute.job_id" = "assertion.job_id"
}
# Limit the scope of the service account to only be able to access the
attribute_condition = "attribute.organization_id == '${local.shisho_cloud_org_id}'"
}
# Grant the identity from the identity provider to impersonate the service account
resource "google_service_account_iam_member" "shisho_cloud_iam_workload_identity_user" {
service_account_id = google_service_account.shisho_cloud.id
role = "roles/iam.workloadIdentityUser"
member = "principalSet://iam.googleapis.com/${google_iam_workload_identity_pool.shisho_cloud.name}/*"
}
Upon completion, the following should have been created:
- 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 script as it is.
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 can typically be a 12-digit number and can be found at 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.
Granting Privileges on 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 set access rights to Shisho Cloud for selected projects. In such cases, refer to the following code sample and grant the created service account the following roles for the corresponding 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)
The roles granted here basically allow only reading of resource configuration values and do not generally include permission to view data within data storage (Cloud Storage, Cloud SQL, etc). To check the detailed permissions included in the roles, refer to the Google Cloud official documentation.
- gcloud CLI
- Terraform
After checking the input values, the following commands can be executed to complete the granting of privileges to the service account:
#!/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"
Terraform でロールを設定する場合には、以下のように google_project_iam_member
リソースでロールを付与できます:
// Assuming:
// resource "google_service_account" "shisho_cloud" {
// project = var.project
// account_id = "shisho-cloud"
// 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."
// }
resource "google_project_iam_member" "shisho_cloud_project_security" {
project = var.project
role = "roles/iam.securityReviewer"
member = "serviceAccount:${google_service_account.shisho_cloud.email}"
}
resource "google_project_iam_member" "shisho_cloud_project_bigquery" {
project = var.project
role = "roles/bigquery.metadataViewer"
member = "serviceAccount:${google_service_account.shisho_cloud.email}"
}
resource "google_project_iam_member" "shisho_cloud_org_policy" {
project = var.project
role = "roles/orgpolicy.policyViewer"
member = "serviceAccount:${google_service_account.shisho_cloud.email}"
}
resource "google_project_iam_member" "shisho_cloud_browser" {
project = var.project
role = "roles/browser"
member = "serviceAccount:${google_service_account.shisho_cloud.email}"
}
resource "google_project_iam_member" "shisho_cloud_access_approval" {
project = var.project
role = "roles/accessapproval.viewer"
member = "serviceAccount:${google_service_account.shisho_cloud.email}"
}
resource "google_project_iam_member" "shisho_cloud_firebase_auth" {
project = var.project
role = "roles/firebaseauth.viewer"
member = "serviceAccount:${google_service_account.shisho_cloud.email}"
}
resource "google_project_iam_member" "shisho_cloud_service_usage" {
project = var.project
role = "roles/serviceusage.serviceUsageConsumer"
member = "serviceAccount:${google_service_account.shisho_cloud.email}"
}
Granting Privileges on a Folder/Organization
If you want Shisho Cloud to protect all projects in a folder or in a Google Cloud Organization, please grant the following roles for the folder/organization to the service account you have 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)
You can use gcloud
CLI or Terraform as well as the single project.
Registering the Service Account to Shisho Cloud
You've successfully completed the configuration of the service account. As a final step, please click the "Settings" button for the "Google Cloud" card displayed on the "⚙ > Integrations" screen. Then follow the on-screen instructions to enter the necessary information.
When you have completed the step, the service account should appear on the settings page with a check mark like the following:
Due to the cache behavior of Google Cloud, Shisho Cloud may not be able to access Google Cloud for a few minutes after the integration. Please wait one-two hours without removing service account settings and visit the dashboard again.
If you are unable to successfully integrate Google Cloud by following the above steps, please feel free to contact the service provider (Flatt Security).