AWS Partner Network (APN) Blog
How to Integrate AWS Security Hub Custom Actions with PagerDuty
By Scott Ward, Partner Solutions Architect at AWS
AWS Security Hub gives customers visibility into their security alerts and compliance status across their Amazon Web Services (AWS) accounts.
The Custom Actions feature enables users to create actions for response and remediation to selected findings. Custom actions include things like sending findings to chat, email, ticketing, and/or remediation systems.
Security Hub uses Amazon CloudWatch Events to support custom actions. Selected findings are sent to CloudWatch and a custom action ID connects the selected findings to a corresponding CloudWatch Event rule and target.
In this post, I will walk you through how to create a custom action in AWS Security Hub and link that custom action with PagerDuty, an AWS Partner Network (APN) Advanced Technology Partner.
This integration allows you to send Security Hub findings to PagerDuty and use the PagerDuty platform to manage, organize, and respond to Security Hub events related to your organization.
This is an overview of the architecture that supports the Security Hub custom action integration with PagerDuty.
To create this integration, the following steps need to be performed:
- Create a service and integration definition in PagerDuty.
- Create a custom action in Security Hub.
- Create a CloudWatch Events rule to process the Security Hub custom action.
- Create an Amazon Simple Notification Service (SNS) topic to send the custom action information to PagerDuty.
Define a PagerDuty Service and Integration
In order to receive and process Security Hub events in PagerDuty, a service and integration needs to be defined in PagerDuty. This definition provides a location for Security Hub findings to be sent to, and enables PagerDuty to process the finding and create the appropriate notifications.
Here’s how to create a new service and integration in PagerDuty:
- If you do not have a PagerDuty account, sign up for an account here.
- Once logged into PagerDuty, choose the Configuration drop down and then the Services option.
- Next, click on the New Service button that takes you to the Add a Service screen. Enter a name for the new service being defined. For Integration Type, choose Amazon CloudWatch. Fill out any other details that are appropriate for the service and then click Add Service to create the service.
- The details of the Integration URL for this integration need to be captured. In the Integrations tab for the new PagerDuty service, click on the name for the Security Hub integration to open up the details of the integration.
- In the detail screen for the custom integration, copy and save the Integration URL. You will need this later for setup in AWS.
Now that a PagerDuty service and integration has been defined, the remaining AWS configuration needed for sending Security Hub findings to PagerDuty can be completed.
Create a Custom Security Hub Action
To be able to send information on findings that are in Security Hub to PagerDuty a custom action in Security Hub needs to be defined. The following steps outline how to set up a custom action:
- In the Security Hub navigation pane, choose Settings and then choose the Custom Actions tab.
- Click the Create Custom Action button to begin the setup process.
- Fill in the Name, Description, and Custom Action ID for the custom action definition and then choose OK to create the action.
- A completed custom action definition now shows in the Custom Actions tab.
- Copy the Custom Action ARN for the PagerDuty Custom action, as it’s needed for a future configuration step.
Create an SNS Topic for PagerDuty
In order to send the details of a Security Hub action to PagerDuty, an SNS topic needs to be defined. This SNS topic will forward Security Hub findings to the PagerDuty Integration URL, which results in the finding being processed by the integration that was defined in PagerDuty.
The following steps outline the necessary SNS setup for forwarding Security Hub actions to PagerDuty:
- In the SNS dashboard choose Create Topic.
- In the Create New Topic window, define a Topic Name and Display Name then click Create Topic to save the topic definition.
- In the Topic Details screen, create a subscription to send the details to your PagerDuty account. In the Subscriptions section, click Create Subscription.
- In the Create Subscription window, choose HTTPS for the protocol and enter the Integration URL for the PagerDuty integration that was defined earlier. Clicking the Create Subscription button saves the subscription definition.
- Once the subscription has been saved, the SNS service will send a request to your PagerDuty endpoint requesting confirmation for the subscription. PagerDuty will automatically acknowledge the subscription. A successful acknowledgement of the subscription will result in the Subscription ID column in SNS topic changing from PendingConfirmation to an ARN that represents the subscription.
Create a CloudWatch Event for Security Hub Actions
Taking action on a finding in Security Hub results in the information for the finding and the ARN of the custom action being sent to CloudWatch Events. To successfully process this action, a CloudWatch Event rule needs to be defined so the action information can be sent to PagerDuty.
- In the CloudWatch Events dashboard, choose Rules.
- In the Rules dashboard, click on the Create Rule button.
- In the Event Source section, choose the Event Pattern option and then from the dropdown choose Custom Event Pattern.
- In the Custom Event Pattern text box, enter the information that applies to the specific Security Hub action that was created for the PagerDuty integration. In the Event Pattern, enter enough information to ensure that only events from the Security Hub service, and for the custom PagerDuty action, trigger this CloudWatch Event. Use the JSON below to define the Event Pattern for your rule. Replace the words CUSTOM_ARN_FOR_PAGERDUTY_ACTION with the ARN for your Actual Custom action in Security Hub.
- In the Targets section, choose SNS Topic and then the name of the topic that was defined in an earlier step.
- Click on the Configure Details button to get to the Configure Rule Details form. Give the rule a name and description, and then click the Create Rule button to complete the setup.
Using the Integration
With all of this done, you are now able to start using a Security Hub custom action to send events to PagerDuty.
- In the Security Hub console, go to the Findings option, and the Findings screen will show a list of all your open Security Hub findings.
- NOTE: If you do not have any findings in Security Hub, and you want to test out the custom action functionality, you can generate sample findings via Amazon GuardDuty. The GuardDuty documentation on generating sample findings walks you through how to create these findings. Once the findings are created, you’ll need to wait a few minutes for them to show in Security Hub.
- Choose one of the findings and then select the Send to PagerDuty custom action from the Actions drop down. A success message appears indicating the event was sent to CloudWatch events.
- In PagerDuty, navigate to the incidents dashboard to see the finding that was sent from Security Hub.
- Now that the Security Hub finding is in PagerDuty, you can use all the standard PagerDuty functionality around triage, routing, and escalation to further process and resolve this finding.
AWS Security Hub is a great way to get visibility into your security profile for all your AWS accounts. PagerDuty gives you the ability to display, triage, and investigate events within your organization.
When used together, Security Hub and PagerDuty gives you the ability to have full visibility and response to the security events happening in your AWS accounts. I invite you to explore PagerDuty and Security Hub further and see what you can do to build out your own integrations.
AWS Security Hub is available globally at no cost during the Preview period. For a complete list of Regions where AWS Security Hub is offered, see AWS Regions.
You can enable Security Hub on a single account with one click in the AWS Security Hub console or a single API call. Learn more about Security Hub at our AWS Online Tech Talks webinar: Introduction to AWS Security Hub.
PagerDuty – APN Partner Spotlight
PagerDuty is an APN Advanced Technology Partner. They are a digital operations management platform for businesses that empowers DevOps, IT ops, support, security, and business leaders to turn any signal into insight and real-time action.