diff --git a/docs/developer-guide/checks.md b/docs/developer-guide/checks.md index bc6d9a40f2..c921c9714e 100644 --- a/docs/developer-guide/checks.md +++ b/docs/developer-guide/checks.md @@ -273,7 +273,7 @@ The `CheckTitle` field must be plain text, clearly and succinctly define **the b **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. -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). +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). #### CheckType @@ -282,7 +282,7 @@ For detailed guidelines on writing effective check titles, including how to dete 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`. -For the complete AWS Security Hub selection guidelines, see [CheckType Guidelines](./check-metadata-guidelines.md#checktype-guidelines-aws-only). +For the complete AWS Security Hub selection guidelines, see [CheckType Guidelines](./check-metadata-guidelines.md#check-type-guidelines-aws-only). #### ServiceName diff --git a/docs/tutorials/gcp/authentication.md b/docs/tutorials/gcp/authentication.md index 5b8ec7b92a..c222510989 100644 --- a/docs/tutorials/gcp/authentication.md +++ b/docs/tutorials/gcp/authentication.md @@ -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 ` 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 +``` + +## 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 +``` + +## 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 export GOOGLE_CLOUD_PROJECT= ``` - - - -## 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 ``` 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` diff --git a/docs/tutorials/gcp/getting-started-gcp.md b/docs/tutorials/gcp/getting-started-gcp.md index ea34f293e8..81d640cf59 100644 --- a/docs/tutorials/gcp/getting-started-gcp.md +++ b/docs/tutorials/gcp/getting-started-gcp.md @@ -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 ` 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 +``` + +### Service Account Impersonation + +For service account impersonation, use the `--impersonate-service-account` flag: + +```console +prowler gcp --impersonate-service-account +``` + +More details on authentication methods in the [Authentication](./authentication.md) page.