Skip to main content
Security Modules 0.75.0Last updated in version 0.74.0

AWS GuardDuty Multi Region Module

View Source Release Notes

This module wraps the guardduty core module to configure AWS GuardDuty in all enabled regions for the AWS Account.

Features​

  • Uses the guardduty module to enable AWS GuardDuty across all regions (recommended best practice) on your AWS account

  • Continuously monitor your AWS account for malicious activity and unauthorized behavior

  • Analyze events across multiple AWS data sources, such as AWS CloudTrail, Amazon VPC Flow Logs, and DNS logs and use machine learning, anomaly detection, and integrated threat intelligence to identify and prioritize potential threats

  • Allows publishing threat findings to S3 and SNS topics through CloudWatch Events

Learn​

Note

This repo is a part of the Gruntwork Infrastructure as Code Library, a collection of reusable, battle-tested, production ready infrastructure code. If you’ve never used the Infrastructure as Code Library before, make sure to read How to use the Gruntwork Infrastructure as Code Library!

Core concepts​

Repo organization​

  • modules: the main implementation code for this repo, broken down into multiple standalone, orthogonal submodules.

  • codegen: Code generation utilities that help generate modules in this repo.

  • examples: This folder contains working examples of how to use the submodules.

  • test: Automated tests for the modules and examples.

Deploy​

Note

This module depends on Python being available on your system. Python 2.7, 3.5+ are supported.

Sample Usage​

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S GUARDDUTY-MULTI-REGION MODULE
# ------------------------------------------------------------------------------------------------------

module "guardduty_multi_region" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/guardduty-multi-region?ref=v0.75.0"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The AWS Account ID the template should be operated on. This avoids
  # misconfiguration errors caused by environment variables.
  aws_account_id = <string>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Whether to accept an invite from the master account if the detector is not
  # created automatically
  accept_invite = false

  # The AWS account ID of the GuardDuty delegated admin/master account
  admin_account_id = null

  # Indicates the auto-enablement configuration of GuardDuty for the member
  # accounts in the organization. Valid values are ALL, NEW, NONE.
  auto_enable_organization_members = null

  # Name of the Cloudwatch event rules.
  cloudwatch_event_rule_name = "guardduty-finding-events"

  # Create the GuardDuty Member Detector resource
  create_detector = true

  # Set to 'true' to create GuardDuty Organization Admin Account. Only usable in
  # Organizations primary account.
  create_organization_admin_account = false

  # The S3 bucket ARN under which the findings get exported.
  default_findings_s3_bucket_arn = null

  # The ARN of the KMS key used to encrypt GuardDuty findings. GuardDuty
  # enforces this to be encrypted. Only used if publish_findings_to_s3 is true.
  default_findings_s3_kms_key_arn = null

  # The ID of the default customer master key (CMK) to use to encrypt the SNS
  # topic for any region that isn't defined in var.sns_kms_master_key_ids. This
  # could be an AWS managed CMK (e.g., aws/sns) or customer managed CMK (e.g.,
  # alias/example-key). For example, you might set this variable to 'aws/sns' to
  # use the AWS managed CMK for encryption in all regions. Only used if
  # publish_findings_to_sns is true.
  default_sns_kms_master_key_id = null

  # The type of GuardDuty event to match. Setting this to anything other than
  # the default will generate noise. This usually only needs to be adjusted for
  # automated testing purposes.
  detail_type = "GuardDuty Finding"

  # Map of detector features to enable, where the key is the name of the feature
  # the value is the feature configuration. When AWS Organizations delegated
  # admin account is used, use var.organization_configuration_features instead.
  # See
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_detector_feature
  detector_features = {}

  # If set to false, suspends GuardDuty (does not destroy data).
  enable = true

  # Specifies the frequency of notifications sent for subsequent finding
  # occurrences. If the detector is a GuardDuty member account, the value is
  # determined by the GuardDuty administrator account and cannot be modified,
  # otherwise defaults to SIX_HOURS. For standalone and GuardDuty administrator
  # accounts, it must be configured in Terraform to enable drift detection.
  # Valid values for standalone and administrator accounts: FIFTEEN_MINUTES,
  # ONE_HOUR, SIX_HOURS.
  finding_publishing_frequency = null

  # A map from AWS region to the ARN of an S3 bucket under which the findings
  # get exported. If there's no S3 bucket set for a region, the value in
  # var.default_findings_s3_bucket_arn will be used instead. Only used if
  # publish_findings_to_s3 is true.
  findings_s3_bucket_arns = {}

  # A map from AWS region to the ARN of a customer master key (CMK) to use to
  # encrypt GuardDuty findings in that region. If there's no ARN set for a
  # region, the value in var.default_findings_s3_kms_key_arn will be used
  # instead. Only used if publish_findings_to_s3 is true.
  findings_s3_kms_key_arns = {}

  # The bucket prefix without trailing '/' under which the findings get
  # exported. The prefix is optional and will be
  # AWSLogs/[Account-ID]/GuardDuty/[Region]/ if not provided.
  findings_s3_prefix = null

  # Specifies a name for the created SNS topics where findings are published.
  # publish_findings_to_sns must be set to true.
  findings_sns_topic_name = "guardduty-findings"

  # The invitation message to send to the member accounts.
  invitation_message = "Please accept GuardDuty invitation."

  # Map of member accounts to add to GuardDuty where key is the AWS account
  # number. Use to add Organization accounts to delegated admin account or
  # invite member accounts by invite.
  member_accounts = {}

  # Map of organization configuration features to enable, where key is the
  # feature name and value is feature configuration. See
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_organization_configuration_feature
  organization_configuration_features = {}

  # Publish GuardDuty findings to an S3 bucket. The bucket arn and prefix are
  # specified by findings_s3_bucket_arn and findings_s3_bucket_prefix.
  publish_findings_to_s3 = false

  # Send GuardDuty findings to SNS topics specified by findings_sns_topic_name.
  publish_findings_to_sns = false

  # A map from AWS region to the ID of a customer master key (CMK) to use to
  # encrypt the SNS topic in that region. This could be an AWS managed CMK
  # (e.g., aws/sns) or customer managed CMK (e.g., alias/example-key). If
  # there's no CMK set for a region, the value in
  # var.default_sns_kms_master_key_id will be used instead. Only used if
  # publish_findings_to_sns is true.
  sns_kms_master_key_ids = {}

}


Reference​

Required​

aws_account_idstringrequired

The AWS Account ID the template should be operated on. This avoids misconfiguration errors caused by environment variables.

Optional​

accept_invitebooloptional

Whether to accept an invite from the master account if the detector is not created automatically

false
admin_account_idstringoptional

The AWS account ID of the GuardDuty delegated admin/master account

null

Indicates the auto-enablement configuration of GuardDuty for the member accounts in the organization. Valid values are ALL, NEW, NONE.

null

Name of the Cloudwatch event rules.

"guardduty-finding-events"
create_detectorbooloptional

Create the GuardDuty Member Detector resource

true

Set to 'true' to create GuardDuty Organization Admin Account. Only usable in Organizations primary account.

false

The S3 bucket ARN under which the findings get exported.

null

The ARN of the KMS key used to encrypt GuardDuty findings. GuardDuty enforces this to be encrypted. Only used if publish_findings_to_s3 is true.

null

The ID of the default customer master key (CMK) to use to encrypt the SNS topic for any region that isn't defined in sns_kms_master_key_ids. This could be an AWS managed CMK (e.g., aws/sns) or customer managed CMK (e.g., alias/example-key). For example, you might set this variable to 'aws/sns' to use the AWS managed CMK for encryption in all regions. Only used if publish_findings_to_sns is true.

null
detail_typestringoptional

The type of GuardDuty event to match. Setting this to anything other than the default will generate noise. This usually only needs to be adjusted for automated testing purposes.

"GuardDuty Finding"
detector_featuresmap(object(…))optional

Map of detector features to enable, where the key is the name of the feature the value is the feature configuration. When AWS Organizations delegated admin account is used, use organization_configuration_features instead. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_detector_feature

map(object({
    status = string
    additional_configuration = list(object({
      name   = string
      status = string
    }))
  }))
{}
enablebooloptional

If set to false, suspends GuardDuty (does not destroy data).

true

Specifies the frequency of notifications sent for subsequent finding occurrences. If the detector is a GuardDuty member account, the value is determined by the GuardDuty administrator account and cannot be modified, otherwise defaults to SIX_HOURS. For standalone and GuardDuty administrator accounts, it must be configured in Terraform to enable drift detection. Valid values for standalone and administrator accounts: FIFTEEN_MINUTES, ONE_HOUR, SIX_HOURS.

null
findings_s3_bucket_arnsmap(string)optional

A map from AWS region to the ARN of an S3 bucket under which the findings get exported. If there's no S3 bucket set for a region, the value in default_findings_s3_bucket_arn will be used instead. Only used if publish_findings_to_s3 is true.

{}
findings_s3_kms_key_arnsmap(string)optional

A map from AWS region to the ARN of a customer master key (CMK) to use to encrypt GuardDuty findings in that region. If there's no ARN set for a region, the value in default_findings_s3_kms_key_arn will be used instead. Only used if publish_findings_to_s3 is true.

{}
findings_s3_prefixstringoptional

The bucket prefix without trailing '/' under which the findings get exported. The prefix is optional and will be AWSLogs/[Account-ID]/GuardDuty/[Region]/ if not provided.

null

Specifies a name for the created SNS topics where findings are published. publish_findings_to_sns must be set to true.

"guardduty-findings"
invitation_messagestringoptional

The invitation message to send to the member accounts.

"Please accept GuardDuty invitation."
member_accountsmap(object(…))optional

Map of member accounts to add to GuardDuty where key is the AWS account number. Use to add Organization accounts to delegated admin account or invite member accounts by invite.

map(object({
    email = string
  }))
{}
organization_configuration_featuresmap(object(…))optional

Map of organization configuration features to enable, where key is the feature name and value is feature configuration. See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_organization_configuration_feature

map(object({
    auto_enable = string
    additional_configuration = list(object({
      name        = string
      auto_enable = string
    }))
  }))
{}

Publish GuardDuty findings to an S3 bucket. The bucket arn and prefix are specified by findings_s3_bucket_arn and findings_s3_bucket_prefix.

false

Send GuardDuty findings to SNS topics specified by findings_sns_topic_name.

false
sns_kms_master_key_idsmap(string)optional

A map from AWS region to the ID of a customer master key (CMK) to use to encrypt the SNS topic in that region. This could be an AWS managed CMK (e.g., aws/sns) or customer managed CMK (e.g., alias/example-key). If there's no CMK set for a region, the value in default_sns_kms_master_key_id will be used instead. Only used if publish_findings_to_sns is true.

{}