ben.carrasco/prowler
1
0
Fork 0
mirror of https://github.com/prowler-cloud/prowler.git synced 2026-07-24 13:01:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(gcp): refactor getting started and auth (#8758)

Browse Source
This commit is contained in:
Andoni Alonso
2025-09-25 10:19:01 +02:00
committed by GitHub
parent 56821de2f4
commit d13f3f0e0c
3 changed files with 181 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tutorials/gcp/authentication.md
+100 -22
View File
@@ -1,5 +1,12 @@
# GCP Authentication in Prowler
Prowler for Google Cloud supports multiple authentication methods. To use a specific method, configure the appropriate credentials during execution:
- [**User Credentials** (Application Default Credentials)](#application-default-credentials-user-credentials)
- [**Service Account Key File**](#service-account-key-file)
- [**Access Token**](#access-token)
- [**Service Account Impersonation**](#service-account-impersonation)
## Required Permissions
Prowler for Google Cloud requires the following permissions:
@@ -33,28 +40,92 @@ At least one project must have the following configurations:
```
???+ note
`prowler` will scan the GCP project associated with the credentials.
## Credentials lookup order
Prowler follows the same credential search process as [Google authentication libraries](https://cloud.google.com/docs/authentication/application-default-credentials#search_order), checking credentials in this order:
1. [`GOOGLE_APPLICATION_CREDENTIALS` environment variable](https://cloud.google.com/docs/authentication/application-default-credentials#GAC)
2. [`CLOUDSDK_AUTH_ACCESS_TOKEN` + optional `GOOGLE_CLOUD_PROJECT`](https://cloud.google.com/sdk/gcloud/reference/auth/print-access-token)
3. [User credentials set up by using the Google Cloud CLI](https://cloud.google.com/docs/authentication/application-default-credentials#personal)
4. [Attached service account (e.g., Cloud Run, GCE, Cloud Functions)](https://cloud.google.com/docs/authentication/application-default-credentials#attached-sa)
???+ note
The credentials must belong to a user or service account with the necessary permissions.
To ensure full access, assign the roles/reader IAM role to the identity being used.
???+ note
Prowler will use the enabled Google Cloud APIs to get the information needed to perform the checks.
Prowler will scan the GCP project associated with the credentials.
## Application Default Credentials (User Credentials)
This method uses the Google Cloud CLI to authenticate and is suitable for development and testing environments.
## Using an Access Token
### Setup Application Default Credentials
1. In the [GCP Console](https://console.cloud.google.com/), click on "Activate Cloud Shell"
![Activate Cloud Shell](./img/access-console.png)
2. Click "Authorize Cloud Shell"
![Authorize Cloud Shell](./img/authorize-cloud-shell.png)
3. Run the following command:
```bash
gcloud auth application-default login
```
- Type `Y` when prompted
![Run Gcloud Auth](./img/run-gcloud-auth.png)
4. Open the authentication URL provided in a browser and select your Google account
![Choose the account](./img/take-account-email.png)
5. Follow the steps to obtain the authentication code
![Copy auth code](./img/copy-auth-code.png)
6. Paste the authentication code back in Cloud Shell
![Enter Auth Code](./img/enter-auth-code.png)
7. Use `cat <file_name>` to view the temporary credentials file
![Get the FileName](./img/get-temp-file-credentials.png)
8. Extract the following values for Prowler Cloud/App:
- `client_id`
- `client_secret`
- `refresh_token`
![Get the values](./img/get-needed-values-auth.png)
### Using with Prowler CLI
Once application default credentials are set up, run Prowler directly:
```console
prowler gcp --project-ids <project-id>
```
## Service Account Key File
This method uses a service account with a downloaded key file for authentication.
### Create Service Account and Key
1. Go to the [Service Accounts page](https://console.cloud.google.com/iam-admin/serviceaccounts) in the GCP Console
2. Click "Create Service Account"
3. Fill in the service account details and click "Create and Continue"
4. Grant the service account the "Reader" role
5. Click "Done"
6. Find your service account in the list and click on it
7. Go to the "Keys" tab
8. Click "Add Key" > "Create new key"
9. Select "JSON" and click "Create"
10. Save the downloaded key file securely
### Using with Prowler CLI
Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable:
```console
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
prowler gcp --project-ids <project-id>
```
## Access Token
For existing access tokens (e.g., generated with `gcloud auth print-access-token`), run Prowler with:
@@ -69,10 +140,7 @@ prowler gcp --project-ids <project-id>
export GOOGLE_CLOUD_PROJECT=<project-id>
```
## Impersonating a GCP Service Account
## Service Account Impersonation
To impersonate a GCP service account, use the `--impersonate-service-account` argument followed by the service account email:
@@ -81,3 +149,13 @@ prowler gcp --impersonate-service-account <service-account-email>
```
This command leverages the default credentials to impersonate the specified service account.
### Prerequisites for Impersonation
The identity running Prowler must have the following permission on the target service account:
- `roles/iam.serviceAccountTokenCreator`
Or the more specific permission:
- `iam.serviceAccounts.generateAccessToken`
docs/tutorials/gcp/getting-started-gcp.md
+79 -63
View File
@@ -1,105 +1,121 @@
# Getting Started with GCP on Prowler Cloud/App
# Getting Started With GCP on Prowler
Set up your GCP project to enable security scanning using Prowler Cloud/App.
## Prowler App
## Requirements
To configure your GCP project, you’ll need:
1. Get the `Project ID`
2. Access to Prowler Cloud/App
3. Configure authentication in GCP:
3.1 Retrieve credentials from Google Cloud
4. Add the credentials to Prowler Cloud/App
---
## Step 1: Get the Project ID
### Step 1: Get the GCP Project ID
1. Go to the [GCP Console](https://console.cloud.google.com/)
2. Locate your Project ID on the welcome screen
2. Locate the Project ID on the welcome screen
![Get the Project ID](./img/project-id-console.png)
---
### Step 2: Access Prowler Cloud or Prowler App
## Step 2: Access Prowler Cloud/App
1. Go to [Prowler Cloud](https://cloud.prowler.com/) or launch [Prowler App](../prowler-app.md)
2. Navigate to `Configuration` > `Cloud Providers`
1. Navigate to [Prowler Cloud](https://cloud.prowler.com/) or launch [Prowler App](../prowler-app.md)
2. Go to "Configuration" > "Cloud Providers"
![Cloud Providers Page](../img/cloud-providers-page.png)
3. Click `Add Cloud Provider`
3. Click "Add Cloud Provider"
![Add a Cloud Provider](../img/add-cloud-provider.png)
4. Select `Google Cloud Platform`
4. Select "Google Cloud Platform"
![Select GCP](./img/select-gcp.png)
5. Add the Project ID and optionally provide a provider alias, then click `Next`
5. Add the Project ID and optionally provide a provider alias, then click "Next"
![Add Project ID](./img/add-project-id.png)
---
### Step 3: Set Up GCP Authentication
## Step 3: Configure Authentication in GCP
Choose the preferred authentication mode before proceeding:
### Retrieve Credentials from Google Cloud
**User Credentials (Application Default Credentials)**
1. In the [GCP Console](https://console.cloud.google.com/), click on `Activate Cloud Shell`
* Quick scan as current user
* Uses Google Cloud CLI authentication
* Credentials may time out
![Activate Cloud Shell](./img/access-console.png)
**Service Account Key File**
2. Click `Authorize Cloud Shell`
* Authenticates as a service identity
* Stable and auditable
* Recommended for production
![Authorize Cloud Shell](./img/authorize-cloud-shell.png)
For detailed instructions on how to set up authentication, see [Authentication](./authentication.md).
3. Run the following command:
6. Once credentials are configured, return to Prowler App and enter the required values:
```bash
gcloud auth application-default login
```
For "Service Account Key":
- Type `Y` when prompted
- `Service Account Key JSON`
![Run Gcloud Auth](./img/run-gcloud-auth.png)
4. Open the authentication URL provided in a browser and select your Google account
![Choose the account](./img/take-account-email.png)
5. Follow the steps to obtain the authentication code
![Copy auth code](./img/copy-auth-code.png)
6. Paste the authentication code back in Cloud Shell
![Enter Auth Code](./img/enter-auth-code.png)
7. Use `cat <file_name>` to view the temporary credentials file
![Get the FileName](./img/get-temp-file-credentials.png)
8. Extract the following values for Prowler Cloud/App:
For "Application Default Credentials":
- `client_id`
- `client_secret`
- `refresh_token`
![Get the values](./img/get-needed-values-auth.png)
![Enter the Credentials](./img/enter-credentials-prowler-cloud.png)
7. Click "Next", then "Launch Scan"
![Launch Scan GCP](./img/launch-scan.png)
---
## Step 4: Add Credentials to Prowler Cloud/App
## Prowler CLI
1. Go back to Prowler Cloud/App and enter the required credentials, then click `Next`
### Credentials Lookup Order
![Enter the Credentials](./img/enter-credentials-prowler-cloud.png)
Prowler follows the same credential search process as [Google authentication libraries](https://cloud.google.com/docs/authentication/application-default-credentials#search_order), checking credentials in this order:
2. Click `Launch Scan` to begin scanning your GCP environment
1. [`GOOGLE_APPLICATION_CREDENTIALS` environment variable](https://cloud.google.com/docs/authentication/application-default-credentials#GAC)
2. [`CLOUDSDK_AUTH_ACCESS_TOKEN` + optional `GOOGLE_CLOUD_PROJECT`](https://cloud.google.com/sdk/gcloud/reference/auth/print-access-token)
3. [User credentials set up by using the Google Cloud CLI](https://cloud.google.com/docs/authentication/application-default-credentials#personal)
4. [Attached service account (e.g., Cloud Run, GCE, Cloud Functions)](https://cloud.google.com/docs/authentication/application-default-credentials#attached-sa)
![Launch Scan GCP](./img/launch-scan.png)
???+ note
The credentials must belong to a user or service account with the necessary permissions.
For detailed instructions on how to set the permissions, see [Authentication > Required Permissions](./authentication.md#required-permissions).
???+ note
Prowler will use the enabled Google Cloud APIs to get the information needed to perform the checks.
### Configure GCP Credentials
To authenticate with GCP, use one of the following methods:
```console
gcloud auth application-default login
```
or set the credentials file path:
```console
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
```
These credentials must belong to a user or service account with the necessary permissions to perform security checks.
For more authentication details, see the [Authentication](./authentication.md) page.
### Project Specification
To scan specific projects, specify them with the following command:
```console
prowler gcp --project-ids <project-id-1> <project-id-2>
```
### Service Account Impersonation
For service account impersonation, use the `--impersonate-service-account` flag:
```console
prowler gcp --impersonate-service-account <service-account-email>
```
More details on authentication methods in the [Authentication](./authentication.md) page.