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

AWS GuardDuty

View Source Release Notes

This Terraform Module configures AWS GuardDuty, a service for detecting threats and continuously monitoring your AWS accounts and workloads against malicious activity and unauthorized behavior.

Features​

  • 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

  • Uses the [guardduty module](../guardduty-single-region) to enable AWS GuardDuty across all regions (recommended best practice) on your AWS account

  • Allows publishing threat findings to 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​

Non-production deployment (quick start for learning)​

If you just want to try this module out, check out the following resources:

Production deployment​

If you want to deploy this module in production, check out the following resources:

Sample Usage​

main.tf

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

module "guardduty" {

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

  # ----------------------------------------------------------------------------------------------------
  # 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 rule
  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 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 = {}

  # Enable monitoring and feedback reporting. Setting to false is equivalent to
  # suspending GuardDuty. Defaults to true
  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

  # The S3 bucket ARN under which the findings get exported. Required if
  # publish_findings_to_s3 is set to true.
  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.
  findings_s3_kms_key_arn = null

  # 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 topic 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 a SNS topic specified by findings_sns_topic_name.
  publish_findings_to_sns = false

  # The ID of a customer master key (CMK) to use to encrypt the SNS topic. This
  # could be an AWS managed CMK (e.g., aws/sns) or customer managed CMK (e.g.,
  # alias/example-key). Only used if publish_findings_to_sns is true.
  sns_kms_master_key_id = null

}


Reference​

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 rule

"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
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

Enable monitoring and feedback reporting. Setting to false is equivalent to suspending GuardDuty. Defaults to true

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

The S3 bucket ARN under which the findings get exported. Required if publish_findings_to_s3 is set to true.

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
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 topic 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 a SNS topic specified by findings_sns_topic_name.

false
sns_kms_master_key_idstringoptional

The ID of a customer master key (CMK) to use to encrypt the SNS topic. This could be an AWS managed CMK (e.g., aws/sns) or customer managed CMK (e.g., alias/example-key). Only used if publish_findings_to_sns is true.

null