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>

docs/tutorials/aws/role-assumption.md

@@ -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).