diff --git a/docs/user-guide/providers/aws/role-assumption.mdx b/docs/user-guide/providers/aws/role-assumption.mdx index 3a2461b50b..ef45e56441 100644 --- a/docs/user-guide/providers/aws/role-assumption.mdx +++ b/docs/user-guide/providers/aws/role-assumption.mdx @@ -69,7 +69,19 @@ If your IAM Role is configured with Multi-Factor Authentication (MFA), use `--mf ## 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](https://github.com/prowler-cloud/prowler/blob/master/permissions/create_role_to_assume_cfn.yaml). +To create an IAM role that can be assumed in one or multiple AWS accounts, use either a CloudFormation Stack or StackSet with the provided [template](https://github.com/prowler-cloud/prowler/blob/master/permissions/create_role_to_assume_cfn.yaml). + +The template requires the following parameters: + +- **AuthorisedARN:** The ARN of the user or role authorized to assume the created role (e.g., `arn:aws:iam::123456789012:root`) +- **ExternalId:** A unique identifier to prevent the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) +- **ProwlerRoleName:** *(Optional)* Name of the IAM role (default: `ProwlerScanRole`) + +When running Prowler, include the External ID using the `-I/--external-id` flag: + +```sh +prowler aws -R arn:aws:iam:::role/ -I +``` **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 ` 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). diff --git a/permissions/create_role_to_assume_cfn.yaml b/permissions/create_role_to_assume_cfn.yaml index 3e950102c5..0f41421808 100644 --- a/permissions/create_role_to_assume_cfn.yaml +++ b/permissions/create_role_to_assume_cfn.yaml @@ -5,7 +5,8 @@ AWSTemplateFormatVersion: '2010-09-09' # --capabilities CAPABILITY_IAM --capabilities CAPABILITY_NAMED_IAM \ # --template-body "file://create_role_to_assume_cfn.yaml" \ # --stack-name "ProwlerScanRole" \ -# --parameters "ParameterKey=AuthorisedARN,ParameterValue=arn:aws:iam::123456789012:root" +# --parameters "ParameterKey=AuthorisedARN,ParameterValue=arn:aws:iam::123456789012:root" \ +# "ParameterKey=ExternalId,ParameterValue=YourExternalId" # Description: | This template creates an AWS IAM Role with an inline policy and two AWS managed policies @@ -20,6 +21,13 @@ Parameters: ARN of user who is authorised to assume the role that is created by this template. E.g., arn:aws:iam::123456789012:root Type: String + ExternalId: + Description: | + This is the External ID that Prowler will use to assume the role. + Type: String + MinLength: 1 + AllowedPattern: ".+" + ConstraintDescription: "ExternalId must not be empty." ProwlerRoleName: Description: | Name of the IAM role that will have these policies attached. Default: ProwlerScanRole @@ -37,10 +45,12 @@ Resources: Principal: AWS: !Sub ${AuthorisedARN} Action: 'sts:AssumeRole' - ## In case MFA is required uncomment lines below and read https://github.com/prowler-cloud/prowler#run-prowler-with-mfa-protected-credentials - # Condition: - # Bool: - # 'aws:MultiFactorAuthPresent': true + Condition: + StringEquals: + 'sts:ExternalId': !Ref ExternalId + ## In case MFA is required uncomment lines below and read https://github.com/prowler-cloud/prowler#run-prowler-with-mfa-protected-credentials + # Bool: + # 'aws:MultiFactorAuthPresent': true # This is 12h that is maximum allowed, Minimum is 3600 = 1h # to take advantage of this use -T like in './prowler --role ProwlerScanRole.ARN -T 43200' MaxSessionDuration: 43200