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.
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
- Seven Security Hub custom insights are created when the solution is first deployed.
- A CloudWatch time-based event invokes a Lambda function for processing.
- The Lambda function gets results of the custom insights from Security Hub, formats the results for email and sends a message to SNS.
- SNS sends the email notification to the address provided during deployment.
- The email includes the summary and links to the Security Hub UI to follow the remediation workflow.
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"
}Here is an example of using this module:
| Name | Version |
|---|---|
| terraform | >= 0.13.0 |
| aws | >= 2 |
| Name | Version |
|---|---|
| aws | >= 2 |
| 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 |
| 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 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 |
aws_best_practices_by_statusaws_best_practices_by_severitycis_by_statuscis_by_severityhealth_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_severitynew_findingstop_resource_types_with_findings_by_count
See documentation for a list of Security Hub integrations
| Name | Description |
|---|---|
| sns_topic_arn | The SNS topic's ARN that was created |
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.
This library is licensed under the MIT License. See the LICENSE file.
| Name | Version |
|---|---|
| terraform | ~> 1.0 |
| archive | ~> 2.0 |
| aws | >= 3.0, < 5.0.0 |
| Name | Version |
|---|---|
| archive | ~> 2.0 |
| aws | >= 3.0, < 5.0.0 |
No modules.
| 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 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 |
| Name | Description |
|---|---|
| sns_topic_arn | The SNS topic that was created |