Add native support for AssumeRole issue #445

README.md

@@ -6,6 +6,7 @@
 - [Features](#features)
 - [Requirements and Installation](#requirements-and-installation)
 - [Usage](#usage)
+- [Advanced Usage](#advanced-usage)
 - [Fix](#fix)
 - [Screenshots](#screenshots)
 - [Troubleshooting](#troubleshooting)
@@ -222,10 +223,50 @@ This script has been written in bash using AWS-CLI and it works in Linux and OSX
         -b                  do not print Prowler banner
         -V                  show version number & exit
         -s                  show scoring report
+        -x                  specify external directory with custom checks (i.e. /my/own/checks, files must start by check)
         -q                  suppress info messages and passing test output
+        -A                  account id for the account where to assume a role, requires -R and -T
+                              (i.e.: 123456789012)
+        -R                  role name to assume in the account, requires -A and -T
+                              (i.e.: ProwlerRole)
+        -T                  session durantion given to that role credentials in seconds, default 1h (3600) recommended 12h, requires -R and -T
+                              (i.e.: 43200)
         -h                  this help
     ```
 
+## Advanced Usage
+
+### Assume Role: 
+
+Prowler uses the AWS CLI 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 eachg use case. 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 -p your-custom-profile`. Additionally you can use `-A 123456789012` and `-R RemoteRoleToAssume` and Prowler will get those temporary credentials using `aws sts assume-role`, set them up as environment variables and run against that given account.
+
+```
+./prowler -A 123456789012 -R ProwlerRole 
+```
+
+> *NOTE 1 about Session Duration*: By default it gets credentials valid for 1 hour (3600 seconds). Depending on the mount 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 2 about Session Duration*: 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). 
+
+For example, if you want to get only the fails in CSV format from all checks regarding RDS without banner from the AWS Account 123456789012 assuming the role RemoteRoleToAssume and set a fixed session duration of 1h:
+
+```
+./prowler -A 123456789012 -R RemoteRoleToAssume -T 3600 -b -M cvs -q -g rds
+```
+
+### Custom folder for custom checks
+
+Flag `-x /my/own/checks` will include any check in that particular directory. To see how to write checks see [Add Custom Checks](#add-custom-checks) section.
+
+### Show or log only FAILs
+
+In order to remove noise and get only FAIL findings there is a `-q` flag that makes Prowler to show and log only FAILs. It can be combined with any other option.
+
+```
+./prowler -q -M csv -b
+```
+
+
 ## How to fix every FAIL
 
 Check your report and fix the issues following all specific guidelines per check in <https://d0.awsstatic.com/whitepapers/compliance/AWS_CIS_Foundations_Benchmark.pdf>