Amazon GuardDuty continuously monitors your AWS accounts and uses threat intelligence to identify unexpected and potentially malicious activity within your AWS environment. Manually enabling GuardDuty for multiple accounts or organizations, across multiple regions, or through the console can be cumbersome. Terraform can be used to automate the process.
AWS recommends using AWS Organizations to create and administer multi-account environments. This pattern follows that recommendation. One benefit of this approach is that, when new accounts are created or added to the Organization, GuardDuty will be auto-enabled in these accounts for all supported regions.
This pattern demonstrates how to use Terraform to enable Amazon GuardDuty for three or more AWS accounts in an Organization. The sample code provides the following attributes:
Delegated Administrator
This sample Terraform code can be deployed locally or integrated into a continuous integration and continuous delivery (CI/CD) pipeline.
For prerequisites and instructions for using this AWS Prescriptive Guidance pattern, see Use Terraform to automatically enable Amazon GuardDuty for an organization.
import-org
- to store the resource config of the imported AWS Organizationcreate-delegatedadmin-acct-role
- to create role for the Management account to assume in the security accountcreate-logging-acct-role
- to create role for the Management account to assume in the logging accountenable-gd
- to enable GuardDuty for different regionscreate-gd-bucket-and-key
- to create an S3 bucket in the logging account and KMS key in the security account to store GuardDuty findings; also has a lifecycle policy to transition items to Glacier after 'n' daysCloudFormation template files with stubs have been provided under cfn-templates/. Run the scripts/replace_config_stubs.sh script to replace the stubs with values provided in the configuration.json file. This will generate the following CloudFormation YAML files:
management-account-role.yaml
– This file contains the role definition and the associated permissions for the IAM role in the management account, which has the minimum permissions required to complete this patternrole-to-assume-for-role-creation.yaml
– This file contains the role definition and the associated permissions for the IAM role in the security and logging accounts, which is used by Terraform to create the GuardDutyTerraformOrgRole in these accountsThe scripts provided under scripts/
folder are used to automate the entire process.
scripts/full-setup.sh
scripts/replace_config_stubs.sh
scripts/cleanup-gd.sh
scripts/generate-backend.sh
scripts/generate-tfvars.sh
scripts/create-roles.sh
scripts/setup-gd.sh
The following outputs are generated from the module tfm-gd-enabler
:
guardduty_detector
: The GuardDuty detector ID in each region1) AWS GuardDuty is available in several regions. This is obtained as a list via an API call in the Python script
2) The Delegated Administrator account has its own list of allowed regions i.e., regions which are not disabled and are either opted in by the account owner or opt-in is not required. This is obtained as a separate list via another API call
3) The intersection of the lists from (1) and (2) provide us with an "allowed list" of regions where GuardDuty can be enabled without errors
4) There is a configuration field target_regions
in configuration.json.sample which is a comma-separated list of preferred regions where GuardDuty needs to be enabled in the current organization. Each region specified in the target_regions
configuration is compared with the "allowed list" from (3) before proceeding to enable GuardDuty in those preferred regions
Add the new region(s) to the target_regions
configuration field in configuration.json.sample file and follow the steps in the pattern to deploy.
import-org/
run terraform plan
, check that the new accounts are included in the state and there are no other changes; then run terraform apply
2) Under enable-gd/
run terraform plan
, check that the new accounts are included in the state and there are no other changes; then run terraform apply
If there are no errors during the above deployment process, the following can be observed via the console:
For subsequent runs of the steps to deploy after the first run, a known error will be reported about importing an already imported resource for the import-org
module. Though this is shown as an Error
, this is expected behavior and does not affect the rest of the setup, so it can be ignored.
There are many ways to contribute to this project. Get started with CONTRIBUTING.
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.