Skip to content

AWS Assume Role

Prowler uses the AWS SDK (Boto3) underneath so it uses the same authentication methods.

However, there are few ways to run Prowler against multiple accounts using IAM Assume Role feature depending on each use case:

  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.
  2. An example profile that performs role-chaining is given below. The credential_source can either be set to Environment, Ec2InstanceMetadata, or EcsContainer.

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

    [profile crossaccountrole]
role_arn = arn:aws:iam::234567890123:role/SomeRole
credential_source = EcsContainer

  4. You can use -R/--role <role_arn> and Prowler will get those temporary credentials using Boto3 and run against that given account. 

    prowler aws -R arn:aws:iam::<account_id>:role/<role_name>

  5. Optionally, the session duration (in seconds, by default 3600) and the external ID of this role assumption can be defined:
prowler aws -T/--session-duration <seconds> -I/--external-id <external_id> -R arn:aws:iam::<account_id>:role/<role_name>

Custom Role Session Name

Prowler can use your custom Role Session name with: 

prowler aws --role-session-name <role_session_name>

Note

It defaults to ProwlerAssessmentSession.

STS Endpoint Region

If you are using Prowler in AWS regions that are not enabled by default you need to use the argument --sts-endpoint-region to point the AWS STS API calls assume-role and get-caller-identity to the non-default region, e.g.: prowler aws --sts-endpoint-region eu-south-2.

Note

Since v3.11.0, Prowler uses a regional token in STS sessions so it can scan all AWS regions without needing the --sts-endpoint-region argument. Make sure that you have enabled the AWS Region you want to scan in BOTH AWS Accounts (assumed role account and account from which you assume the role).

Role MFA

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:

  • ARN of your MFA device
  • TOTP (Time-Based One-Time Password)

Create Role

To create a role to be assumed in one or multiple accounts you can use either as CloudFormation Stack or StackSet the following template and adapt it.

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.

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.