Automate the AWS GuardDuty account invitation lifecycle for all of your organizations AWS accounts in all regions as well as aggregate and normalize the GuardDuty findings
Above is an example architecture for a master account with a member account. Note: The member account has GuardDuty detectors in every region as does the master account.
As a multi-account user of Amazon Web Services you have a few choices when deciding to turn on GuardDuty across your accounts.
Your options are:
- Stack Sets
- Human invitations
- Something else.
Due to the nature of stack sets and the distributed governance of Mozilla it breaks our trust model to grant the needed permissions to run stack sets. Human behavior consistently generates inconsistent results.
This is why we elected to create GuardDuty Multi-Account Manager
GuardDuty Multi-Account Manager is a series of lambda functions designed to do the following:
- Enable GuardDuty Masters in all AWS Regions present and future.
- Empower account owners to decide to enable GuardDuty
- Manage the lifecycle of invitations to the member accounts
- Aggregate all findings from all detectors in all regions, normalize the data, and send to a single SQS queue
- AWS Organizations
- Either run the GuardDuty Multi-Account Manager from within an AWS Organizations parent account or
- Establish an IAM Role in the AWS Organizations parent account that can be assumed by the GuardDuty Multi-Account Manager. Example IAM Role
- Deploy the
Cloudformation Cross Account Outputs
service which allows CloudFormation stacks in other AWS accounts to report
back output. This is used to convey the
GuardDuty Member Account IAM Role
information. In order to deploy this service
follow the instructions in the README
which explains how.
- Make sure that in Step 1 and 2 you deploy each template in only one region. These resources shouldn't be deployed multiple times in an AWS account.
- Make sure that in Step 3, you deploy the
cloudformation-sns-emission-consumer.ymltemplate in every region that you want to allow your GuardDuty members to potentially deploy the GuardDuty member role in. For example, in the includedguardduty-member-account-role.yml, it assumes that you'll have deployedcloudformation-sns-emission-consumer.ymlin bothus-west-2andus-east-1
- Customize the
guardduty-member-account-role.ymlCloudFormation template which you'll distribute to your members.- You need to set two values in the
Mappingssection of the templateMasterAccount:Principal: Set this to the root principal of your AWS account in which you're running the GuardDuty master. For examplearn:aws:iam::123456789012:rootSNSTopicForPublishingIAMRoleArn:Account: Set this to the AWS Account ID of the AWS account that you've deployed the Cloudformation Cross Account Outputs service in. For example123456789012.
- Add any additional regions that you wish to support (which you've deployed
Cloudformation Cross Account Outputs in) into the
TheRegionYouAreDeployingInmapping following the example of the existing two regions listed there already.
- You need to set two values in the
-
Deploy the Cloudformation Stack from
cloudformation/guardduty-multi-account-manager-parent.ymlin the master account. -
The stack will spin up and create all Master Detectors in all regions, a normalization functions, and all SNS Topics with CloudWatch events.
- Ensure that the the mappings are configured in the
cloudformation/guardduty-member-account-role.ymltemplate as described above - Deploy the customized
cloudformation/guardduty-member-account-role.ymlCloudFormation template in your member AWS accounts. This CloudFormation template should only be deployed once in a single region in each member AWS account. The account will then register with the master account and go through the invitation process automatically for every region.
- Watch our presentation on GuardDuty Multi Account Manager at AWS re:Invent 2018
- Read the slides
guardduty-multi-account-manager is Licensed under the Mozilla Public License 2.0 ( MPL2.0 )