terraform-aws-securityhub-summary-email

Generates and sends a periodic email summarising of Security Hub. Based on https://github.com/aws-samples/aws-security-hub-summary-email

This solution uses Security Hub custom insights, AWS Lambda, and the Security Hub API. A custom insight is a collection of findings that are aggregated by a grouping attribute, such as severity or status. Insights help you identify common security issues that may require remediation action. Security Hub includes several managed insights, or you can create your own custom insights.

Overview

A recurring Security Hub Summary email will provide recipients with a proactive communication summarizing the security posture and improvement within their AWS Accounts. The email message contains the following sections:

• AWS Foundational Security Best Practices findings by status
• AWS Foundational Security Best Practices findings by severity
• CIS Benchmark findings by compliance status
• Failed CIS Benchmark findings by severity
• Health findings by severity
• Amazon GuardDuty findings by severity
• Macie findings by severity
• AWS IAM Access Analyzer findings by severity
• Trusted Advisor findings by severity
• Inspector findings by severity
• Systems Manager Patch Manager findings by severity
• Systems Manager OpsCenter and Explorer findings by severity
• Firewall Manager findings by severity
• Audit Manager findings by severity
• Detective findings by severity
• Chatbot findings by severity
• Unresolved findings by severity
• New findings in the last 7 days by security product
• Top 10 resource types with the most findings

Here’s how the solution works

1. Seven Security Hub custom insights are created when the solution is first deployed.
2. A CloudWatch time-based event invokes a Lambda function for processing.
3. The Lambda function gets results of the custom insights from Security Hub, formats the results for email and sends a message to SNS.
4. SNS sends the email notification to the address provided during deployment.
5. The email includes the summary and links to the Security Hub UI to follow the remediation workflow.

Usage

For a complete example, see examples/managed_sns.

For automated tests of the complete example using bats and Terratest (which tests and deploys the example on AWS), see test.

Here's how to invoke this module in your projects:

module "securityhub-email" {
  source  = "app.terraform.io/aesop/security-hub-summary-email/aws"
  version = "x.x.x"
}

Examples

Here is an example of using this module:

• examples/managed_sns

Requirements

Name	Version
terraform	>= 0.13.0
aws	>= 2

Providers

Name	Version
aws	>= 2

Resources

Name	Type
aws_cloudwatch_event_rule.trigger	resource
aws_cloudwatch_event_target.lambda	resource
aws_iam_role.iam_for_lambda	resource
aws_lambda_permission.trigger	resource
aws_lambda_function.sechub_summariser	resource
aws_securityhub_insight.all_by_severity	resource
aws_securityhub_insight.aws_best_prac_by_severity	resource
aws_securityhub_insight.aws_best_prac_by_status	resource
aws_securityhub_insight.guardduty_by_severity	resource
aws_securityhub_insight.iam_by_severity	resource
aws_securityhub_insight.new_findings	resource
aws_securityhub_insight.top_resource_types	resource
aws_sns_topic.this	resource
aws_sns_topic_subscription.this	resource
archive_file.code	data source
aws_partition.this	data source

Inputs

Name	Description	Type	Default	Required
additional_email_header_text	Additional text to append at the start of email message.	string	""	no
additional_email_footer_text	Additional text to append at the end of email message.	string	""	no
email	Email Address for Subscriber to Security Hub summary. Only used if SNS arn is not specified.	string	null	no
insights	list of insights and in what order to include in the summary. See Below for possible values.	list	[]	no
name	ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.	string	sechub-aummariser	no
schedule	Expression for scheduling the Security Hub summary email. Default: Every Monday 8:00 AM UTC. Example: Every Friday 9:00 AM UTC: cron(0 9 ? _ 6 _).	string	cron(0 8 ? * 2 *)	no
sns_topic_arn	ARN of the SNS Topic to send summaries to. If empty, a topic is created for you.	string	null	no
kms_key_id	KMS Key ID to use for encrypting the topic.	string	alias/aws/sns	no
tags	Additional tags (e.g. {'BusinessUnit': 'XYZ'}).	map(string)	{}	no

Possible insight values

• aws_best_practices_by_status
• aws_best_practices_by_severity
• cis_by_status
• cis_by_severity
• health_by_severity (AWS Health events)
• guardduty_by_severity (GuardDuty)
• macie_by_severity (Macie)
• iam_by_severity (IAM Access Analyzer)
• ta_by_severity (Trusted Advisor)
• inspector_by_severity (Inspector)
• ssmpm_by_severity (Systems Manager Patch Manager)
• ssmops_by_severity (Systems Manager OpsCenter and Explorer)
• fwman_by_severity (Firewall Manager)
• auditman_by_severity (Audit Manager)
• detective_by_severity (Detective)
• chatbot_by_severity (Chatbot)
• all_findings_by_severity
• new_findings
• top_resource_types_with_findings_by_count

See documentation for a list of Security Hub integrations

Outputs

Name	Description
sns_topic_arn	The SNS topic's ARN that was created

Test Solution

You can send a test email once the deployment is complete and you have confirmed the SNS subscription email. Navigate to the Lambda console and locate the function Lambda function named SendSecurityHubSummaryEmail. Perform a manual invocation with any event payload to receive an email shortly.

License

This library is licensed under the MIT License. See the LICENSE file.

Requirements

Name	Version
terraform	~> 1.0
archive	~> 2.0
aws	>= 3.0, < 5.0.0

Providers

Name	Version
archive	~> 2.0
aws	>= 3.0, < 5.0.0

Modules

No modules.

Resources

Name	Type
aws_cloudwatch_event_rule.trigger	resource
aws_cloudwatch_event_target.lambda	resource
aws_iam_role.iam_for_lambda	resource
aws_lambda_function.sechub_summariser	resource
aws_lambda_permission.trigger	resource
aws_securityhub_insight.all_by_severity	resource
aws_securityhub_insight.auditman_by_severity	resource
aws_securityhub_insight.aws_best_prac_by_severity	resource
aws_securityhub_insight.aws_best_prac_by_status	resource
aws_securityhub_insight.chatbot_by_severity	resource
aws_securityhub_insight.cis_by_severity	resource
aws_securityhub_insight.cis_by_status	resource
aws_securityhub_insight.detective_by_severity	resource
aws_securityhub_insight.fwman_by_severity	resource
aws_securityhub_insight.guardduty_by_severity	resource
aws_securityhub_insight.health_by_severity	resource
aws_securityhub_insight.iam_by_severity	resource
aws_securityhub_insight.inspector_by_severity	resource
aws_securityhub_insight.macie_by_severity	resource
aws_securityhub_insight.new_findings	resource
aws_securityhub_insight.ssmops_by_severity	resource
aws_securityhub_insight.ssmpm_by_severity	resource
aws_securityhub_insight.ta_by_severity	resource
aws_securityhub_insight.top_resource_types	resource
aws_sns_topic.this	resource
aws_sns_topic_subscription.this	resource
archive_file.code	data source
aws_partition.this	data source

Inputs

Name	Description	Type	Default	Required
additional_email_footer_text	Additional text to append at the end of email message	string	""	no
additional_email_header_text	Additional text to prepend at the start of email message	string	""	no
email	Email Address for Subscriber to Security Hub summary. Only used if SNS arn is not specified	string	null	no
insights	list of insights and in what order to include in the summary.	list(any)	[]	no
kms_key_id	KMS Key ID to use for encrypting the topic	string	"alias/aws/sns"	no
name	ID element	string	"sechub-summariser"	no
schedule	Expression for scheduling the Security Hub summary email. Default: Every Monday 8:00 AM UTC. Example: Every Friday 9:00 AM UTC: cron(0 9 ? * 6 *)	string	"cron(0 8 ? * 2 *)"	no
sns_topic_arn	ARN of the SNS Topic to send summaries to. If empty, a topic is created for you.	string	null	no
tags	Additional tags	map(string)	{}	no

Outputs

Name	Description
sns_topic_arn	The SNS topic that was created