AWS Assume Role in Prowler

Authentication Overview

Prowler leverages the AWS SDK (Boto3) for authentication, following standard AWS authentication methods.

Running Prowler Against Multiple Accounts

To execute Prowler across multiple AWS accounts using IAM Assume Role, choose one of the following approaches:

1. Custom Profile Configuration

   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.

     [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.

   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:

   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 aws --role-session-name <role_session_name>

Note

If not specified, it defaults to ProwlerAssessmentSession.

Role MFA Authentication

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)

Creating a Role for One or Multiple Accounts

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.

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.

⚠️ 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.