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>

include/assume_role

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+
+# Prowler - the handy cloud security tool (copyright 2019) by Toni de la Fuente
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy
+# of the License at http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+
+# both variables are mandatory to be set together 
+if [[ $ACCOUNT_TO_ASSUME ]]; then
+    if [[ -z $ROLE_TO_ASSUME ]]; then
+        echo "$OPTRED ERROR!$OPTNORMAL - Both Account ID (-A) and IAM Role to assume (-R) must be set"
+        exit 1
+    fi 
+    # if not session duration set with -T, then will be 1h. 
+    # In some cases you will need more than 1h.
+    if [[ -z $SESSION_DURATION_TO_ASSUME ]]; then
+        SESSION_DURATION_TO_ASSUME="3600"
+    fi
+
+    # temporary file where to store credentials
+    TEMP_STS_ASSUMED_FILE=$(mktemp -t prowler.sts_assumed-XXXXXX)
+
+    # assume role command
+    $AWSCLI sts assume-role --role-arn arn:aws:iam::$ACCOUNT_TO_ASSUME:role/$ROLE_TO_ASSUME \
+        --role-session-name ProwlerAssessmentSession \
+        --duration-seconds $SESSION_DURATION_TO_ASSUME > $TEMP_STS_ASSUMED_FILE 
+
+    # if previous command fails exit with the given error from aws-cli
+    # this is likely to be due to session duration limit of 1h in case 
+    # of assume role chaining:
+    # "The requested DurationSeconds exceeds the 1 hour session limit 
+    # for roles assumed by role chaining."
+    # https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html
+    if [[ $? != 0 ]];then
+        exit 1
+    fi
+
+    cat $TEMP_STS_ASSUMED_FILE
+
+    # set env variables with assumed role credentials
+    AWS_ACCESS_KEY_ID=$(cat $TEMP_STS_ASSUMED_FILE | jq -r '.Credentials.AccessKeyId')
+    AWS_SECRET_ACCESS_KEY=$(cat $TEMP_STS_ASSUMED_FILE | jq -r '.Credentials.SecretAccessKey')
+    AWS_SESSION_TOKEN=$(cat $TEMP_STS_ASSUMED_FILE | jq -r '.Credentials.SessionToken')
+
+    aws sts get-caller-identity
+
+    rm -fr $TEMP_STS_ASSUMED_FILE
+fi

prowler

@@ -77,12 +77,18 @@ USAGE:
       -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
   "
   exit
 }
 
-while getopts ":hlLkqp:r:c:g:f:m:M:E:enbVsx:" OPTION; do
+while getopts ":hlLkqp:r:c:g:f:m:M:E:enbVsx:A:R:T:" OPTION; do
    case $OPTION in
      h )
         usage
@@ -145,6 +151,15 @@ while getopts ":hlLkqp:r:c:g:f:m:M:E:enbVsx:" OPTION; do
      q )
         QUIET=1
         ;;
+     A )
+        ACCOUNT_TO_ASSUME=$OPTARG
+        ;;
+     R )
+        ROLE_TO_ASSUME=$OPTARG
+        ;;
+     T )
+        SESSION_DURATION_TO_ASSUME=$OPTARG
+        ;;
      : )
         echo ""
         echo "$OPTRED ERROR!$OPTNORMAL  -$OPTARG requires an argument"
@@ -175,6 +190,7 @@ done
 . $PROWLER_DIR/include/python_detector
 . $PROWLER_DIR/include/secrets_detector
 . $PROWLER_DIR/include/check3x
+. $PROWLER_DIR/include/assume_role
 
 # Get a list of all available AWS Regions
 REGIONS=$($AWSCLI ec2 describe-regions --query 'Regions[].RegionName' \