Skip to content

Commit d13f3f0

Browse files
andoniafandoniaf
authored
docs(gcp): refactor getting started and auth (#8758)
1 parent 56821de commit d13f3f0

File tree

3 files changed

+170
-76
lines changed

3 files changed

+170
-76
lines changed

‎docs/developer-guide/checks.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -273,7 +273,7 @@ The `CheckTitle` field must be plain text, clearly and succinctly define **the b
273273

274274
**Always write the `CheckTitle` to describe the *PASS* case**, the desired secure or compliant state of the resource(s). This helps ensure that findings are easy to interpret and that the title always reflects the best practice being met.
275275

276-
For detailed guidelines on writing effective check titles, including how to determine singular vs. plural scope and common mistakes to avoid, see [CheckTitle Guidelines](./check-metadata-guidelines.md#checktitle-guidelines).
276+
For detailed guidelines on writing effective check titles, including how to determine singular vs. plural scope and common mistakes to avoid, see [CheckTitle Guidelines](./check-metadata-guidelines.md#check-title-guidelines).
277277

278278
#### CheckType
279279

@@ -282,7 +282,7 @@ For detailed guidelines on writing effective check titles, including how to dete
282282

283283
It follows the [AWS Security Hub Types](https://docs.aws.amazon.com/securityhub/latest/userguide/asff-required-attributes.html#Types) format using the pattern `namespace/category/classifier`.
284284

285-
For the complete AWS Security Hub selection guidelines, see [CheckType Guidelines](./check-metadata-guidelines.md#checktype-guidelines-aws-only).
285+
For the complete AWS Security Hub selection guidelines, see [CheckType Guidelines](./check-metadata-guidelines.md#check-type-guidelines-aws-only).
286286

287287
#### ServiceName
288288

‎docs/tutorials/gcp/authentication.md‎

Lines changed: 95 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# GCP Authentication in Prowler
22

3+
Prowler for Google Cloud supports multiple authentication methods. To use a specific method, configure the appropriate credentials during execution:
4+
5+
- [**User Credentials** (Application Default Credentials)](#application-default-credentials-user-credentials)
6+
- [**Service Account Key File**](#service-account-key-file)
7+
- [**Access Token**](#access-token)
8+
- [**Service Account Impersonation**](#service-account-impersonation)
9+
310
## Required Permissions
411

512
Prowler for Google Cloud requires the following permissions:
@@ -33,28 +40,92 @@ At least one project must have the following configurations:
3340
```
3441

3542
???+ note
36-
`prowler` will scan the GCP project associated with the credentials.
43+
Prowler will scan the GCP project associated with the credentials.
3744

38-
## Credentials lookup order
3945

40-
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:
46+
## Application Default Credentials (User Credentials)
4147

42-
1. [`GOOGLE_APPLICATION_CREDENTIALS` environment variable](https://cloud.google.com/docs/authentication/application-default-credentials#GAC)
43-
2. [`CLOUDSDK_AUTH_ACCESS_TOKEN` + optional `GOOGLE_CLOUD_PROJECT`](https://cloud.google.com/sdk/gcloud/reference/auth/print-access-token)
44-
3. [User credentials set up by using the Google Cloud CLI](https://cloud.google.com/docs/authentication/application-default-credentials#personal)
45-
4. [Attached service account (e.g., Cloud Run, GCE, Cloud Functions)](https://cloud.google.com/docs/authentication/application-default-credentials#attached-sa)
48+
This method uses the Google Cloud CLI to authenticate and is suitable for development and testing environments.
4649

47-
???+ note
48-
The credentials must belong to a user or service account with the necessary permissions.
49-
To ensure full access, assign the roles/reader IAM role to the identity being used.
50+
### Setup Application Default Credentials
5051

51-
???+ note
52-
Prowler will use the enabled Google Cloud APIs to get the information needed to perform the checks.
52+
1. In the [GCP Console](https://console.cloud.google.com/), click on "Activate Cloud Shell"
53+
54+
![Activate Cloud Shell](./img/access-console.png)
55+
56+
2. Click "Authorize Cloud Shell"
57+
58+
![Authorize Cloud Shell](./img/authorize-cloud-shell.png)
59+
60+
3. Run the following command:
61+
62+
```bash
63+
gcloud auth application-default login
64+
```
65+
66+
- Type `Y` when prompted
5367

68+
![Run Gcloud Auth](./img/run-gcloud-auth.png)
5469

70+
4. Open the authentication URL provided in a browser and select your Google account
5571

72+
![Choose the account](./img/take-account-email.png)
5673

57-
## Using an Access Token
74+
5. Follow the steps to obtain the authentication code
75+
76+
![Copy auth code](./img/copy-auth-code.png)
77+
78+
6. Paste the authentication code back in Cloud Shell
79+
80+
![Enter Auth Code](./img/enter-auth-code.png)
81+
82+
7. Use `cat <file_name>` to view the temporary credentials file
83+
84+
![Get the FileName](./img/get-temp-file-credentials.png)
85+
86+
8. Extract the following values for Prowler Cloud/App:
87+
88+
- `client_id`
89+
- `client_secret`
90+
- `refresh_token`
91+
92+
![Get the values](./img/get-needed-values-auth.png)
93+
94+
### Using with Prowler CLI
95+
96+
Once application default credentials are set up, run Prowler directly:
97+
98+
```console
99+
prowler gcp --project-ids <project-id>
100+
```
101+
102+
## Service Account Key File
103+
104+
This method uses a service account with a downloaded key file for authentication.
105+
106+
### Create Service Account and Key
107+
108+
1. Go to the [Service Accounts page](https://console.cloud.google.com/iam-admin/serviceaccounts) in the GCP Console
109+
2. Click "Create Service Account"
110+
3. Fill in the service account details and click "Create and Continue"
111+
4. Grant the service account the "Reader" role
112+
5. Click "Done"
113+
6. Find your service account in the list and click on it
114+
7. Go to the "Keys" tab
115+
8. Click "Add Key" > "Create new key"
116+
9. Select "JSON" and click "Create"
117+
10. Save the downloaded key file securely
118+
119+
### Using with Prowler CLI
120+
121+
Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable:
122+
123+
```console
124+
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
125+
prowler gcp --project-ids <project-id>
126+
```
127+
128+
## Access Token
58129

59130
For existing access tokens (e.g., generated with `gcloud auth print-access-token`), run Prowler with:
60131

@@ -69,10 +140,7 @@ prowler gcp --project-ids <project-id>
69140
export GOOGLE_CLOUD_PROJECT=<project-id>
70141
```
71142

72-
73-
74-
75-
## Impersonating a GCP Service Account
143+
## Service Account Impersonation
76144

77145
To impersonate a GCP service account, use the `--impersonate-service-account` argument followed by the service account email:
78146

@@ -81,3 +149,13 @@ prowler gcp --impersonate-service-account <service-account-email>
81149
```
82150

83151
This command leverages the default credentials to impersonate the specified service account.
152+
153+
### Prerequisites for Impersonation
154+
155+
The identity running Prowler must have the following permission on the target service account:
156+
157+
- `roles/iam.serviceAccountTokenCreator`
158+
159+
Or the more specific permission:
160+
161+
- `iam.serviceAccounts.generateAccessToken`

‎docs/tutorials/gcp/getting-started-gcp.md‎

Lines changed: 73 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,121 @@
1-
# Getting Started with GCP on Prowler Cloud/App
1+
# Getting Started With GCP on Prowler
22

3-
Set up your GCP project to enable security scanning using Prowler Cloud/App.
3+
## Prowler App
44

5-
## Requirements
5+
### Step 1: Get the GCP Project ID
66

7-
To configure your GCP project, you’ll need:
7+
1. Go to the [GCP Console](https://console.cloud.google.com/)
8+
2. Locate the Project ID on the welcome screen
89

9-
1. Get the `Project ID`
10-
2. Access to Prowler Cloud/App
11-
3. Configure authentication in GCP:
10+
![Get the Project ID](./img/project-id-console.png)
1211

13-
3.1 Retrieve credentials from Google Cloud
12+
### Step 2: Access Prowler Cloud or Prowler App
1413

15-
4. Add the credentials to Prowler Cloud/App
14+
1. Navigate to [Prowler Cloud](https://cloud.prowler.com/) or launch [Prowler App](../prowler-app.md)
15+
2. Go to "Configuration" > "Cloud Providers"
1616

17-
---
17+
![Cloud Providers Page](../img/cloud-providers-page.png)
1818

19-
## Step 1: Get the Project ID
19+
3. Click "Add Cloud Provider"
2020

21-
1. Go to the [GCP Console](https://console.cloud.google.com/)
22-
2. Locate your Project ID on the welcome screen
21+
![Add a Cloud Provider](../img/add-cloud-provider.png)
2322

24-
![Get the Project ID](./img/project-id-console.png)
23+
4. Select "Google Cloud Platform"
2524

26-
---
25+
![Select GCP](./img/select-gcp.png)
2726

28-
## Step 2: Access Prowler Cloud/App
27+
5. Add the Project ID and optionally provide a provider alias, then click "Next"
2928

30-
1. Go to [Prowler Cloud](https://cloud.prowler.com/) or launch [Prowler App](../prowler-app.md)
31-
2. Navigate to `Configuration` > `Cloud Providers`
29+
![Add Project ID](./img/add-project-id.png)
3230

33-
![Cloud Providers Page](../img/cloud-providers-page.png)
31+
### Step 3: Set Up GCP Authentication
3432

35-
3. Click `Add Cloud Provider`
33+
Choose the preferred authentication mode before proceeding:
3634

37-
![Add a Cloud Provider](../img/add-cloud-provider.png)
35+
**User Credentials (Application Default Credentials)**
3836

39-
4. Select `Google Cloud Platform`
37+
* Quick scan as current user
38+
* Uses Google Cloud CLI authentication
39+
* Credentials may time out
4040

41-
![Select GCP](./img/select-gcp.png)
41+
**Service Account Key File**
4242

43-
5. Add the Project ID and optionally provide a provider alias, then click `Next`
43+
* Authenticates as a service identity
44+
* Stable and auditable
45+
* Recommended for production
4446

45-
![Add Project ID](./img/add-project-id.png)
47+
For detailed instructions on how to set up authentication, see [Authentication](./authentication.md).
4648

47-
---
49+
6. Once credentials are configured, return to Prowler App and enter the required values:
4850

49-
## Step 3: Configure Authentication in GCP
51+
For "Service Account Key":
5052

51-
### Retrieve Credentials from Google Cloud
53+
- `Service Account Key JSON`
5254

53-
1. In the [GCP Console](https://console.cloud.google.com/), click on `Activate Cloud Shell`
55+
For "Application Default Credentials":
5456

55-
![Activate Cloud Shell](./img/access-console.png)
57+
- `client_id`
58+
- `client_secret`
59+
- `refresh_token`
5660

57-
2. Click `Authorize Cloud Shell`
61+
![Enter the Credentials](./img/enter-credentials-prowler-cloud.png)
62+
63+
7. Click "Next", then "Launch Scan"
5864

59-
![Authorize Cloud Shell](./img/authorize-cloud-shell.png)
65+
![Launch Scan GCP](./img/launch-scan.png)
6066

61-
3. Run the following command:
67+
---
6268

63-
```bash
64-
gcloud auth application-default login
65-
```
69+
## Prowler CLI
6670

67-
- Type `Y` when prompted
71+
### Credentials Lookup Order
6872

69-
![Run Gcloud Auth](./img/run-gcloud-auth.png)
73+
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:
7074

71-
4. Open the authentication URL provided in a browser and select your Google account
75+
1. [`GOOGLE_APPLICATION_CREDENTIALS` environment variable](https://cloud.google.com/docs/authentication/application-default-credentials#GAC)
76+
2. [`CLOUDSDK_AUTH_ACCESS_TOKEN` + optional `GOOGLE_CLOUD_PROJECT`](https://cloud.google.com/sdk/gcloud/reference/auth/print-access-token)
77+
3. [User credentials set up by using the Google Cloud CLI](https://cloud.google.com/docs/authentication/application-default-credentials#personal)
78+
4. [Attached service account (e.g., Cloud Run, GCE, Cloud Functions)](https://cloud.google.com/docs/authentication/application-default-credentials#attached-sa)
7279

73-
![Choose the account](./img/take-account-email.png)
80+
???+ note
81+
The credentials must belong to a user or service account with the necessary permissions.
82+
For detailed instructions on how to set the permissions, see [Authentication > Required Permissions](./authentication.md#required-permissions).
7483

75-
5. Follow the steps to obtain the authentication code
84+
???+ note
85+
Prowler will use the enabled Google Cloud APIs to get the information needed to perform the checks.
7686

77-
![Copy auth code](./img/copy-auth-code.png)
87+
### Configure GCP Credentials
7888

79-
6. Paste the authentication code back in Cloud Shell
89+
To authenticate with GCP, use one of the following methods:
8090

81-
![Enter Auth Code](./img/enter-auth-code.png)
91+
```console
92+
gcloud auth application-default login
93+
```
8294

83-
7. Use `cat <file_name>` to view the temporary credentials file
95+
or set the credentials file path:
8496

85-
![Get the FileName](./img/get-temp-file-credentials.png)
97+
```console
98+
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
99+
```
86100

87-
8. Extract the following values for Prowler Cloud/App:
101+
These credentials must belong to a user or service account with the necessary permissions to perform security checks.
88102

89-
- `client_id`
90-
- `client_secret`
91-
- `refresh_token`
103+
For more authentication details, see the [Authentication](./authentication.md) page.
92104

93-
![Get the values](./img/get-needed-values-auth.png)
105+
### Project Specification
94106

95-
---
107+
To scan specific projects, specify them with the following command:
96108

97-
## Step 4: Add Credentials to Prowler Cloud/App
109+
```console
110+
prowler gcp --project-ids <project-id-1> <project-id-2>
111+
```
98112

99-
1. Go back to Prowler Cloud/App and enter the required credentials, then click `Next`
113+
### Service Account Impersonation
100114

101-
![Enter the Credentials](./img/enter-credentials-prowler-cloud.png)
115+
For service account impersonation, use the `--impersonate-service-account` flag:
102116

103-
2. Click `Launch Scan` to begin scanning your GCP environment
117+
```console
118+
prowler gcp --impersonate-service-account <service-account-email>
119+
```
104120

105-
![Launch Scan GCP](./img/launch-scan.png)
121+
More details on authentication methods in the [Authentication](./authentication.md) page.

0 commit comments

Comments
 (0)