How do I use EventBridge with an Amazon SNS topic to set up customized email notifications for Security Hub findings?

5 minute read

I want to use Amazon EventBridge with an Amazon Simple Notification Service (Amazon SNS) topic to set up customized email notifications for AWS Security Hub.

Short description

The following resolution shows you how to configure Amazon EventBridge with Amazon SNS to receive Security Hub notifications. Based on the EventBridge rule, Amazon SNS sends a notification to the email address subscribed to the topic when your event occurs. An AWS Lambda function creates a customized alert message with improved formatting.

Resolution

Create an SNS topic and subscription

Complete the following steps:

Open the Amazon SNS console.
In the navigation pane, choose Topics.
Choose Create topic.
In the Details section, for Type, choose Standard.
For Name, enter the name of your topic.
Choose Create topic.
From the created topic, choose Create subscription.
For Topic ARN, select the Amazon Resource Name (ARN) of the topic that you created if not automatically populated.
For Protocol, choose Email.
For Endpoint, enter the email address where you want to receive SNS notifications.
Choose Create subscription.
Important: You must confirm the subscription in the confirmation email sent to the subscriber for the subscription to switch from PendingConfirmation status to Confirmed.
(Optional) You can also create an authenticated subscription that prevents the unsubscribe action on your topic.

Create a Lambda function

Complete the following steps:

Open the Lambda console.
In the navigation pane, choose Functions.
Choose Create function.
Choose Author from scratch.
For Function name, enter a name for your function.
Choose Runtime, and then choose Python 3.14.
For Architecture, select x86_64.
Expand Change default execution role.
For Execution role, select Create a new role from AWS policy templates.
For Role name, enter a name for the role.
For Policy template, choose Amazon SNS publish policy.
Choose Create function.

Enter the following code in the Code source section:

import json
import boto3

sns = boto3.client('sns')

def lambda_handler(event, context):
    
    #Extract details from JSON event
    detailType= event["detail-type"]
    region = event["region"]
    accountId = event["account"] 
    
    #Security Hub Insight Results
    if (detailType == "Security Hub Insight Results"):
        
        action = event["detail"]["actionDescription"]
        
        message = "Alert: %s in %s for account: %s\n Action description: %s" % (detailType, region,accountId,action)
    
    elif  ("Security Hub Findings" in detailType):
        
        finding = event["detail"]["findings"][0] 
        findingTime = finding["FirstObservedAt"]
        findingType = finding["Types"][0]
        findingDescription = finding["Description"]
        remediation = finding["Remediation"]["Recommendation"]["Text"]
        
        #Security Hub Findings - Custom finding
        if(detailType == "Security Hub Findings - Custom"):
            complianceStatus = finding["Compliance"]["Status"]
            severity = finding["Severity"]["Label"]
            remediationUrl = finding["Remediation"]["Recommendation"]["Url"]
            
            message = "Alert: %s in %s for account: %s\n\nFinding regarding: [%s] %s\n Severity: %s\nDescription: %s\nFirst observed at: %s\n%s: %s" % (detailType, region, accountId, complianceStatus, findingType, 
            severity, findingDescription, findingTime, remediation, remediationUrl)
        
        #Security Hub Findings - Imported finding
        else:
            message = "Alert: %s in %s for account: %s\n\nFinding regarding: %s\nFirst observed at: %s\nRemediation recommendation: %s" % (detailType, region, accountId, findingDescription,findingTime, remediation)
    
    #AWS API Call via CloudTrail finding
    elif (detailType == "AWS API Call via CloudTrail"):
        
        time = event["detail"]["eventTime"]
        eventName = event["detail"]["eventName"]
        requestParameters = event["detail"]["requestParameters"]
        
        message = "Alert: %s in %s for account: %s at time: %s\n\n Event: %s \n Request parameters: %s" % (detailType, region, accountId, time, eventName, requestParameters)
        
        
    #If the event doesn't match any of the above, return the event    
    else:
        message = str(event)
    
    response = sns.publish(
            TopicArn = "arn:aws:sns:eu-west-1:111122233333:your-arn",
            Message = message
            )
    
    return {
      'statusCode': 200,
      'body': json.dumps('Success!')
}

Note: Replace arn:aws:sns:eu-west-1:111122233333:your-arn with your topics ARN.

Choose Deploy.

Create and configure the EventBridge rule

Complete the following steps:

Open the EventBridge console.
In the navigation pane, choose Rules, and then choose Create rule.
Enter a Name for your rule, and then choose Next.
For Creation method, select Use pattern form.
For Event source, select AWS services.
For AWS service, select Security Hub.
For Event type, select All Events, and then choose Next.
Note: You can also configure alerts for specific events rather than for all events.
For Target types, choose AWS service.
For Select a target, choose Lambda function.
For Function, choose the function that you previously created, and then choose Next.
On the Configure tags page, choose Next.
Choose Create rule.

Receive a customized notification

When the configured events occur, you receive a customized notification email from no-reply@sns.amazonaws.com.

The default Security Hub events are reformatted into a customized format that's more readable.

Example Security Hub Insight result message

Default:

{"version": "0", "id": "ac844908-d14e-05b1-4b7b-836d85110e26", "detail-type": "Security Hub Insight Results", "source": "aws.securityhub", "account": "123456789012", "time": "2019-04-11T21:31:57Z", "region": "us-east-1", "resources": ["arn:aws:securityhub:us-east-1:123456789012:action/custom/slackMessaging"], "detail": {"actionName": "SendToSlack", "actionDescription": "Send Findings to Slack", "insightName": "5. AWS users with the most suspicious activity", "insightArn": "arn:aws:securityhub:::insight/securityhub/default/9", "resultType": "ResourceAwsIamAccessKeyUserName", "insightResults": [{"Admin": 7}, {"DenySlr_UI_User": 1}]}}

Customized:

Alert: Security Hub Insight Results in us-east-1 for account: 123456789012

Action description: Send Findings to Slack

Note: You can edit the message for each security finding type for your use case.