AWS Security Hub Integration Guide | PagerDuty

Integration Guide for AWS Security Hub

PagerDuty + AWS Security Hub Integration Benefits

  • This integration allows you to send AWS Security Hub Findings to PagerDuty and use the PagerDuty platform to manage, organize, and respond to events relevant to your organization.

How it Works

  • As AWS Security Hub discovers Findings, it will automatically send these Findings to CloudWatch Events. As a result of this automated process by AWS Security Hub, you can define the Event Pattern in which to trigger notifications to be sent to PagerDuty through SNS Topics. Example JSON for Event Pattern is available below in step 5 of our CloudFormation template.
  • You can also add and/or restrict these Findings to be sent only when they’re manually triggered by creating a Custom Action in AWS Security Hub, and adding that Custom Action ID ARN in the Event Pattern Resource.

Requirements

In AWS Security Hub:

In PagerDuty:

  • This integration requires a Manager, Admin, Global Admin or Account Owner base role to configure. If you're not sure what role you have, or if you need your permissions adjusted, visit our sections on Checking Your User Role or Changing User Roles.

Integration Walkthrough

In PagerDuty

There are two ways that AWS Security Hub can be integrated with PagerDuty: via Global Event Rules or through an integration on a PagerDuty Service. Global Event Rules may be beneficial if you want to build different routing rules based on the payload coming from AWS. Integrating with a PagerDuty service may be beneficial if you don't need to route alerts from AWS to different responders based on the event payload.

Note: If you are integrating AWS Security Hub with an existing PagerDuty service, please skip to the Integrating with a PagerDuty Service section of this guide.

Integrating With Global Event Rules

  1. From the Configuration menu, select Event Rules.
  2. On the Event Rules screen, click on the arrow next to Incoming Event Source to display the Integration key information. Copy your Integration Key. This is the same integration key you will use for any other tool you want to integrate with using event rules. When you have finished setting up the integration, you will return to this interface to specify how to route events from AWS Security Hub to services in PagerDuty.
  1. Once you have your Integration Key, the Integration URL will be in the following format:
    https://events.pagerduty.com/x-ere/[YOUR_INTEGRATION_KEY_HERE]. Keep this URL in a safe place for later use. You can now proceed to the In the AWS Console section below.

Integrating With a PagerDuty Service

  1. From the Configuration menu, select Services.

  2. It is recommended that you create a service specifically for Amazon CloudWatch notifications.
    If you are creating a new service for your integration, please read our documentation in section Configuring Services and Integrations and follow the steps outlined in the Create a New Service section, selecting AWS Security Hub as the Integration Type in step 4. Continue with the In Datadog section (below) once you have finished these steps.

If you are adding your integration to an existing service, click the name of the service you want to add the integration to. Then select the Integrations tab and click the New Integration button.

  1. Enter an Integration Name in the format monitoring-tool-service-name (e.g. AWS-Security-Hub-Shopping-Cart) and select AWS Security Hub from the Integration Type menu.

  2. Click Add Integration to save your new integration. You will be redirected to the Integrations tab for your service.

  3. Copy the Integration URL for your new integration. Keep this URL in a safe place for later use. You can now proceed to the In the AWS Console section below.

In the AWS Console

Next you will need to configure AWS Security Hub to send CloudWatch Events to PagerDuty. You can set up CloudWatch events by using our provided CloudFormation template, or you can configure them manually.

CloudFormation Template

This CloudFormation template will automatically create a new SNS Topic named SecurityHubSNSTopic. The CloudFormation template will prompt you to provide an Event Pattern for selected events to be routed to the SNS Topic target. The template will also prompt for the PagerDuty Integration URL generated above in step 3 of the Integrating Global Event Rules section, or step 5 of the Integrating With a PagerDuty Service section.

  1. Download the PagerDutyCloudFormation.template file.
  2. In AWS CloudFormation, click Create stack.
  3. Select Template is ready and Upload a template file.
  4. Upload the PagerDutyCloudFormation.template file.
  5. Give this Stack a Name, and specify the following parameters:

EventPatternParameter JSON Example:

{ "source": [ "aws.securityhub" ] }

SNSSubEndpoint Integration URL Examples:

Integrating With Global Event Rules:
https://events.pagerduty.com/x-ere/[YOUR_INTEGRATION_KEY_HERE]

Integrating With a PagerDuty Service:
https://events.pagerduty.com/integration/7c6178Yourcb469Keyb039e15c3f4499/enqueue

Manually Configure CloudWatch Events

  1. In the SNS dashboard, click Create topic. This will be used to route alerts to PagerDuty from AWS Security Hub.
  1. Enter a Name, optionally enter a Display name and then click Create topic. You may want to name your topic after your PagerDuty service’s name.
  2. Now that your topic has been created, click Create Subscription.
  1. In the Protocol field, select HTTPS. In the Endpoint field, paste the PagerDuty Integration URL that was generated above in step 3 of the Integrating Global Event Rules section, or step 5 of the Integrating With a PagerDuty Service section. Click Create Subscription to continue.
  1. Your Subscription ID should automatically read as Confirmed. Click the icon on the right hand side to refresh and ensure that the Subscription ID is not PendingConfirmation.
  1. Next, navigate to CloudWatch and select Rules to create a rule that will define when to trigger an AWS Security Hub finding and where to send the finding.
  2. Click the Create Rule button. In the Service Name field, select Security Hub and in the Event Type field, select your preference of what Events should be sent to PagerDuty.
  1. Click Add Target on the right to specify where to send the event.
  2. Select SNS Topic from the dropdown and then select the Topic name created in Step 2 (above). Click Configure details to continue.
  3. On the next screen, enter a Name, Description and ensure that the Enable checkbox is checked. Click Create Rule to complete the integration.

Custom Actions for Manual Notifications

If you would like to manually send AWS Security Hub Findings instead of automatically sending them based on an Event Pattern, you can follow this section to configure the Custom Action button in AWS Security Hub.

AWS Security Hub Custom Action

  1. Navigate to Security Hub
  2. Select Settings on the left navigation panel, select the Custom actions tab and click the Create custom action button.
  1. Enter a Name, Description and Custom Action ID.
  1. Copy the Custom action ARN to be used when defining the CloudWatch Event Rule.
  1. Navigate to CloudWatch.
  2. Select Rules in the left navigation panel and click the Create Rule button.
  3. Select Build custom event pattern.
  4. The pattern should look similar to the below example, but ensure that you replace the value “CUSTOM_ACTION_ARN_HERE” in the resources section value with the Custom Action ARN generated in step 6 above.

Example:

{
  "source": [
    "aws.securityhub"
  ],
  "detail-type": [
    "Security Hub Findings - Custom Action"
  ],
  "resources": [
    “CUSTOM_ACTION_ARN_HERE”
  ]
}
  1. Specify where the AWS Security Hub Finding should be sent under the Target section. If you haven’t already configured this, this is available in Steps 1-3 in the section Manually Configure CloudWatch Events above.

FAQ

What AWS Security Hub Findings will be sent to PagerDuty with this integration?

This will depend on your Event Pattern that is defined in the CloudFormation Template section, step 5 (above). By default, this configuration will send all AWS Security Hub Findings to PagerDuty. You can restrict this by adding specific ‘detail-type’ and/or adding specific resources.

Does PagerDuty sync statuses and updates with AWS Security Hub?

No, not at this time. AWS Security Hub will send the notifications to PagerDuty, and updates will not be posted/synced back with the particular AWS Security Hub Finding.

AWS Security Hub Integration Guide | PagerDuty


Integration Guide for AWS Security Hub

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.