AWS GuardDuty via Terraform and Python

AWS GuardDuty

At re:Invent 2017, on November 28th, AWS released GuardDuty. This is a new threat detection service that operates within your account structure (including organizational child accounts). The service leverages machine learning to identify threats, provide recommendations for remediation, and can fire off alerts via AWS services like Simple Notification Service (SNS). There is nothing to install as it uses internal AWS infrastructure. It monitors CloudTrail logs, DNS logs, and API usage looking for unusual account usage. You can review the pricing model here.

Over the last couple of years I have implemented Amazon Web Services (AWS) in a security role. Soon after the release I was given the task to get it configured.

GuardDuty detects issues and classifies them as low, medium, and high. You can then send these alerts into Sumo Logic, VictorOps, or even Slack.

Terraform is still getting features added to support GuardDuty and at this time cannot, by itself, do a full implementation but that won’t stop me.

To get this done I had to use the Terraform aws_cloudformation_stack resource because Terraform does not have a functional equivalent to boto3‘s invite_members().

The following instructions are for setting up GuardDuty in a master/member relationship. If your company is using AWS Organizations then you’ll want one account as the master and the other accounts as members.

Requirements for operation
  • Terraform version 0.11.1 with AWS provisioner 1.11 or higher
  • Python3 (Python2 will work as well)
  • S3 bucket to store state
Python requirements:
  • boto3
  • ply
  • pyhcl
A single file controls which regions to enable GuardDuty in for both Terraform and Python operations

Edit the file and update the variable region_list with the regions you would like to enable and use GuardDuty.

3 steps:
  1. enable GuardDuty detector(s) in every region, as defined, for the master account context
    • Terraform
  2. create member accounts and invite the member accounts in every region, as defined, for the master account context
    • Terraform creating CloudFormation stacks
  3. create the member detector(s) in every region, as defined, and accept the invite from the master account in the member account context
    • Python

All of this can be found on GitHub in my aws-guardduty-example repository.

All code is Apache License 2.0.

Any problems with the Python code are my fault and not Amazon’s as I hacked it up.

Books I used: