GuardDuty in a multi-account organization with Terraform

GitHub Code

https://github.com/zghafari/guardduty

What is GuardDuty?

GuardDuty in a nutshell is a threat detection service that continuously monitors your AWS accounts and workloads for malicious or unauthorized behavior. It’s sort of like have custom config rules setup, except amazon is taking care of it for you and its fully managed.

What does it monitor?

• Backdoor
• Behavior
• CryptoCurrency
• PenTest
• Persistence
• Policy
• Recon
• ResourceConsumption
• Stealth
• Trojan
• UnauthorizedAccess

Technical Details of GuardDuty

GuardDuty works by creating what is called a “Detector”. A detector is an object that represents the AWS Service. For GuardDuty to become operational it is necessary to have this detector created. To create the detector programmatically the CreateDetector  API operation will need to be run.

GuardDuty in a multi-account organization. 

So we know that GuardDuty requires a detector to be created on an account for it to be operational and only one detector is allowed per account.

In a multi-account environment there will be one master and multiple member accounts. Lets’ take a look a look step by step with what operations are required to set this up in such an environment.

1. Create detectors on all member accounts. This will render the GuardDuty service to become operational.
2. Run the CreateMembers API operation on the master account. This will create the members on what will become the master account for GuardDuty. Two parameters will have to be supplied, detector-id and account-details. The detector-id will be the id of the master detector (detector id on account you are running CreateMembers). account-details will contain the account id and root email address of each account as a list.
3. Run the InviteMembers API operation on the same master account to send an invitation out to the member accounts. This also has two parameters. The master detector-id and all the member account-ids you would like to invite to join the master.
4. Finally you can now accept the invitation by running the AcceptInvitation API operation on each member account. You must specify the detector-id of the current member account, the master account-id and the invitation-id.

Terraform Modules

So we now know what API operations will be called and what operations are run on the master and what is run on the member. Lets take a look at some of the terraform operations available to us.

Master GuardDuty Module Structure

• Create Detector
• Create GuardDuty Member
• Note:  You must manually accept member account invitations before GuardDuty will begin sending cross-account events. Terraform and Cloudformation does not offer an API operation to accomplish this.

Master GuardDuty Variables

variable "member_account_ids" {
  type = "list"
}

variable "member_account_emails" {
  type = "list"
}

Master GuardDuty Module Code

resource "aws_guardduty_detector" "master" {
  enable = true
}

resource "aws_guardduty_member" "prod_member" {
  count              = "${length(var.member_account_ids)}"
  detector_id        = "${aws_guardduty_detector.master.id}"
  account_id         = "${element(var.member_account_ids, count.index)}"
  email              = "${element(var.member_account_emails, count.index)}"
  invite             = true
  invitation_message = "GuardDuty Invite - Please accept this invitation if you are expecting it."
}

Member GuardDuty Module Structure

• Create Detector

Member GuardDuty Module Code

resource "aws_guardduty_detector" "member" {
  enable = true
}