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(aws): refactor getting started and auth (#8683)

Browse Source
This commit is contained in:
Andoni Alonso
2025-09-10 13:45:36 +02:00
committed by GitHub
parent ea20943f83
commit 48913c1886
7 changed files with 165 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/basic-usage/prowler-cli.md
+1 -1
View File
@@ -279,4 +279,4 @@ You can filter scans to specific organizations or projects:
prowler mongodbatlas --atlas-project-id <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)
docs/tutorials/aws/authentication.md
+102 -21
View File
@@ -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 <profile_name>
```
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"
}
}
```
docs/tutorials/aws/getting-started-aws.md
+58 -134
View File
@@ -1,39 +1,31 @@
# Getting Started with AWS on Prowler Cloud/App
# Getting Started With AWS on Prowler
## Prowler App
<iframe width="560" height="380" src="https://www.youtube-nocookie.com/embed/RPgIWOCERzY" title="Prowler Cloud Onboarding AWS" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="1"></iframe>
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 <profile_name>
```
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)**
docs/tutorials/aws/role-assumption.md
+1 -1
View File
@@ -1,4 +1,4 @@
# AWS Assume Role in Prowler
# AWS Assume Role in Prowler (CLI)
## Authentication Overview
docs/tutorials/mongodbatlas/authentication.md
+1 -1
View File
@@ -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).
docs/tutorials/prowler-app.md
+1 -1
View File
@@ -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
mkdocs.yml
+1 -1
View File
@@ -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