Document permissions required, include terraform module (#9)

* Add terraform module for role to run rpCheckup

* Add shell script to run built rpCheckup with an assumed role

* Add permissions documentation to the readme

* Added README in terraform/ to include instructions on how to use it.

* Add check for aws cli to run_with_role.sh

Co-authored-by: Greg Soltis <greg@goldfiglabs.ciom>
Co-authored-by: Vikrum Nijjar <vsnijjar@gmail.com>

Author: 3 people

README.md

@@ -74,6 +74,24 @@ Run `./rpCheckup` and view the generated report found in `output/`.
 
 <img width="800" alt="Screen Shot 2021-03-01 at 12 22 36 PM" src="https://user-images.githubusercontent.com/291215/109732631-61122780-7b72-11eb-8f6d-1b51758d2f19.png">
 
+## Permissions
+
+rpCheckup needs read-only access to portions of your AWS account.
+A principal (user/role/group) needs the following to make full use 
+of rpCheckup:
+
+```
+AWS Managed Policy: arn:aws:iam::aws:policy/SecurityAudit
+AWS Managed Policy: arn:aws:iam::aws:policy/job-function/ViewOnlyAccess
+Additional Permissions:
+  "apigateway:GetRestApis",
+  "efs:Describe*",
+  "acm-pca:List*",
+  "acm-pca:GetPolicy"
+```
+
+Additionally, there is a [Terraform Module](./terraform) for creating a role with the appropriate credentials, as well as a [shell script](./run_with_role.sh) for running with an assumed role (requires running [./build.sh](./build.sh) first).
+
 ## Overview
 rpCheckup uses [goldfiglabs/introspector](https://github.com/goldfiglabs/introspector) to snapshot the configuration of your AWS account. rpCheckup runs SQL queries to generate findings based on this snapshot. Introspector does the heavy lifting of importing and normalizing the configurations while rpCheckup is responsible for querying and report generation.
 

run_with_role.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+
+set -e
+
+if [[ -z $(which jq) ]]; then
+  echo "script requires jq"
+  exit 1
+fi
+
+if [[ -z $(which aws) ]]; then
+  echo "script requires aws cli"
+  exit 1
+fi
+
+if [[ -z $1 ]]; then
+  echo "usage: ./run_with_role.sh <ROLE_ARN> [<SESSION_NAME>]"
+  exit 2
+fi
+
+if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+  bin="rpCheckup_linux"
+elif [[ "$OSTYPE" == "darwin"* ]]; then
+  arch=$(uname -m)
+  if [[ $arch == "arm64" ]]; then
+    bin="rpCheckup_darwin_arm64"
+  else
+    bin="rpCheckup_darwin_amd64"
+  fi
+else
+  echo "Unsupported OS ${OSTYPE}"
+  exit 3
+fi
+
+ROLE_ARN=$1
+SESSION_NAME=${2:-rpCheckupSession}
+
+cmd="aws sts assume-role --role-arn ${ROLE_ARN} --role-session-name ${SESSION_NAME}"
+creds=$($cmd)
+accessKeyId=$(echo $creds | jq -r '.Credentials.AccessKeyId')
+secretKey=$(echo $creds | jq -r '.Credentials.SecretAccessKey')
+sessionToken=$(echo $creds | jq -r '.Credentials.SessionToken')
+
+AWS_ACCESS_KEY_ID=$accessKeyId \
+  AWS_SECRET_ACCESS_KEY=$secretKey \
+  AWS_SESSION_TOKEN=$sessionToken \
+  dist/${bin}

terraform/.gitignore

@@ -0,0 +1,2 @@
+.terraform*
+*.tfstate

terraform/README.md

@@ -0,0 +1,11 @@
+# rpCheckup Terraform permissions role
+
+This Terraform module creates a role in the AWS account you are currently signed in to. Review the permissions in `main.tf`.
+
+Use Terraform to create the role in your account:
+
+1. terraform init
+2. terraform plan
+3. terraform apply
+
+Upon success, the Terraform run will output an ARN. This can be used by `run_with_role.sh` to invoke rpCheckup with the newly created role.

terraform/main.tf

@@ -0,0 +1,60 @@
+provider "aws" {
+  region = var.region
+}
+
+data "aws_caller_identity" "current" {}
+
+resource "aws_iam_role" "rpcheckup" {
+  name = var.role_name
+  assume_role_policy = <<EOF
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": "sts:AssumeRole",
+      "Principal": {
+        "AWS": "${data.aws_caller_identity.current.account_id}"
+      },
+      "Effect": "Allow",
+      "Sid": ""
+    }
+  ]
+}
+EOF
+}
+
+resource "aws_iam_policy" "rpcheckup" {
+  name = "rpCheckupExtraPermissions"
+  policy = jsonencode(
+    {
+      "Statement" = [
+        {
+          Action = [
+            "apigateway:GetRestApis",
+            "efs:Describe*",
+            "acm-pca:List*",
+            "acm-pca:GetPolicy"
+          ],
+          Effect = "Allow",
+          Resource = "*"
+        }
+      ],
+      Version = "2012-10-17"
+    }
+  )
+}
+
+resource "aws_iam_role_policy_attachment" "extra_permissions" {
+  role = aws_iam_role.rpcheckup.name
+  policy_arn = aws_iam_policy.rpcheckup.arn
+}
+
+resource "aws_iam_role_policy_attachment" "security_audit" {
+  role = aws_iam_role.rpcheckup.name
+  policy_arn = "arn:aws:iam::aws:policy/SecurityAudit"
+}
+
+resource "aws_iam_role_policy_attachment" "view_only" {
+  role = aws_iam_role.rpcheckup.name
+  policy_arn = "arn:aws:iam::aws:policy/job-function/ViewOnlyAccess"
+}

terraform/outputs.tf

@@ -0,0 +1,3 @@
+output "arn" {
+  value = aws_iam_role.rpcheckup.arn
+}

terraform/variables.tf

@@ -0,0 +1,7 @@
+variable "role_name" {
+  default = "rpCheckup"
+}
+
+variable "region" {
+  default = "us-east-1"
+}