# Google Cloud
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.**
## 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.
:::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):
{GCPSetupShellScript}
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`
**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`.
:::info
The sample code assumes that you have specified the Google Cloud project ID to create the service account, etc., in the `project` variable defined as follows:
```hcl
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.
:::
{GCPSetupTerraformScript}
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`
Launch Cloud Shell from the terminal button in the upper right corner of the screen. It is the button highlighted in the upper right corner of the following image:
After clicking and waiting for a while, Cloud Shell will start up as shown below, and the `gcloud` command will be available:
**After changing the value in the `# ID of the Shisho Cloud organization you created` section at the beginning appropriately**, copy and paste the following script into the Cloud Shell and execute it to create the necessary resources (ID provider and IAM roles):
{GCPSetupWebShellScript}
After 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@.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](https://console.cloud.google.com/welcome).
## 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](https://cloud.google.com/iam/docs/understanding-roles).
:::
After checking the value in the **Input values** section, you can grant permission to the service account by running the following command:
{GCPSetupShellTwoScript}
When setting roles in Terraform, you can grant roles with the `google_project_iam_member` resource as follows:
{GCPSetupTerraformTwoScript}
Open the [IAM & Admin console](https://console.cloud.google.com/iam-admin/iam), and if the project selector is displayed, **select the project (or folder/organizational unit) you want to inspect**.
If it is not displayed, after the screen opens, **select the project (or folder/organizational unit) you want to inspect** from the part where the project name is displayed at the top of the screen.
Then, you will see a screen like the one below:
Then click the "Grant Access" button.
Then, you will see a screen like the one below:
After entering the following in the displayed screen, press the "Save" button:
- New principals: The address of the service account you created (e.g., `shisho-cloud@.iam.gserviceaccount.com`; if you used Cloud Shell or gcloud CLI when "Creating a Service Account", the value displayed after `Service Account Email:`)
- Role: All of the following roles
- `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)
### 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:
{GCPSetupShellTwoOrgScript}
When setting roles in Terraform, you can grant roles with the `google_organization_iam_member` resource, as follows:
{GCPSetupTerraformTwoOrgScript}
After opening the [IAM & Admin console](https://console.cloud.google.com/iam-admin/iam), click the project name (next to the Google Cloud logo) at the top of the screen.
Then, you will see the following project, folder, and organization selector:
Then, if you select the "All" tab, you will be able to see the organization name (in the example image, `flatt.tech`) and folder names that group your company's Google Cloud projects.
If you want to inspect the entire organization with Shisho Cloud, click the organization name (in the example image, `flatt.tech`).
Then, if your Google Cloud account has sufficient privileges to configure organization settings (such as Google Workspace or Cloud Identity administrator roles), you will see a screen like the one below:
Then click the "Grant Access" button.
Then, you will see a screen like the one below:
After entering the following in the displayed screen, press the "Save" button:
- New principals: The address of the service account you created (e.g., `shisho-cloud@.iam.gserviceaccount.com`; if you used Cloud Shell or gcloud CLI when "Creating a Service Account and Related Resources," the value displayed after `Service Account Email:`)
- Role: All four of the following roles
- `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)
## 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 :gear: > 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](https://cloud.google.com/iam/docs/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](https://github.blog/changelog/2021-10-27-github-actions-secure-cloud-deployments-with-openid-connect/).
### 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.