Announcing the Amazon GuardDuty Runbook Generator

Dustin Whited

Director of Security Engineering

LinkedIn

We are proud to announce another open-source project from Aquia: GuardDuty Runbook Generator. This tool is a kickstart to generate a base set of runbooks when GuardDuty is enabled in an organization. Using documentation provided by Amazon on each GuardDuty finding, this tool will create a runbook that can be customized for an organization's incident response needs.

Background

Amazon GuardDuty is a security monitoring service with built in detections for common issues in AWS environments. It is fully managed by AWS, leverages data sources in an AWS account, and has built in threat intelligence feeds.

Runbooks, or playbooks, are processes with detailed steps that can be used when triaging an alert. They provide documentation for a responder to efficiently gather data and contain an incident if needed.

How it Works

The GuardDuty Runbook Generator is an application written in python that gathers all active finding types from the GuardDuty documentation page. It will then query each finding type and find its corresponding detail and remediation recommendations from the AWS documentation page. This information is converted into Markdown and written to a file per finding.

How it Helps

Having quick access to documentation is critical when triaging alerts. Runbooks generated by this tool contain a base set of information and remediation recommendations in order to create a foundation of runbooks when enabling GuardDuty. The runbooks should be enriched, customized, and tailored to the incident response needs of the organization.

SIEM tools that support "detections as code" like Panther and Matano can also support runbooks as code. Storing runbooks as markdown in the git repository next to the detections helps create context, easy links, and provide transparency to responders.

Generating Runbooks

This tool can be installed from PyPI

pip install guardduty-runbooks

It can also be installed locally from Github. After cloning the directory, run in the folder:

pip install .

The tool can then be run with optional flags:

guardduty-runbooks [--outdir outdir] [--overwrite]

If outdir is not specified, it will write all runbooks to the local directory.

guardduty-runbooks --outdir ./my-runbook-directory

This tool can be run multiple times to create runbooks for new finding types. Run the tool again over the directory where runbooks are stored and it will write new runbooks only, unless --overwrite is specified. Overwrite is a destructive command and will erase any customization made to the runbook.

guardduty-runbooks --outdir ./my-runbook-directory --overwrite

Runbook filenames are written using the "finding type" specified by GuardDuty. Because finding types include non alphanumeric characters like :,/, !, and ., those characters are replaced with dashes - and all other characters are made lowercase.

For example:

CryptoCurrency:EC2/BitcoinTool.B!DNS becomes cryptocurrency-ec2-bitcointool-b-dns

The content for this finding from the AWS Documentation page is generated as below:

CryptoCurrency:EC2/BitcoinTool.B!DNS
------------------------------------


### An EC2 instance is querying a domain name that is associated with cryptocurrency-related activity.


**Default severity: High**


 * **Data source:** DNS logs

This finding informs you that the listed EC2 instance in your AWS environment is querying a domain name that is associated with Bitcoin or other cryptocurrency-related activity. Bitcoin is a worldwide cryptocurrency and digital payment system that can be exchanged for other currencies, products, and services. Bitcoin is a reward for bitcoin-mining and is highly sought after by threat actors.


**Remediation recommendations:**


If you use this EC2 instance to mine or manage cryptocurrency, or this instance is otherwise involved in blockchain activity, this finding could be expected activity for your environment. If this is the case in your AWS environment, we recommend that you set up a suppression rule for this finding. The suppression rule should consist of two filter criteria. The first criteria should use the **Finding type** attribute with a value of `CryptoCurrency:EC2/BitcoinTool.B!DNS`. The second filter criteria should be the **Instance ID** of the instance involved in blockchain activity. To learn more about creating suppression rules see [Suppression rules](https://docs.aws.amazon.com/guardduty/latest/ug/findings_suppression-rule.html).


If this activity is unexpected, your instance is likely compromised, see [Remediating a compromised Amazon EC2 instance](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_remediate.html#compromised-ec2).

Note that the runbook content generated from docs.aws.amazon.com is licensed under CC-BY-SA-4.0 per AWS Site Terms.

Related Links

For more information on Detections as Code, see our recent webinar on Detection Engineering or our blog on our recent open source contribution to Matano.