prowler/util/org-multi-account/README.md

Organizational Prowler Deployment

Created by: Julio Delgado Jr. delgjul@amazon.com

Deploys Prowler to assess all Accounts in an AWS Organization on a schedule, create assessment reports in HTML, and store them in an S3 bucket.

Prowler is an independent third-party command line tool for AWS Security Best Practices Assessment, Auditing, Hardening, and Forensic Readiness. It evaluates guidelines of the CIS Amazon Web Services Foundations Benchmark and dozens of additional checks, including for GDPR, and HIPAA.

---

Solution Goals

• Use minimal technologies, so solution can be more easily adopted, and further enhanced as needed.
  • Amazon EC2, to run Prowler
  • Amazon S3, to store Prowler script & reports.
  • AWS CloudFormation, to provision the AWS resources.
  • AWS Systems Manager Session Manager, Optional, but recommended, to manage the Prowler EC2 instance, without having to allow inbound ssh.
• Staying cohesive with Prowler, for scripting, only leveraging:
  • Bash Shell
  • AWS CLI
• Adhere to the principle of least privilege.
• Support an AWS Multi-Account approach
  • Runs Prowler against All accounts in the AWS Organization

---

Components

1. ProwlerS3.yaml
   • Creates Private S3 Bucket for Prowler script and reports.
   • Public Access Block permissions enabled.
   • SSE-S3 used with Amazon S3 Default Encryption
   • Versioning Enabled
   • Bucket Policy only grants GetObject, PutObject, and ListObject to Principals from the same AWS Organization.
2. ProwlerRole.yaml
   • Creates Cross-Account Role for Prowler to assess accounts in AWS Organization
   • Allows Role to be assumed by the Prowler EC2 instance role in the AWS account where Prowler EC2 resides (preferably the Audit/Security account).
   • Role has permissions needed for Prowler to assess accounts.
   • Role has GetObject, PutObject, and ListObject rights to Prowler S3 from Component #1.
3. ProwlerEC2.yaml
   • Creates Prowler EC2 instance
     • Uses the Latest Amazon Linux 2 AMI
     • Uses "t2.micro" Instance Type
   • Uses cfn-init for prepping the Prowler EC2
     • Installs necessary packages for Prowler
     • Downloads run-prowler-reports.sh script from Prowler S3 from Component #1.
     • Creates /home/ec2-user/.awsvariables, to store CloudFormation data as variables to be used in script.
     • Creates cron job for Prowler to run on a schedule.
   • Creates Prowler Security Group
     • Denies inbound access. If using ssh to manage Prowler, then update Security Group with pertinent rule.
     • Allows outbound 80/443 for updates, and Amazon S3 communications
   • Creates Instance Role that is used for Prowler EC2
     • Role has permissions for Systems Manager Agent communications, and Session Manager
     • Role has GetObject, PutObject, and ListObject rights to Prowler S3 from Component #1.
     • Role has rights to Assume Cross-Account Role from Component #2.
4. run-prowler-reports.sh

   • Script is documented accordingly.

   • Script loops through all AWS Accounts in AWS Organization, and by default, Runs Prowler as follows:

     • -R: used to specify Cross-Account role for Prowler to assume to run its assessment.

     • -A: used to specify AWS Account number for Prowler to run assessment against.

     • -g cislevel1: used to specify cislevel1 checks for Prowler to assess

     • ansi2html -la: used to generate HTML assessment report

       ./prowler/prowler -R "$ROLE" -A "$accountId" -g cislevel1 | ansi2html -la >"$Report"
       

     • NOTE: Script can be modified to run Prowler as desired.

   • Script runs Prowler against 1 AWS Account at a time.

     • Update PARALLEL_ACCOUNTS variable in script, to specify how many Accounts to assess with Prowler in parallel.

     • If running against multiple AWS Accounts in parallel, monitor performance, and upgrade Instance Type as necessary.

       PARALLEL_ACCOUNTS="1"
       

   • In summary:

     • Download latest version of Prowler
     • Find AWS Master Account
     • Lookup All Accounts in AWS Organization
     • Run Prowler against All Accounts in AWS Organization
     • Save Reports to reports prefix in S3 from Component #1
     • Report Names: date+time-accountid-report.html

---

Instructions

1. Deploy ProwlerS3.yaml in the Logging Account.
   • Could be deployed to any account in the AWS Organizations, if desired.
   • See How to get AWS Organization ID
   • Take Note of CloudFormation Outputs, that will be needed in deploying the below CloudFormation templates.
2. Upload run-prowler-reports.sh to the root of the S3 Bucket created in Step #1.
3. Deploy ProwlerRole.yaml in the Master Account
   • Use CloudFormation Stacks, to deploy to Master Account, as organizational StackSets don't apply to the Master Account.
   • Use CloudFormation StackSet, to deploy to all Member Accounts. See Create Stack Set with Service-Managed Permissions
   • Take Note of CloudFormation Outputs, that will be needed in deploying the below CloudFormation templates.
4. Deploy ProwlerEC2.yaml in the Audit/Security Account
   • Could be deployed to any account in the AWS Organizations, if desired.
5. Prowler will run against all Accounts in AWS Organization, based on the schedule you provided, and therefore set in a cron job for ec2-user.

---

Post-Setup

Run Prowler on a Schedule against all Accounts in AWS Organization

1. Prowler will run on the Schedule you provided.
2. Cron job for ec2-user is managing the schedule.
3. This solution implemented this automatically. Nothing for you to do.

Run Prowler Adhoc against all Accounts in AWS Organization

1. Connect to Prowler EC2 Instance

   • If using Session Manager, then after login, switch to "ec2-user", via: sudo -u ec2-user
   • If using SSH, then login as "ec2-user"

2. Run Prowler Script

   cd /home/ec2-user
   ./run-prowler-reports.sh
   

Run Prowler Adhoc Interactively

1. Connect to Prowler EC2 Instance

   • If using Session Manager, then after login, switch to "ec2-user", via: sudo -u ec2-user
   • If using SSH, then login as "ec2-user"

2. See Cross-Account Role and S3 Bucket being used for Prowler

   cd /home/ec2-user
   cat .awsvariables
   

3. Run Prowler interactively. See Usage Examples

   cd /home/ec2-user
   ./prowler/prowler
   

Upgrading Prowler to Latest Version

1. Connect to Prowler EC2 Instance

   • If using Session Manager, then after login, switch to "ec2-user", via: sudo -u ec2-user
   • If using SSH, then login as "ec2-user"

2. Delete the existing version of Prowler, and download the latest version of Prowler

   cd /home/ec2-user
   rm -rf prowler
   git clone https://github.com/toniblyx/prowler.git