From 48913c18866cbff7d4a52ff93c2a3cb9bd80750d Mon Sep 17 00:00:00 2001 From: Andoni Alonso <14891798+andoniaf@users.noreply.github.com> Date: Wed, 10 Sep 2025 13:45:36 +0200 Subject: [PATCH] docs(aws): refactor getting started and auth (#8683) --- docs/basic-usage/prowler-cli.md | 2 +- docs/tutorials/aws/authentication.md | 123 +++++++++-- docs/tutorials/aws/getting-started-aws.md | 192 ++++++------------ docs/tutorials/aws/role-assumption.md | 2 +- docs/tutorials/mongodbatlas/authentication.md | 2 +- docs/tutorials/prowler-app.md | 2 +- mkdocs.yml | 2 +- 7 files changed, 165 insertions(+), 160 deletions(-) diff --git a/docs/basic-usage/prowler-cli.md b/docs/basic-usage/prowler-cli.md index 6d20eefe11..3681714b70 100644 --- a/docs/basic-usage/prowler-cli.md +++ b/docs/basic-usage/prowler-cli.md @@ -279,4 +279,4 @@ You can filter scans to specific organizations or projects: prowler mongodbatlas --atlas-project-id ``` -See more details about MongoDB Atlas Authentication in [Requirements](../getting-started/requirements.md#mongodb-atlas) +See more details about MongoDB Atlas Authentication in [MongoDB Atlas Authentication](../tutorials/mongodbatlas/authentication.md) diff --git a/docs/tutorials/aws/authentication.md b/docs/tutorials/aws/authentication.md index dbfc97eaa7..c7d96aa17e 100644 --- a/docs/tutorials/aws/authentication.md +++ b/docs/tutorials/aws/authentication.md @@ -2,7 +2,11 @@ Prowler requires AWS credentials to function properly. Authentication is available through the following methods: +- Static Credentials +- Assumed Role + ## Required Permissions + To ensure full functionality, attach the following AWS managed policies to the designated user or role: - `arn:aws:iam::aws:policy/SecurityAudit` @@ -13,37 +17,114 @@ To ensure full functionality, attach the following AWS managed policies to the d For certain checks, additional read-only permissions are required. Attach the following custom policy to your role: [prowler-additions-policy.json](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-additions-policy.json) -## Configure AWS Credentials +## Assume Role (Recommended) -Use one of the following methods to authenticate: +This method grants permanent access and is the recommended setup for production environments. -```console -aws configure -``` +=== "CloudFormation" -or + 1. Download the [Prowler Scan Role Template](https://raw.githubusercontent.com/prowler-cloud/prowler/refs/heads/master/permissions/templates/cloudformation/prowler-scan-role.yml) -```console -export AWS_ACCESS_KEY_ID="ASXXXXXXX" -export AWS_SECRET_ACCESS_KEY="XXXXXXXXX" -export AWS_SESSION_TOKEN="XXXXXXXXX" -``` + ![Prowler Scan Role Template](./img/prowler-scan-role-template.png) -These credentials must be associated with a user or role with the necessary permissions to perform security checks. + ![Download Role Template](./img/download-role-template.png) + 2. Open the [AWS Console](https://console.aws.amazon.com), search for **CloudFormation** + ![CloudFormation Search](./img/cloudformation-nav.png) -## AWS Profiles + 3. Go to **Stacks** and click "Create stack" > "With new resources (standard)" -Specify a custom AWS profile using the following command: + ![Create Stack](./img/create-stack.png) -```console -prowler aws -p/--profile -``` + 4. In **Specify Template**, choose "Upload a template file" and select the downloaded file -## Multi-Factor Authentication (MFA) + ![Upload a template file](./img/upload-template-file.png) + ![Upload file from downloads](./img/upload-template-from-downloads.png) -For IAM entities requiring Multi-Factor Authentication (MFA), use the `--mfa` flag. Prowler prompts for the following values to initiate a new session: + 5. Click "Next", provide a stack name and the **External ID** shown in the Prowler Cloud setup screen -- **ARN of your MFA device** -- **TOTP (Time-Based One-Time Password)** + ![External ID](./img/prowler-cloud-external-id.png) + ![Stack Data](./img/fill-stack-data.png) + + !!! info + An **External ID** is required when assuming the *ProwlerScan* role to comply with AWS [confused deputy prevention](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). + + 6. Acknowledge the IAM resource creation warning and proceed + + ![Stack Creation Second Step](./img/stack-creation-second-step.png) + + 7. Click "Submit" to deploy the stack + + ![Click on submit](./img/submit-third-page.png) + +=== "Terraform" + + To provision the scan role using Terraform: + + 1. Run the following commands: + + ```bash + terraform init + terraform plan + terraform apply + ``` + + 2. During `plan` and `apply`, provide the **External ID** when prompted, which is available in the Prowler Cloud or Prowler App UI: + + ![Get External ID](./img/get-external-id-prowler-cloud.png) + + > 💡 Note: Terraform will use the AWS credentials of the default profile. + +--- + +## Credentials +=== "Long term credentials" + + 1. Go to the [AWS Console](https://console.aws.amazon.com), open **CloudShell** + + ![AWS CloudShell](./img/aws-cloudshell.png) + + 2. Run: + + ```bash + aws iam create-access-key + ``` + + 3. Copy the output containing: + + - `AccessKeyId` + - `SecretAccessKey` + + ![CloudShell Output](./img/cloudshell-output.png) + +=== "Short term credentials (Recommended)" + + Use the [AWS Access Portal](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html) or the CLI: + + 1. Retrieve short-term credentials for the IAM identity using this command: + + ```bash + aws sts get-session-token --duration-seconds 900 + ``` + + ???+ note + Check the aws documentation [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/sts_example_sts_GetSessionToken_section.html) + + 2. Copy the output containing: + + - `AccessKeyId` + - `SecretAccessKey` + - `SessionToken` + + > Sample output: + ```json + { + "Credentials": { + "AccessKeyId": "ASIAIOSFODNN7EXAMPLE", + "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY", + "SessionToken": "AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4OlgkBN9bkUDNCJiBeb/AXlzBBko7b15fjrBs2+cTQtpZ3CYWFXG8C5zqx37wnOE49mRl/+OtkIKGO7fAE", + "Expiration": "2020-05-19T18:06:10+00:00" + } + } + ``` diff --git a/docs/tutorials/aws/getting-started-aws.md b/docs/tutorials/aws/getting-started-aws.md index 88ecea3e95..10bcd01131 100644 --- a/docs/tutorials/aws/getting-started-aws.md +++ b/docs/tutorials/aws/getting-started-aws.md @@ -1,39 +1,31 @@ -# Getting Started with AWS on Prowler Cloud/App +# Getting Started With AWS on Prowler + +## Prowler App -Set up your AWS account to enable security scanning using Prowler Cloud/App. +> Walkthrough video onboarding an AWS Account using Assumed Role. -## Requirements - -To configure your AWS account, you’ll need: - -1. Access to Prowler Cloud/App -2. Properly configured AWS credentials (either static or via an assumed IAM role) - ---- - -## Step 1: Get Your AWS Account ID +### Step 1: Get Your AWS Account ID 1. Log in to the [AWS Console](https://console.aws.amazon.com) 2. Locate your AWS account ID in the top-right dropdown menu ![Account ID detail](./img/aws-account-id.png) ---- -## Step 2: Access Prowler Cloud/App +### Step 2: Access Prowler Cloud or Prowler App 1. Navigate to [Prowler Cloud](https://cloud.prowler.com/) or launch [Prowler App](../prowler-app.md) -2. Go to `Configuration` > `Cloud Providers` +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 `Amazon Web Services` +4. Select "Amazon Web Services" ![Select AWS Provider](./img/select-aws.png) @@ -41,96 +33,39 @@ To configure your AWS account, you’ll need: ![Add account ID](./img/add-account-id.png) -6. Choose your preferred authentication method (next step) +6. Choose the preferred authentication method (next step) ![Select auth method](./img/select-auth-method.png) ---- -## Step 3: Set Up AWS Authentication +### Step 3: Set Up AWS Authentication -Before proceeding, choose your preferred authentication mode: +Before proceeding, choose the preferred authentication mode: -Credentials +**Credentials** -* Quick scan as current user ✅ -* No extra setup ✅ -* Credentials time out ❌ +* Quick scan as current user +* No extra setup +* Credentials time out -Assumed Role +**Assumed Role** + +* Preferred Setup +* Permanent Credentials +* Requires access to create role -* Preferred Setup ✅ -* Permanent Credentials ✅ -* Requires access to create role ❌ --- -### 🔐 Assume Role (Recommended) - -![Assume Role Overview](./img/assume-role-overview.png) +#### Assume Role (Recommended) This method grants permanent access and is the recommended setup for production environments. -=== "CloudFormation" +![Assume Role Overview](img/assume-role-overview.png) - 1. Download the [Prowler Scan Role Template](https://raw.githubusercontent.com/prowler-cloud/prowler/refs/heads/master/permissions/templates/cloudformation/prowler-scan-role.yml) +For detailed instructions on how to create the role, see [Authentication > Assume Role](./authentication.md#assume-role-recommended). - ![Prowler Scan Role Template](./img/prowler-scan-role-template.png) - - ![Download Role Template](./img/download-role-template.png) - - 2. Open the [AWS Console](https://console.aws.amazon.com), search for **CloudFormation** - - ![CloudFormation Search](./img/cloudformation-nav.png) - - 3. Go to **Stacks** and click `Create stack` > `With new resources (standard)` - - ![Create Stack](./img/create-stack.png) - - 4. In **Specify Template**, choose `Upload a template file` and select the downloaded file - - ![Upload a template file](./img/upload-template-file.png) - ![Upload file from downloads](./img/upload-template-from-downloads.png) - - 5. Click `Next`, provide a stack name and the **External ID** shown in the Prowler Cloud setup screen - - ![External ID](./img/prowler-cloud-external-id.png) - ![Stack Data](./img/fill-stack-data.png) - - !!! info - An **External ID** is required when assuming the *ProwlerScan* role to comply with AWS [confused deputy prevention](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). - - 6. Acknowledge the IAM resource creation warning and proceed - - ![Stack Creation Second Step](./img/stack-creation-second-step.png) - - 7. Click `Submit` to deploy the stack - - ![Click on submit](./img/submit-third-page.png) - -=== "Terraform" - - To provision the scan role using Terraform: - - 1. Run the following commands: - - ```bash - terraform init - terraform plan - terraform apply - ``` - - 2. During `plan` and `apply`, you will be prompted for the **External ID**, which is available in the Prowler Cloud/App UI: - - ![Get External ID](./img/get-external-id-prowler-cloud.png) - - > 💡 Note: Terraform will use the AWS credentials of your default profile. - ---- - -### Finish Setup with Assume Role - -8. Once the role is created, go to the **IAM Console**, click on the `ProwlerScan` role to open its details: +8. Once the role is created, go to the **IAM Console**, click on the "ProwlerScan" role to open its details: ![ProwlerScan role info](./img/prowler-scan-pre-info.png) @@ -138,80 +73,69 @@ This method grants permanent access and is the recommended setup for production ![New Role Info](./img/get-role-arn.png) -10. Paste the ARN into the corresponding field in Prowler Cloud/App +10. Paste the ARN into the corresponding field in Prowler Cloud or Prowler App ![Input the Role ARN](./img/paste-role-arn-prowler.png) -11. Click `Next`, then `Launch Scan` +11. Click "Next", then "Launch Scan" ![Next button in Prowler Cloud](./img/next-button-prowler-cloud.png) ![Launch Scan](./img/launch-scan-button-prowler-cloud.png) --- -### 🔑 Credentials (Static Access Keys) +#### Credentials (Static Access Keys) -You can also configure your AWS account using static credentials (not recommended for long-term use): +AWS accounts can also be configured using static credentials (not recommended for long-term use): ![Connect via credentials](./img/connect-via-credentials.png) -=== "Long term credentials" +For detailed instructions on how to create the credentials, see [Authentication > Credentials](./authentication.md#credentials). - 1. Go to the [AWS Console](https://console.aws.amazon.com), open **CloudShell** +1. Complete the form in Prowler Cloud or Prowler App and click "Next" - ![AWS CloudShell](./img/aws-cloudshell.png) + ![Filled credentials page](./img/prowler-cloud-credentials-next.png) - 2. Run: +2. Click "Launch Scan" - ```bash - aws iam create-access-key - ``` + ![Launch Scan](./img/launch-scan-button-prowler-cloud.png) - 3. Copy the output containing: +--- - - `AccessKeyId` - - `SecretAccessKey` +## Prowler CLI - ![CloudShell Output](./img/cloudshell-output.png) +### Configure AWS Credentials - > ⚠️ Save these credentials securely and paste them into the Prowler Cloud/App setup screen. +To authenticate with AWS, use one of the following methods: -=== "Short term credentials (Recommended)" +```console +aws configure +``` - You can use your [AWS Access Portal](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html) or the CLI: +or - 1. Retrieve short-term credentials for the IAM identity using this command: +```console +export AWS_ACCESS_KEY_ID="ASXXXXXXX" +export AWS_SECRET_ACCESS_KEY="XXXXXXXXX" +export AWS_SESSION_TOKEN="XXXXXXXXX" +``` - ```bash - aws sts get-session-token --duration-seconds 900 - ``` +These credentials must be associated with a user or role with the necessary permissions to perform security checks. - ???+ note - Check the aws documentation [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/sts_example_sts_GetSessionToken_section.html) +More details on Assume Role settings from the CLI in [Assume Role](./role-assumption.md) page. - 2. Copy the output containing: - - `AccessKeyId` - - `SecretAccessKey` +### AWS Profiles - > Sample output: - ```json - { - "Credentials": { - "AccessKeyId": "ASIAIOSFODNN7EXAMPLE", - "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY", - "SessionToken": "AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4OlgkBN9bkUDNCJiBeb/AXlzBBko7b15fjrBs2+cTQtpZ3CYWFXG8C5zqx37wnOE49mRl/+OtkIKGO7fAE", - "Expiration": "2020-05-19T18:06:10+00:00" - } - } - ``` +To use a custom AWS profile, specify it with the following command: - > ⚠️ Save these credentials securely and paste them into the Prowler Cloud/App setup screen. +```console +prowler aws -p/--profile +``` -Complete the form in Prowler Cloud/App and click `Next` +### Multi-Factor Authentication (MFA) -![Filled credentials page](./img/prowler-cloud-credentials-next.png) +For IAM entities requiring Multi-Factor Authentication (MFA), use the `--mfa` flag. Prowler prompts for the following values to initiate a new session: -Click `Launch Scan` - -![Launch Scan](./img/launch-scan-button-prowler-cloud.png) +- **ARN of your MFA device** +- **TOTP (time-based one-time password)** diff --git a/docs/tutorials/aws/role-assumption.md b/docs/tutorials/aws/role-assumption.md index acee1119f5..17fb3c2727 100644 --- a/docs/tutorials/aws/role-assumption.md +++ b/docs/tutorials/aws/role-assumption.md @@ -1,4 +1,4 @@ -# AWS Assume Role in Prowler +# AWS Assume Role in Prowler (CLI) ## Authentication Overview diff --git a/docs/tutorials/mongodbatlas/authentication.md b/docs/tutorials/mongodbatlas/authentication.md index cc6ddafb50..653dbb817c 100644 --- a/docs/tutorials/mongodbatlas/authentication.md +++ b/docs/tutorials/mongodbatlas/authentication.md @@ -42,4 +42,4 @@ prowler mongodbatlas - Note the public key and private key - Store credentials securely -For more details about MongoDB Atlas, see the [MongoDB Atlas Tutorial](../tutorials/mongodbatlas/getting-started-mongodbatlas.md). +For more details about MongoDB Atlas, see the [MongoDB Atlas Tutorial](./getting-started-mongodbatlas.md). diff --git a/docs/tutorials/prowler-app.md b/docs/tutorials/prowler-app.md index 431e1259d6..c9675a88f1 100644 --- a/docs/tutorials/prowler-app.md +++ b/docs/tutorials/prowler-app.md @@ -1,6 +1,6 @@ # Prowler App -**Prowler App** is a user-friendly interface for Prowler CLI, providing a visual dashboard to monitor your cloud security posture. This tutorial will guide you through setting up and using Prowler App. +**Prowler App** is a web application that simplifies running Prowler. This tutorial will guide you through setting up and using it. ## Accessing Prowler App and API Documentation diff --git a/mkdocs.yml b/mkdocs.yml index 949f360dfb..b9170130b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,7 +100,7 @@ nav: - AWS: - Getting Started: tutorials/aws/getting-started-aws.md - Authentication: tutorials/aws/authentication.md - - Assume Role: tutorials/aws/role-assumption.md + - Assume Role (CLI): tutorials/aws/role-assumption.md - AWS Organizations: tutorials/aws/organizations.md - AWS Regions and Partitions: tutorials/aws/regions-and-partitions.md - Tag-based Scan: tutorials/aws/tag-based-scan.md