mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-07-24 13:01:56 +00:00
docs(tutorials): improve quality redrive (#7915)
Co-authored-by: Daniel Barranquero <danielbo2001@gmail.com> Co-authored-by: Andoni Alonso <14891798+andoniaf@users.noreply.github.com>
This commit is contained in:
Rubén De la Torre Vico
committed by
GitHub
GitHub
parent
1bdcf2c7f1
commit
9ca1899ebf
@@ -1,6 +1,10 @@
|
||||
# AWS Authentication
|
||||
# AWS Authentication in Prowler
|
||||
|
||||
Make sure you have properly configured your AWS-CLI with a valid Access Key and Region or declare AWS variables properly (or instance profile/role):
|
||||
Proper authentication is required for Prowler to perform security checks across AWS resources. Ensure that AWS-CLI is correctly configured or manually declare AWS credentials before running scans.
|
||||
|
||||
## Configure AWS Credentials
|
||||
|
||||
Use one of the following methods to authenticate:
|
||||
|
||||
```console
|
||||
aws configure
|
||||
@@ -14,25 +18,32 @@ export AWS_SECRET_ACCESS_KEY="XXXXXXXXX"
|
||||
export AWS_SESSION_TOKEN="XXXXXXXXX"
|
||||
```
|
||||
|
||||
Those credentials must be associated to a user or role with proper permissions to do all checks. To make sure, add the following AWS managed policies to the user or role being used:
|
||||
These credentials must be associated with a user or role with the necessary permissions to perform security checks.
|
||||
|
||||
- `arn:aws:iam::aws:policy/SecurityAudit`
|
||||
- `arn:aws:iam::aws:policy/job-function/ViewOnlyAccess`
|
||||
## Assign Required AWS Permissions
|
||||
To ensure full functionality, attach the following AWS managed policies to the designated user or role:
|
||||
|
||||
- `arn:aws:iam::aws:policy/SecurityAudit`
|
||||
- `arn:aws:iam::aws:policy/job-function/ViewOnlyAccess`
|
||||
|
||||
???+ note
|
||||
Moreover, some read-only additional permissions are needed for several checks, make sure you attach also the custom policy [prowler-additions-policy.json](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-additions-policy.json) to the role you are using. If you want Prowler to send findings to [AWS Security Hub](https://aws.amazon.com/security-hub), make sure you also attach the custom policy [prowler-security-hub.json](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-security-hub.json).
|
||||
Some security checks require read-only additional permissions. Attach the following custom policies to the role: [prowler-additions-policy.json](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-additions-policy.json). If you want Prowler to send findings to [AWS Security Hub](https://aws.amazon.com/security-hub), make sure to also attach the custom policy: [prowler-security-hub.json](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-security-hub.json).
|
||||
|
||||
## AWS Profiles and Service Scanning in Prowler
|
||||
|
||||
## Profiles
|
||||
Prowler supports authentication and security assessments using custom AWS profiles and can optionally scan unused services.
|
||||
|
||||
**Using Custom AWS Profiles**
|
||||
|
||||
Prowler allows you to specify a custom AWS profile using the following command:
|
||||
|
||||
Prowler can use your custom AWS Profile with:
|
||||
```console
|
||||
prowler aws -p/--profile <profile_name>
|
||||
```
|
||||
|
||||
## Multi-Factor Authentication
|
||||
## Multi-Factor Authentication (MFA)
|
||||
|
||||
If your IAM entity enforces MFA you can use `--mfa` and Prowler will ask you to input the following values to get a new session:
|
||||
If MFA enforcement is required for your IAM entity, you can use `--mfa`. Prowler will prompt you to enter the following in order to get a new session:
|
||||
|
||||
- ARN of your MFA device
|
||||
- TOTP (Time-Based One-Time Password)
|
||||
|
||||
@@ -1,45 +1,52 @@
|
||||
# Boto3 Retrier Configuration
|
||||
# Boto3 Retrier Configuration in Prowler
|
||||
|
||||
Prowler's AWS Provider uses the Boto3 [Standard](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html) retry mode to assist in retrying client calls to AWS services when these kinds of errors or exceptions are experienced. This mode includes the following behaviours:
|
||||
Prowler's AWS Provider leverages Boto3's [Standard](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html) retry mode to automatically retry client calls to AWS services when encountering errors or exceptions.
|
||||
|
||||
- A default value of 3 for maximum retry attempts. This can be overwritten with the `--aws-retries-max-attempts 5` argument.
|
||||
## Retry Behavior Overview
|
||||
|
||||
- Retry attempts for an expanded list of errors/exceptions:
|
||||
```
|
||||
# Transient errors/exceptions
|
||||
RequestTimeout
|
||||
RequestTimeoutException
|
||||
PriorRequestNotComplete
|
||||
ConnectionError
|
||||
HTTPClientError
|
||||
Boto3's Standard retry mode includes the following mechanisms:
|
||||
|
||||
# Service-side throttling/limit errors and exceptions
|
||||
Throttling
|
||||
ThrottlingException
|
||||
ThrottledException
|
||||
RequestThrottledException
|
||||
TooManyRequestsException
|
||||
ProvisionedThroughputExceededException
|
||||
TransactionInProgressException
|
||||
RequestLimitExceeded
|
||||
BandwidthLimitExceeded
|
||||
LimitExceededException
|
||||
RequestThrottled
|
||||
SlowDown
|
||||
EC2ThrottledException
|
||||
```
|
||||
- Maximum Retry Attempts: Default value set to 3, configurable via the `--aws-retries-max-attempts 5` argument.
|
||||
|
||||
- Retry attempts on nondescriptive, transient error codes. Specifically, these HTTP status codes: 500, 502, 503, 504.
|
||||
- Expanded Error Handling: Retries occur for a comprehensive set of errors.
|
||||
|
||||
- Any retry attempt will include an exponential backoff by a base factor of 2 for a maximum backoff time of 20 seconds.
|
||||
```
|
||||
# *Transient Errors/Exceptions*
|
||||
The retrier handles various temporary failures:
|
||||
RequestTimeout
|
||||
RequestTimeoutException
|
||||
PriorRequestNotComplete
|
||||
ConnectionError
|
||||
HTTPClientError
|
||||
|
||||
## Notes for validating retry attempts
|
||||
# *Service-Side Throttling and Limit Errors*
|
||||
Retries occur for service-imposed rate limits and resource constraints:
|
||||
Throttling
|
||||
ThrottlingException
|
||||
ThrottledException
|
||||
RequestThrottledException
|
||||
TooManyRequestsException
|
||||
ProvisionedThroughputExceededException
|
||||
TransactionInProgressException
|
||||
RequestLimitExceeded
|
||||
BandwidthLimitExceeded
|
||||
LimitExceededException
|
||||
RequestThrottled
|
||||
SlowDown
|
||||
EC2ThrottledException
|
||||
```
|
||||
|
||||
If you are making changes to Prowler, and want to validate if requests are being retried or given up on, you can take the following approach
|
||||
- Nondescriptive Transient Error Codes: The retrier applies retry logic to standard HTTP status codes signaling transient errors: 500, 502, 503, 504.
|
||||
|
||||
- Exponential Backoff Strategy: Each retry attempt follows exponential backoff with a base factor of 2, ensuring progressive delay between retries. Maximum backoff time: 20 seconds
|
||||
|
||||
## Validating Retry Attempts
|
||||
|
||||
For testing or modifying Prowler's behavior, use the following steps to confirm whether requests are being retried or abandoned:
|
||||
|
||||
* Run prowler with `--log-level DEBUG` and `--log-file debuglogs.txt`
|
||||
* Search for retry attempts using `grep -i 'Retry needed' debuglogs.txt`
|
||||
|
||||
This is based off of the [AWS documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html#checking-retry-attempts-in-your-client-logs), which states that if a retry is performed, you will see a message starting with "Retry needed".
|
||||
This approach follows the [AWS documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html#checking-retry-attempts-in-your-client-logs), which states that if a retry is performed, a message starting with "Retry needed” will be prompted.
|
||||
|
||||
You can determine the total number of calls made using `grep -i 'Sending http request' debuglogs.txt | wc -l`
|
||||
It is possible to determine the total number of calls made using `grep -i 'Sending http request' debuglogs.txt | wc -l`
|
||||
|
||||
@@ -1,7 +1,11 @@
|
||||
# AWS CloudShell
|
||||
# Installing Prowler in AWS CloudShell
|
||||
|
||||
## Following the migration of AWS CloudShell from Amazon Linux 2 to Amazon Linux 2023
|
||||
|
||||
AWS CloudShell has migrated from Amazon Linux 2 to Amazon Linux 2023 [[1]](https://aws.amazon.com/about-aws/whats-new/2023/12/aws-cloudshell-migrated-al2023/) [[2]](https://docs.aws.amazon.com/cloudshell/latest/userguide/cloudshell-AL2023-migration.html). With this transition, Python 3.9 is now included by default in AL2023, eliminating the need for manual compilation.
|
||||
|
||||
To install Prowler v4 in AWS CloudShell, follow the standard installation method using pip:
|
||||
|
||||
## Installation
|
||||
After the migration of AWS CloudShell from Amazon Linux 2 to Amazon Linux 2023 [[1]](https://aws.amazon.com/about-aws/whats-new/2023/12/aws-cloudshell-migrated-al2023/) [[2]](https://docs.aws.amazon.com/cloudshell/latest/userguide/cloudshell-AL2023-migration.html), there is no longer a need to manually compile Python 3.9 as it's already included in AL2023. Prowler can thus be easily installed following the Generic method of installation via pip. Follow the steps below to successfully execute Prowler v4 in AWS CloudShell:
|
||||
```shell
|
||||
sudo bash
|
||||
adduser prowler
|
||||
@@ -11,13 +15,20 @@ cd /tmp
|
||||
prowler aws
|
||||
```
|
||||
|
||||
## Download Files
|
||||
## Downloading Files from AWS CloudShell
|
||||
|
||||
To download the results from AWS CloudShell, select Actions -> Download File and add the full path of each file. For the CSV file it will be something like `/home/cloudshell-user/output/prowler-output-123456789012-20221220191331.csv`
|
||||
To download results from AWS CloudShell:
|
||||
|
||||
## Clone Prowler from Github
|
||||
- Select Actions → Download File.
|
||||
|
||||
- Specify the full file path of each file you wish to download. For example, downloading a CSV file would require providing its complete path, as in: `/home/cloudshell-user/output/prowler-output-123456789012-20221220191331.csv`
|
||||
|
||||
## Cloning Prowler from GitHub
|
||||
|
||||
Due to the limited storage in AWS CloudShell's home directory, installing Poetry dependencies for running Prowler from GitHub can be problematic.
|
||||
|
||||
The following workaround ensures successful installation:
|
||||
|
||||
The limited storage that AWS CloudShell provides for the user's home directory causes issues when installing the poetry dependencies to run Prowler from GitHub. Here is a workaround:
|
||||
```shell
|
||||
sudo bash
|
||||
adduser prowler
|
||||
@@ -31,8 +42,8 @@ eval $(poetry env activate)
|
||||
poetry install
|
||||
python prowler-cli.py -v
|
||||
```
|
||||
> [!IMPORTANT]
|
||||
> Starting from Poetry v2.0.0, `poetry shell` has been deprecated in favor of `poetry env activate`.
|
||||
>
|
||||
> If your poetry version is below 2.0.0 you must keep using `poetry shell` to activate your environment.
|
||||
> In case you have any doubts, consult the Poetry environment activation guide: https://python-poetry.org/docs/managing-environments/#activating-the-environment
|
||||
|
||||
???+ important
|
||||
Starting from Poetry v2.0.0, `poetry shell` has been deprecated in favor of `poetry env activate`.
|
||||
|
||||
If your Poetry version is below v2.0.0, continue using `poetry shell` to activate your environment. For further guidance, refer to the Poetry Environment Activation Guide https://python-poetry.org/docs/managing-environments/#activating-the-environment.
|
||||
|
||||
@@ -1,34 +1,39 @@
|
||||
# Scan Multiple AWS Accounts
|
||||
# Scanning Multiple AWS Accounts with Prowler
|
||||
|
||||
Prowler can scan multiple accounts when it is executed from one account that can assume a role in those given accounts to scan using [Assume Role feature](role-assumption.md) and [AWS Organizations integration feature](organizations.md).
|
||||
Prowler enables security scanning across multiple AWS accounts by utilizing the [Assume Role feature](role-assumption.md) and [integration with AWS Organizations feature](organizations.md).
|
||||
|
||||
This approach allows execution from a single account with permissions to assume roles in the target accounts.
|
||||
|
||||
## Scan multiple specific accounts sequentially
|
||||
## Scanning Multiple Accounts Sequentially
|
||||
|
||||
- Declare a variable with all the accounts to scan:
|
||||
To scan specific accounts one at a time:
|
||||
|
||||
- Define a variable containing the AWS account IDs to be scanned:
|
||||
|
||||
```
|
||||
ACCOUNTS_LIST='11111111111 2222222222 333333333'
|
||||
```
|
||||
|
||||
- Then run Prowler to assume a role (change `<role_name>` below to yours, that must be the same in all accounts):
|
||||
- Run Prowler with an IAM role that exists in all target accounts: (replace the `<role_name>` with to yours, that is to be consistent throughout all accounts):
|
||||
|
||||
```
|
||||
ROLE_TO_ASSUME=<role_name>
|
||||
for accountId in $ACCOUNTS_LIST; do
|
||||
prowler aws --role arn:aws:iam::$accountId:role/$ROLE_TO_ASSUME
|
||||
for accountId in $ACCOUNTS_LIST; do
|
||||
prowler aws --role arn:aws:iam::$accountId:role/$ROLE_TO_ASSUME
|
||||
done
|
||||
```
|
||||
|
||||
## Scan multiple specific accounts in parallel
|
||||
## Scanning Multiple Accounts in Parallel
|
||||
|
||||
- Declare a variable with all the accounts to scan:
|
||||
- To scan multiple accounts simultaneously:
|
||||
|
||||
Define the AWS accounts to be scanned with a variable:
|
||||
|
||||
```
|
||||
ACCOUNTS_LIST='11111111111 2222222222 333333333'
|
||||
```
|
||||
|
||||
- Then run Prowler to assume a role (change `<role_name>` below to yours, that must be the same in all accounts), in this example it will scan 3 accounts in parallel:
|
||||
- Run Prowler with an IAM role that exists in all target accounts: (replace the `<role_name>` with to yours, that is to be consistent throughout all accounts). The following example executes scanning across three accounts in parallel:
|
||||
|
||||
```
|
||||
ROLE_TO_ASSUME=<role_name>
|
||||
@@ -41,25 +46,35 @@ for accountId in $ACCOUNTS_LIST; do
|
||||
done
|
||||
```
|
||||
|
||||
## Scan multiple accounts from AWS Organizations in parallel
|
||||
## Scanning Multiple AWS Organization Accounts in Parallel
|
||||
|
||||
- Declare a variable with all the accounts to scan. To do so, get the list of your AWS accounts in your AWS Organization by running the following command (will create a variable with all your ACTIVE accounts). Remember to run that command with the permissions needed to get that information in your AWS Organizations Management account.
|
||||
Prowler enables parallel security scans across multiple AWS accounts within an AWS Organization.
|
||||
|
||||
### Retrieve Active AWS Accounts
|
||||
|
||||
To efficiently scan multiple accounts within an AWS Organization, follow these steps:
|
||||
|
||||
- Step 1: Retrieve a List of Active Accounts
|
||||
|
||||
First, declare a variable containing all active accounts in your AWS Organization. Run the following command in your AWS Organizations Management account, ensuring that you have the necessary permissions:
|
||||
|
||||
```
|
||||
ACCOUNTS_IN_ORG=$(aws organizations list-accounts --query Accounts[?Status==`ACTIVE`].Id --output text)
|
||||
```
|
||||
|
||||
- Then run Prowler to assume a role (change `<role_name>` that must be the same in all accounts and `<management_organizations_account_id>` that must be your AWS Organizations management account ID):
|
||||
- Step 2: Run Prowler with Assumed Roles
|
||||
|
||||
Use Prowler to assume roles across accounts in parallel. Modify <role_name> to match the role that exists in all accounts and <management_organizations_account_id> to your AWS Organizations Management account ID.
|
||||
|
||||
```
|
||||
ROLE_TO_ASSUME=<role_name>
|
||||
MGMT_ACCOUNT_ID=<management_organizations_account_id>
|
||||
PARALLEL_ACCOUNTS="3"
|
||||
for accountId in $ACCOUNTS_IN_ORG; do
|
||||
test "$(jobs | wc -l)" -ge $PARALLEL_ACCOUNTS && wait || true
|
||||
{
|
||||
prowler aws --role arn:aws:iam::$accountId:role/$ROLE_TO_ASSUME \
|
||||
--organizations-role arn:aws:iam::$MGMT_ACCOUNT_ID:role/$ROLE_TO_ASSUME
|
||||
} &
|
||||
test "$(jobs | wc -l)" -ge $PARALLEL_ACCOUNTS && wait || true
|
||||
{
|
||||
prowler aws --role arn:aws:iam::$accountId:role/$ROLE_TO_ASSUME \
|
||||
--organizations-role arn:aws:iam::$MGMT_ACCOUNT_ID:role/$ROLE_TO_ASSUME
|
||||
} &
|
||||
done
|
||||
```
|
||||
|
||||
@@ -1,28 +1,39 @@
|
||||
# AWS Organizations
|
||||
# AWS Organizations in Prowler
|
||||
|
||||
## Get AWS Account details from your AWS Organization
|
||||
## Retrieving AWS Account Details
|
||||
|
||||
Prowler allows you to get additional information of the scanned account from AWS Organizations.
|
||||
If AWS Organizations is enabled, Prowler can fetch detailed account information during scans, including:
|
||||
|
||||
If you have AWS Organizations enabled, Prowler can get your account details like account name, email, ARN, organization id and tags and you will have them next to every finding's output.
|
||||
- Account Name
|
||||
- Email Address
|
||||
- ARN
|
||||
- Organization ID
|
||||
- Tags
|
||||
|
||||
In order to do that you can use the argument `-O`/`--organizations-role <organizations_role_arn>`. If this argument is not present Prowler will try to fetch that information automatically if the AWS account is a delegated administrator for the AWS Organization.
|
||||
These details will be included alongside each security finding in the output.
|
||||
|
||||
### Enabling AWS Organizations Data Retrieval
|
||||
|
||||
To retrieve AWS Organizations account details, use the `-O`/`--organizations-role <organizations_role_arn>` argument. If this argument is not provided, Prowler will attempt to fetch the data automatically—provided the AWS account is a delegated administrator for the AWS Organization.
|
||||
|
||||
???+ note
|
||||
Refer [here](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_delegate_policies.html) for more information about AWS Organizations delegated administrator.
|
||||
For more information on AWS Organizations delegated administrator, refer to the official documentation [here](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_delegate_policies.html).
|
||||
|
||||
See the following sample command:
|
||||
The following command is an example:
|
||||
|
||||
```shell
|
||||
prowler aws \
|
||||
-O arn:aws:iam::<management_organizations_account_id>:role/<role_name>
|
||||
```
|
||||
|
||||
???+ note
|
||||
Make sure the role in your AWS Organizations management account has the permissions `organizations:DescribeAccount` and `organizations:ListTagsForResource`.
|
||||
Ensure the IAM role used in your AWS Organizations management account has the following permissions:`organizations:DescribeAccount` and `organizations:ListTagsForResource`.
|
||||
|
||||
Prowler will scan the AWS account and get the account details from AWS Organizations.
|
||||
|
||||
In the JSON output below you can see tags coded in base64 to prevent breaking CSV or JSON due to its format:
|
||||
### Handling JSON Output
|
||||
|
||||
In Prowler’s JSON output, tags are encoded in Base64 to prevent formatting errors in CSV or JSON outputs. This ensures compatibility when exporting findings.
|
||||
|
||||
```json
|
||||
"Account Email": "my-prod-account@domain.com",
|
||||
@@ -34,17 +45,17 @@ In the JSON output below you can see tags coded in base64 to prevent breaking CS
|
||||
|
||||
The additional fields in CSV header output are as follows:
|
||||
|
||||
- ACCOUNT_DETAILS_EMAIL
|
||||
- ACCOUNT_DETAILS_NAME
|
||||
- ACCOUNT_DETAILS_ARN
|
||||
- ACCOUNT_DETAILS_ORG
|
||||
- ACCOUNT_DETAILS_TAGS
|
||||
- ACCOUNT\_DETAILS\_EMAIL
|
||||
- ACCOUNT\_DETAILS\_NAME
|
||||
- ACCOUNT\_DETAILS\_ARN
|
||||
- ACCOUNT\_DETAILS\_ORG
|
||||
- ACCOUNT\_DETAILS\_TAGS
|
||||
|
||||
## Extra: Run Prowler across all accounts in AWS Organizations by assuming roles
|
||||
|
||||
If you want to run Prowler across all accounts of AWS Organizations you can do this:
|
||||
### Running Prowler Across All AWS Organization Accounts
|
||||
|
||||
1. First get a list of accounts that are not suspended:
|
||||
1. To run Prowler across all accounts in AWS Organizations, first retrieve a list of accounts that are not suspended:
|
||||
|
||||
```shell
|
||||
ACCOUNTS_IN_ORGS=$(aws organizations list-accounts \
|
||||
@@ -65,5 +76,4 @@ If you want to run Prowler across all accounts of AWS Organizations you can do t
|
||||
```
|
||||
|
||||
???+ note
|
||||
Using the same for loop it can be scanned a list of accounts with a variable like:
|
||||
</br>`ACCOUNTS_LIST='11111111111 2222222222 333333333'`
|
||||
This same loop structure can be adapted to scan a predefined list of accounts using a variable like the following: </br>`ACCOUNTS_LIST='11111111111 2222222222 333333333'`
|
||||
|
||||
@@ -7,62 +7,81 @@ By default Prowler is able to scan the following AWS partitions:
|
||||
- GovCloud (US): `aws-us-gov`
|
||||
|
||||
???+ note
|
||||
To check the available regions for each partition and service please refer to the following document [aws_regions_by_service.json](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/aws_regions_by_service.json)
|
||||
To check the available regions for each partition and service, refer to: [aws\_regions\_by\_service.json](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/aws_regions_by_service.json)
|
||||
|
||||
It is important to take into consideration that to scan the China (`aws-cn`) or GovCloud (`aws-us-gov`) partitions it is either required to have a valid region for that partition in your AWS credentials or to specify the regions you want to audit for that partition using the `-f/--region` flag.
|
||||
## Scanning AWS China and GovCloud Partitions in Prowler
|
||||
|
||||
When scanning the China (`aws-cn`) or GovCloud (`aws-us-gov`), ensure one of the following:
|
||||
|
||||
- Your AWS credentials include a valid region within the desired partition.
|
||||
|
||||
- Specify the regions to audit within that partition using the `-f/--region` flag.
|
||||
|
||||
???+ note
|
||||
Please, refer to https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials for more information about the AWS credentials configuration.
|
||||
Refer to: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#configuring-credentials for more information about the AWS credential configuration.
|
||||
|
||||
### Scanning Specific Regions
|
||||
|
||||
To scan a particular AWS region with Prowler, use:
|
||||
|
||||
Prowler can scan specific region(s) with:
|
||||
```console
|
||||
prowler aws -f/--region eu-west-1 us-east-1
|
||||
```
|
||||
|
||||
You can get more information about the available partitions and regions in the following [Botocore](https://github.com/boto/botocore) [file](https://github.com/boto/botocore/blob/22a19ea7c4c2c4dd7df4ab8c32733cba0c7597a4/botocore/data/partitions.json).
|
||||
### AWS Credentials Configuration
|
||||
|
||||
For details on configuring AWS credentials, refer to the following [Botocore](https://github.com/boto/botocore) [file](https://github.com/boto/botocore/blob/22a19ea7c4c2c4dd7df4ab8c32733cba0c7597a4/botocore/data/partitions.json).
|
||||
|
||||
## AWS China
|
||||
## Scanning AWS Partitions in Prowler
|
||||
|
||||
To scan your AWS account in the China partition (`aws-cn`):
|
||||
### AWS China
|
||||
|
||||
To scan an account in the AWS China partition (`aws-cn`):
|
||||
|
||||
- By using the `-f/--region` flag:
|
||||
|
||||
```
|
||||
prowler aws --region cn-north-1 cn-northwest-1
|
||||
```
|
||||
|
||||
- By using the region configured in your AWS profile at `~/.aws/credentials` or `~/.aws/config`:
|
||||
|
||||
```
|
||||
[default]
|
||||
aws_access_key_id = XXXXXXXXXXXXXXXXXXX
|
||||
aws_secret_access_key = XXXXXXXXXXXXXXXXXXX
|
||||
region = cn-north-1
|
||||
```
|
||||
|
||||
- Using the `-f/--region` flag:
|
||||
```
|
||||
prowler aws --region cn-north-1 cn-northwest-1
|
||||
```
|
||||
- Using the region configured in your AWS profile at `~/.aws/credentials` or `~/.aws/config`:
|
||||
```
|
||||
[default]
|
||||
aws_access_key_id = XXXXXXXXXXXXXXXXXXX
|
||||
aws_secret_access_key = XXXXXXXXXXXXXXXXXXX
|
||||
region = cn-north-1
|
||||
```
|
||||
???+ note
|
||||
With this option all the partition regions will be scanned without the need of use the `-f/--region` flag
|
||||
With this configuration, all partition regions will be scanned without needing the `-f/--region` flag
|
||||
|
||||
### AWS GovCloud (US)
|
||||
|
||||
## AWS GovCloud (US)
|
||||
To scan an account in the AWS GovCloud (US) partition (`aws-us-gov`):
|
||||
|
||||
To scan your AWS account in the GovCloud (US) partition (`aws-us-gov`):
|
||||
- By using the `-f/--region` flag:
|
||||
|
||||
```
|
||||
prowler aws --region us-gov-east-1 us-gov-west-1
|
||||
```
|
||||
|
||||
- By using the region configured in your AWS profile at `~/.aws/credentials` or `~/.aws/config`:
|
||||
|
||||
```
|
||||
[default]
|
||||
aws_access_key_id = XXXXXXXXXXXXXXXXXXX
|
||||
aws_secret_access_key = XXXXXXXXXXXXXXXXXXX
|
||||
region = us-gov-east-1
|
||||
```
|
||||
|
||||
- Using the `-f/--region` flag:
|
||||
```
|
||||
prowler aws --region us-gov-east-1 us-gov-west-1
|
||||
```
|
||||
- Using the region configured in your AWS profile at `~/.aws/credentials` or `~/.aws/config`:
|
||||
```
|
||||
[default]
|
||||
aws_access_key_id = XXXXXXXXXXXXXXXXXXX
|
||||
aws_secret_access_key = XXXXXXXXXXXXXXXXXXX
|
||||
region = us-gov-east-1
|
||||
```
|
||||
???+ note
|
||||
With this option all the partition regions will be scanned without the need of use the `-f/--region` flag
|
||||
With this configuration, all partition regions will be scanned without needing the `-f/--region` flag
|
||||
|
||||
### AWS ISO (US \& Europe)
|
||||
|
||||
## AWS ISO (US & Europe)
|
||||
The AWS ISO partitions—commonly referred to as "secret partitions"—are air-gapped from the Internet, and Prowler does not have a built-in way to scan them. To audit an AWS ISO partition, manually update [aws\_regions\_by\_service.json](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/aws_regions_by_service.json) to include the partition, region, and services. For example:
|
||||
|
||||
For the AWS ISO partitions, which are known as "secret partitions" and are air-gapped from the Internet, there is no builtin way to scan it. If you want to audit an AWS account in one of the AWS ISO partitions you should manually update the [aws_regions_by_service.json](https://github.com/prowler-cloud/prowler/blob/master/prowler/providers/aws/aws_regions_by_service.json) and include the partition, region and services, e.g.:
|
||||
```json
|
||||
"iam": {
|
||||
"regions": {
|
||||
|
||||
@@ -1,9 +1,13 @@
|
||||
# Resource ARNs based Scan
|
||||
# Resource ARN-based Scanning
|
||||
|
||||
Prowler allows you to scan only the resources with specific AWS Resource ARNs. This can be done with the flag `--resource-arn` followed by one or more [Amazon Resource Names (ARNs)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) separated by space:
|
||||
Prowler enables scanning of resources based on specific AWS Resource ARNs.
|
||||
|
||||
## Resource ARN-Based Scanning
|
||||
|
||||
Prowler enables scanning of resources based on specific AWS Resource [Amazon Resource Names (ARNs)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). To perform this scan, use the designated flag `--resource-arn` followed by one or more ARNs, separated by spaces.
|
||||
|
||||
```
|
||||
prowler aws --resource-arn arn:aws:iam::012345678910:user/test arn:aws:ec2:us-east-1:123456789012:vpc/vpc-12345678
|
||||
```
|
||||
|
||||
This example will only scan the two resources with those ARNs.
|
||||
Example: This configuration scans only the specified two resources using their ARNs.
|
||||
|
||||
@@ -1,50 +1,74 @@
|
||||
# AWS Assume Role
|
||||
# AWS Assume Role in Prowler
|
||||
|
||||
Prowler uses the AWS SDK (Boto3) underneath so it uses the same authentication methods.
|
||||
## Authentication Overview
|
||||
|
||||
However, there are few ways to run Prowler against multiple accounts using IAM Assume Role feature depending on each use case:
|
||||
Prowler leverages the AWS SDK (Boto3) for authentication, following standard AWS authentication methods.
|
||||
|
||||
1. You can just set up your custom profile inside `~/.aws/config` with all needed information about the role to assume then call it with `prowler aws -p/--profile your-custom-profile`.
|
||||
- An example profile that performs role-chaining is given below. The `credential_source` can either be set to `Environment`, `Ec2InstanceMetadata`, or `EcsContainer`.
|
||||
- Alternatively, you could use the `source_profile` instead of `credential_source` to specify a separate named profile that contains IAM user credentials with permission to assume the target the role. More information can be found [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html).
|
||||
```
|
||||
[profile crossaccountrole]
|
||||
role_arn = arn:aws:iam::234567890123:role/SomeRole
|
||||
credential_source = EcsContainer
|
||||
```
|
||||
### Running Prowler Against Multiple Accounts
|
||||
|
||||
2. You can use `-R`/`--role <role_arn>` and Prowler will get those temporary credentials using `Boto3` and run against that given account.
|
||||
```sh
|
||||
prowler aws -R arn:aws:iam::<account_id>:role/<role_name>
|
||||
```
|
||||
- Optionally, the session duration (in seconds, by default 3600) and the external ID of this role assumption can be defined:
|
||||
To execute Prowler across multiple AWS accounts using IAM Assume Role, choose one of the following approaches:
|
||||
|
||||
```sh
|
||||
prowler aws -T/--session-duration <seconds> -I/--external-id <external_id> -R arn:aws:iam::<account_id>:role/<role_name>
|
||||
```
|
||||
1. Custom Profile Configuration
|
||||
|
||||
## Custom Role Session Name
|
||||
Set up a custom profile inside `~/.aws/config` with the necessary role information.
|
||||
|
||||
Then call the profile using `prowler aws -p/--profile your-custom-profile`.
|
||||
|
||||
- Role-Chaining Example Profile The `credential_source` parameter can be set to `Environment`, `Ec2InstanceMetadata`, or `EcsContainer`.
|
||||
|
||||
- Using an Alternative Named Profile
|
||||
|
||||
Instead of the `credential_source` parameter, `source_profile` can be used to specify a separate named profile.
|
||||
|
||||
This profile must contain IAM user credentials with permissions to assume the target role. For additional details, refer to the AWS Assume Role documentation: [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html).
|
||||
|
||||
```
|
||||
[profile crossaccountrole]
|
||||
role_arn = arn:aws:iam::234567890123:role/SomeRole
|
||||
credential_source = EcsContainer
|
||||
```
|
||||
|
||||
2. Using IAM Role Assumption in Prowler
|
||||
|
||||
To allow Prowler to retrieve temporary credentials by using `Boto3` and run assessments on the specified account, use the `-R`/`--role <role_arn>` flag.
|
||||
|
||||
```sh
|
||||
prowler aws -R arn:aws:iam::<account_id>:role/<role_name>
|
||||
```
|
||||
|
||||
**Defining Session Duration and External ID**
|
||||
|
||||
Optionally, specify the session duration (in seconds, default: 3600) and the external ID for role assumption:
|
||||
|
||||
```sh
|
||||
prowler aws -T/--session-duration <seconds> -I/--external-id <external_id> -R arn:aws:iam::<account_id>:role/<role_name>
|
||||
```
|
||||
|
||||
## Custom Role Session Name in Prowler
|
||||
|
||||
### Setting a Custom Session Name
|
||||
|
||||
Prowler allows you to specify a custom Role Session name using the following flag:
|
||||
|
||||
Prowler can use your custom Role Session name with:
|
||||
```console
|
||||
prowler aws --role-session-name <role_session_name>
|
||||
```
|
||||
|
||||
???+ note
|
||||
It defaults to `ProwlerAssessmentSession`.
|
||||
If not specified, it defaults to `ProwlerAssessmentSession`.
|
||||
|
||||
## Role MFA
|
||||
## Role MFA Authentication
|
||||
|
||||
If your IAM Role has MFA configured you can use `--mfa` along with `-R`/`--role <role_arn>` and Prowler will ask you to input the following values to get a new temporary session for the IAM Role provided:
|
||||
If your IAM Role is configured with Multi-Factor Authentication (MFA), use `--mfa` along with `-R`/`--role <role_arn>`. Prowler will prompt you to input the following values to obtain a temporary session for the IAM Role provided:
|
||||
|
||||
- ARN of your MFA device
|
||||
- TOTP (Time-Based One-Time Password)
|
||||
|
||||
## Create Role
|
||||
## Creating a Role for One or Multiple Accounts
|
||||
|
||||
To create a role to be assumed in one or multiple accounts you can use either as CloudFormation Stack or StackSet the following [template](https://github.com/prowler-cloud/prowler/blob/master/permissions/create_role_to_assume_cfn.yaml) and adapt it.
|
||||
To create an IAM role that can be assumed in one or multiple AWS accounts, use either a CloudFormation Stack or StackSet and adapt the provided [template](https://github.com/prowler-cloud/prowler/blob/master/permissions/create_role_to_assume_cfn.yaml).
|
||||
|
||||
???+ note "About Session Duration"
|
||||
Depending on the amount of checks you run and the size of your infrastructure, Prowler may require more than 1 hour to finish. Use option `-T <seconds>` to allow up to 12h (43200 seconds). To allow more than 1h you need to modify _"Maximum CLI/API session duration"_ for that particular role, read more [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session).
|
||||
???+ note
|
||||
**Session Duration Considerations**: Depending on the number of checks performed and the size of your infrastructure, Prowler may require more than 1 hour to complete. Use the `-T <seconds>` option to allow up to 12 hours (43,200 seconds). If you need more than 1 hour, modify the _“Maximum CLI/API session duration”_ setting for the role. Learn more [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session).
|
||||
|
||||
Bear in mind that if you are using roles assumed by role chaining there is a hard limit of 1 hour so consider not using role chaining if possible, read more about that, in foot note 1 below the table [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html).
|
||||
⚠️ Important: If assuming roles via role chaining, there is a hard limit of 1 hour. Whenever possible, avoid role chaining to prevent session expiration issues. More details are available in footnote 1 below the table in the [AWS IAM guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html).
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
# Send report to AWS S3 Bucket
|
||||
# Sending Reports to an AWS S3 Bucket
|
||||
|
||||
To save your report in an S3 bucket, use `-B`/`--output-bucket`.
|
||||
To save reports directly in an S3 bucket, use: `-B`/`--output-bucket`.
|
||||
|
||||
```sh
|
||||
prowler aws -B my-bucket
|
||||
```
|
||||
|
||||
If you can use a custom folder and/or filename, use `-o`/`--output-directory` and/or `-F`/`--output-filename`.
|
||||
### Custom Folder and Filename
|
||||
|
||||
For a custom folder and/or filename, specify: `-o`/`--output-directory` and/or `-F`/`--output-filename`.
|
||||
|
||||
```sh
|
||||
prowler aws \
|
||||
@@ -15,14 +17,16 @@ prowler aws \
|
||||
--output-filename output-filename
|
||||
```
|
||||
|
||||
By default Prowler sends HTML, JSON and CSV output formats, if you want to send a custom output format or a single one of the defaults you can specify it with the `-M`/`--output-modes` flag.
|
||||
### Custom Output Formats
|
||||
|
||||
By default, Prowler sends HTML, JSON, and CSV output formats. To specify a single output format, use the `-M`/`--output-modes` flag.
|
||||
|
||||
```sh
|
||||
prowler aws -M csv -B my-bucket
|
||||
```
|
||||
|
||||
|
||||
???+ note
|
||||
In the case you do not want to use the assumed role credentials but the initial credentials to put the reports into the S3 bucket, use `-D`/`--output-bucket-no-assume` instead of `-B`/`--output-bucket`.
|
||||
If you prefer using the initial credentials instead of the assumed role credentials for uploading reports, use `-D`/`--output-bucket-no-assume` instead of `-B`/`--output-bucket`.
|
||||
|
||||
???+ warning
|
||||
Make sure that the used credentials have `s3:PutObject` permissions in the S3 path where the reports are going to be uploaded.
|
||||
Ensure the credentials used have write permissions for the `s3:PutObject` where reports will be uploaded.
|
||||
|
||||
@@ -1,84 +1,92 @@
|
||||
# AWS Security Hub Integration
|
||||
# AWS Security Hub Integration with Prowler
|
||||
|
||||
Prowler supports natively and as **official integration** sending findings to [AWS Security Hub](https://aws.amazon.com/security-hub). This integration allows **Prowler** to import its findings to AWS Security Hub.
|
||||
Prowler natively supports **official integration** with [AWS Security Hub](https://aws.amazon.com/security-hub), allowing security findings to be sent directly. This integration enables **Prowler** to import its findings into AWS Security Hub.
|
||||
|
||||
To activate the integration, follow these steps in at least one AWS region within your AWS account:
|
||||
|
||||
Before sending findings, you will need to enable AWS Security Hub and the **Prowler** integration.
|
||||
## Enabling AWS Security Hub for Prowler Integration
|
||||
|
||||
## Enable AWS Security Hub
|
||||
To enable the integration, follow these steps in **at least** one AWS region within your AWS account.
|
||||
|
||||
To enable the integration you have to perform the following steps, in _at least_ one AWS region of a given AWS account, to enable **AWS Security Hub** and **Prowler** as a partner integration.
|
||||
Since **AWS Security Hub** is a region-based service, it must be activated in each region where security findings need to be collected.
|
||||
|
||||
Since **AWS Security Hub** is a region based service, you will need to enable it in the region or regions you require. You can configure it using the AWS Management Console or the AWS CLI.
|
||||
**Configuration Options**
|
||||
|
||||
AWS Security Hub can be enabled using either of the following methods:
|
||||
|
||||
???+ note
|
||||
Take into account that enabling this integration will incur in costs in AWS Security Hub, please refer to its pricing [here](https://aws.amazon.com/security-hub/pricing/) for more information.
|
||||
Enabling this integration incurs costs in AWS Security Hub. Refer to [this information](https://aws.amazon.com/security-hub/pricing/) for details.
|
||||
|
||||
### Using the AWS Management Console
|
||||
|
||||
#### Enable AWS Security Hub
|
||||
#### Enabling AWS Security Hub for Prowler Integration
|
||||
|
||||
If you have currently AWS Security Hub enabled you can skip to the [next section](#enable-prowler-integration).
|
||||
If AWS Security Hub is already enabled, you can proceed to the [next section](#enable-prowler-integration).
|
||||
|
||||
1. Open the **AWS Security Hub** console at https://console.aws.amazon.com/securityhub/.
|
||||
1. Enable AWS Security Hub via Console: Open the **AWS Security Hub** console: https://console.aws.amazon.com/securityhub/.
|
||||
|
||||
2. When you open the Security Hub console for the first time make sure that you are in the region you want to enable, then choose **Go to Security Hub**.
|
||||
|
||||
2. Ensure you are in the correct AWS region, then select “**Go to Security Hub**”. 
|
||||
|
||||
3. On the next page, the Security standards section lists the security standards that Security Hub supports. Select the check box for a standard to enable it, and clear the check box to disable it.
|
||||
3. In the “Security Standards” section, review the supported security standards. Select the checkbox for each standard you want to enable, or clear it to disable a standard.
|
||||
|
||||
4. Choose **Enable Security Hub**.
|
||||
|
||||
4. Choose “**Enable Security Hub**”. 
|
||||
|
||||
#### Enable Prowler Integration
|
||||
#### Enabling Prowler Integration in AWS Security Hub
|
||||
|
||||
If you have currently the Prowler integration enabled in AWS Security Hub you can skip to the [next section](#send-findings) and start sending findings.
|
||||
If the Prowler integration is already enabled in AWS Security Hub, you can proceed to the [next section](#send-findings) and begin sending findings.
|
||||
|
||||
Once **AWS Security Hub** is enabled you will need to enable **Prowler** as partner integration to allow **Prowler** to send findings to your **AWS Security Hub**.
|
||||
Once **AWS Security Hub** is activated, **Prowler** must be enabled as partner integration to allow security findings to be sent to it.
|
||||
|
||||
1. Open the **AWS Security Hub** console at https://console.aws.amazon.com/securityhub/.
|
||||
1. Enabling AWS Security Hub via Console
|
||||
Open the **AWS Security Hub** console: https://console.aws.amazon.com/securityhub/.
|
||||
|
||||
2. Select the **Integrations** tab in the right-side menu bar.
|
||||
|
||||
2. Select the “**Integrations**” tab from the right-side menu bar. 
|
||||
|
||||
3. Search for _Prowler_ in the text search box and the **Prowler** integration will appear.
|
||||
3. Search for “_Prowler_” in the text search box and the **Prowler** integration will appear.
|
||||
|
||||
4. Once there, click on **Accept Findings** to allow **AWS Security Hub** to receive findings from **Prowler**.
|
||||
|
||||
4. Click “**Accept Findings**” to authorize **AWS Security Hub** to receive findings from **Prowler**. 
|
||||
|
||||
5. A new modal will appear to confirm that you are enabling the **Prowler** integration.
|
||||
|
||||
5. A new modal will appear to confirm that the integration with **Prowler** is being enabled. 
|
||||
|
||||
6. Right after click on **Accept Findings**, you will see that the integration is enabled in **AWS Security Hub**.
|
||||
|
||||
6. Click “**Accept Findings**”, to authorize **AWS Security Hub** to receive findings from Prowler. 
|
||||
|
||||
### Using the AWS CLI
|
||||
### Using AWS CLI
|
||||
|
||||
To enable **AWS Security Hub** and the **Prowler** integration you have to run the following commands using the AWS CLI:
|
||||
To enable **AWS Security Hub** and integrate **Prowler**, execute the following AWS CLI commands:
|
||||
|
||||
**Step 1: Enable AWS Security Hub**
|
||||
|
||||
Run the following command to activate AWS Security Hub in the desired region:
|
||||
|
||||
```shell
|
||||
aws securityhub enable-security-hub --region <region>
|
||||
```
|
||||
???+ note
|
||||
For this command to work you will need the `securityhub:EnableSecurityHub` permission. You will need to set the AWS region where you want to enable AWS Security Hub.
|
||||
|
||||
Once **AWS Security Hub** is enabled you will need to enable **Prowler** as partner integration to allow **Prowler** to send findings to your AWS Security Hub. You have to run the following commands using the AWS CLI:
|
||||
???+ note
|
||||
This command requires the `securityhub:EnableSecurityHub` permission. Ensure you set the correct AWS region where you want to enable AWS Security Hub.
|
||||
|
||||
**Step 2: Enable Prowler Integration**
|
||||
|
||||
Once **AWS Security Hub** is activated, **Prowler** must be enabled as partner integration to allow security findings to be sent to it. Run the following AWS CLI commands:
|
||||
|
||||
```shell
|
||||
aws securityhub enable-import-findings-for-product --region eu-west-1 --product-arn arn:aws:securityhub:<region>::product/prowler/prowler
|
||||
```
|
||||
|
||||
???+ note
|
||||
You will need to set the AWS region where you want to enable the integration and also the AWS region also within the ARN. For this command to work you will need the `securityhub:securityhub:EnableImportFindingsForProduct` permission.
|
||||
Specify the AWS region where you want to enable the integration. Ensure the region is correctly set within the ARN value. This command requires the`securityhub:securityhub:EnableImportFindingsForProduct` permission.
|
||||
|
||||
## Sending Findings to AWS Security Hub
|
||||
|
||||
## Send Findings
|
||||
Once it is enabled, it is as simple as running the command below (for all regions):
|
||||
Once AWS Security Hub is enabled, findings can be sent using the following commands:
|
||||
|
||||
For all regions:
|
||||
|
||||
```sh
|
||||
prowler aws --security-hub
|
||||
```
|
||||
|
||||
or for only one filtered region like eu-west-1:
|
||||
For a specific region (e.g., eu-west-1):
|
||||
|
||||
```sh
|
||||
prowler --security-hub --region eu-west-1
|
||||
@@ -91,52 +99,60 @@ prowler --security-hub --region eu-west-1
|
||||
|
||||
To have updated findings in Security Hub you have to run Prowler periodically. Once a day or every certain amount of hours.
|
||||
|
||||
### See you Prowler findings in AWS Security Hub
|
||||
### Viewing Prowler Findings in AWS Security Hub
|
||||
|
||||
Once configured the **AWS Security Hub** in your next scan you will receive the **Prowler** findings in the AWS regions configured. To review those findings in **AWS Security Hub**:
|
||||
After enabling **AWS Security Hub**, findings from **Prowler** will be available in the configured AWS regions. Reviewing Prowler Findings in **AWS Security Hub**:
|
||||
|
||||
1. Open the **AWS Security Hub** console at https://console.aws.amazon.com/securityhub/.
|
||||
1. Enabling AWS Security Hub via Console
|
||||
|
||||
2. Select the **Findings** tab in the right-side menu bar.
|
||||
|
||||
Open the **AWS Security Hub** console: https://console.aws.amazon.com/securityhub/.
|
||||
|
||||
3. Use the search box filters and use the **Product Name** filter with the value _Prowler_ to see the findings sent from **Prowler**.
|
||||
2. Select the “**Findings**” tab from the right-side menu bar. 
|
||||
|
||||
4. Then, you can click on the check **Title** to see the details and the history of a finding.
|
||||
|
||||
3. Use the search box filters and apply the “**Product Name**” filter with the value _Prowler_ to display findings sent by **Prowler**.
|
||||
|
||||
As you can see in the related requirements section, in the detailed view of the findings, **Prowler** also sends compliance information related to every finding.
|
||||
4. Click the check “**Title**” to access its detailed view, including its history and status. 
|
||||
|
||||
## Send findings to Security Hub assuming an IAM Role
|
||||
#### Compliance Information
|
||||
|
||||
When you are auditing a multi-account AWS environment, you can send findings to a Security Hub of another account by assuming an IAM role from that account using the `-R` flag in the Prowler command:
|
||||
As outlined in the Requirements section, the detailed view includes compliance details for each finding reported by **Prowler**.
|
||||
|
||||
## Sending Findings to Security Hub with IAM Role Assumption
|
||||
|
||||
### Multi-Account AWS Auditing
|
||||
|
||||
When auditing a multi-account AWS environment, Prowler allows you to send findings to a Security Hub in another account by assuming an IAM role from that target account.
|
||||
|
||||
#### Using an IAM Role to Send Findings
|
||||
|
||||
To send findings to Security Hub, use the `-R` flag in the Prowler command:
|
||||
|
||||
```sh
|
||||
prowler --security-hub --role arn:aws:iam::123456789012:role/ProwlerExecutionRole
|
||||
```
|
||||
|
||||
???+ note
|
||||
Remember that the used role needs to have permissions to send findings to Security Hub. To get more information about the permissions required, please refer to the following IAM policy [prowler-security-hub.json](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-security-hub.json)
|
||||
The specified IAM role must have the necessary permissions to send findings to Security Hub. For details on the required permissions, refer to the IAM policy: [prowler-security-hub.json](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-security-hub.json)
|
||||
|
||||
## Sending Only Failed Findings to AWS Security Hub
|
||||
|
||||
## Send only failed findings to Security Hub
|
||||
|
||||
When using the **AWS Security Hub** integration you can send only the `FAIL` findings generated by **Prowler**. Therefore, the **AWS Security Hub** usage costs eventually would be lower. To follow that recommendation you could add the `--status FAIL` flag to the Prowler command:
|
||||
When using **AWS Security Hub** integration, **Prowler** allows sending only failed findings (`FAIL`), helping reduce **AWS Security Hub** usage costs. To enable this, add the `--status FAIL` flag to the Prowler command:
|
||||
|
||||
```sh
|
||||
prowler --security-hub --status FAIL
|
||||
```
|
||||
|
||||
You can use, instead of the `--status FAIL` argument, the `--send-sh-only-fails` argument to save all the findings in the Prowler outputs but just to send FAIL findings to AWS Security Hub:
|
||||
**Configuring Findings Output**
|
||||
|
||||
Instead of using `--status FAIL`, the `--send-sh-only-fails` argument to store all findings in Prowler outputs while sending only FAIL findings to AWS Security:
|
||||
|
||||
```sh
|
||||
prowler --security-hub --send-sh-only-fails
|
||||
```
|
||||
|
||||
## Skip sending updates of findings to Security Hub
|
||||
## Skipping Updates for Findings in Security Hub
|
||||
|
||||
By default, Prowler archives all its findings in Security Hub that have not appeared in the last scan.
|
||||
You can skip this logic by using the option `--skip-sh-update` so Prowler will not archive older findings:
|
||||
By default, Prowler archives any findings in Security Hub that were not detected in the latest scan. To prevent older findings from being archived, use the `--skip-sh-update` option:
|
||||
|
||||
```sh
|
||||
prowler --security-hub --skip-sh-update
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
# Tags-based Scan
|
||||
# Tag-based scan
|
||||
|
||||
Prowler allows you to scan only the resources that contain specific tags. This can be done with the flag `--resource-tags` followed by the tags `Key=Value` separated by space:
|
||||
Prowler provides the capability to scan only resources containing specific tags. To execute this, use the designated flag `--resource-tags` followed by the tags `Key=Value`, separated by spaces.
|
||||
|
||||
```
|
||||
prowler aws --resource-tags Environment=dev Project=prowler
|
||||
```
|
||||
|
||||
This example will only scan the resources that contains both tags.
|
||||
This configuration scans only resources that contain both specified tags.
|
||||
|
||||
@@ -1,28 +1,32 @@
|
||||
# Threat Detection
|
||||
# Threat Detection in AWS with Prowler
|
||||
|
||||
Prowler enables threat detection in AWS by analyzing CloudTrail log records. To execute threat detection checks, use the following command:
|
||||
|
||||
Prowler allows you to do threat detection in AWS based on the CloudTrail log records. To run checks related with threat detection use:
|
||||
```
|
||||
prowler aws --category threat-detection
|
||||
```
|
||||
This command will run these checks:
|
||||
|
||||
* `cloudtrail_threat_detection_privilege_escalation` -> Detects privilege escalation attacks.
|
||||
* `cloudtrail_threat_detection_enumeration` -> Detects enumeration attacks.
|
||||
* `cloudtrail_threat_detection_llm_jacking` -> Detects LLM Jacking attacks.
|
||||
This command runs checks to detect:
|
||||
|
||||
* `cloudtrail_threat_detection_privilege_escalation`: Privilege escalation attacks
|
||||
* `cloudtrail_threat_detection_enumeration`: Enumeration attacks
|
||||
* `cloudtrail_threat_detection_llm_jacking`: LLM Jacking attacks
|
||||
|
||||
???+ note
|
||||
Threat Detection checks will be only executed using `--category threat-detection` flag due to performance.
|
||||
Threat detection checks are executed only when the `--category threat-detection` flag is used, due to performance considerations.
|
||||
|
||||
## Config File
|
||||
## Config File for Threat Detection
|
||||
|
||||
If you want to manage the behavior of the Threat Detection checks you can edit `config.yaml` file from `/prowler/config`. In this file you can edit the following attributes related with Threat Detection:
|
||||
To manage the behavior of threat detection checks, edit the configuration file located in `config.yaml` file from `/prowler/config`. The following attributes can be modified, all related to threat detection:
|
||||
|
||||
* `threat_detection_privilege_escalation_threshold`: determines the percentage of actions found to decide if it is an privilege_scalation attack event, by default is 0.2 (20%)
|
||||
* `threat_detection_privilege_escalation_minutes`: it is the past minutes to search from now for privilege_escalation attacks, by default is 1440 minutes (24 hours)
|
||||
* `threat_detection_privilege_escalation_actions`: these are the default actions related with privilege escalation.
|
||||
* `threat_detection_enumeration_threshold`: determines the percentage of actions found to decide if it is an enumeration attack event, by default is 0.3 (30%)
|
||||
* `threat_detection_enumeration_minutes`: it is the past minutes to search from now for enumeration attacks, by default is 1440 minutes (24 hours)
|
||||
* `threat_detection_enumeration_actions`: these are the default actions related with enumeration attacks.
|
||||
* `threat_detection_llm_jacking_threshold`: determines the percentage of actions found to decide if it is an LLM Jacking attack event, by default is 0.4 (40%)
|
||||
* `threat_detection_llm_jacking_minutes`: it is the past minutes to search from now for LLM Jacking attacks, by default is 1440 minutes (24 hours)
|
||||
* `threat_detection_llm_jacking_actions`: these are the default actions related with LLM Jacking attacks.
|
||||
* `threat_detection_privilege_escalation_threshold`: Defines the percentage of actions required to classify an event as a privilege escalation attack. Default: 0.2 (20%)
|
||||
* `threat_detection_privilege_escalation_minutes`: Specifies the time window (in minutes) to search for privilege escalation attack patterns. Default: 1440 minutes (24 hours).
|
||||
* `threat_detection_privilege_escalation_actions`: Lists the default actions associated with privilege escalation attacks.
|
||||
* `threat_detection_enumeration_threshold`: Defines the percentage of actions required to classify an event as an enumeration attack. Default: 0.3 (30%)
|
||||
* `threat_detection_enumeration_minutes`: Specifies the time window (in minutes) to search for enumeration attack patterns. Default: 1440 minutes (24 hours).
|
||||
* `threat_detection_enumeration_actions`: Lists the default actions associated with enumeration attacks.
|
||||
* `threat_detection_llm_jacking_threshold`: Defines the percentage of actions required to classify an event as LLM jacking attack. Default: 0.4 (40%)
|
||||
* `threat_detection_llm_jacking_minutes`: Specifies the time window (in minutes) to search for LLM jacking attack patterns. Default: 1440 minutes (24 hours).
|
||||
* `threat_detection_llm_jacking_actions`: Lists the default actions associated with LLM jacking attacks.
|
||||
|
||||
Modify these attributes in the configuration file to fine-tune threat detection checks based on your security requirements.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Check mapping between Prowler v4/v3 and v2
|
||||
# Check Mapping Prowler v4/v3 to v2
|
||||
|
||||
Prowler v3 and v4 comes with different identifiers but we maintained the same checks that were implemented in v2. The reason for this change is because in previous versions of Prowler, check names were mostly based on CIS Benchmark for AWS. In v4 and v3 all checks are independent from any security framework and they have its own name and ID.
|
||||
Prowler v3 and v4 introduce distinct identifiers while preserving the checks originally implemented in v2. This change was made because, in previous versions, check names were primarily derived from the CIS Benchmark for AWS. Starting with v3 and v4, all checks are independent of any security framework and have unique names and IDs.
|
||||
|
||||
If you need more information about how new compliance implementation works in Prowler v4 and v3 see [Compliance](../compliance.md) section.
|
||||
For more details on the updated compliance implementation in Prowler v4 and v3, refer to the [Compliance](../compliance.md) section.
|
||||
|
||||
```
|
||||
checks_v4_v3_to_v2_mapping = {
|
||||
@@ -17,7 +17,7 @@ checks_v4_v3_to_v2_mapping = {
|
||||
"apigateway_restapi_public": "extra745",
|
||||
"apigateway_restapi_logging_enabled": "extra722",
|
||||
"apigateway_restapi_waf_acl_attached": "extra744",
|
||||
"apigatewayv2_api_access_logging_enabled": "extra7156",
|
||||
“apigatewayv2_api_access_logging_enabled": "extra7156",
|
||||
"apigatewayv2_api_authorizers_enabled": "extra7157",
|
||||
"appstream_fleet_default_internet_access_disabled": "extra7193",
|
||||
"appstream_fleet_maximum_session_duration": "extra7190",
|
||||
|
||||
Reference in New Issue
Block a user