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 Event Rules or through an integration on a PagerDuty Service.

Integrating with Event Rules

Integrating with global or service-level event rules may be beneficial if you want to build different rules based on the payload coming from AWS. If you would like to learn more, please visit our article on Rulesets.

Configure a Global Event Rules Integration

  1. From the Automation menu, select Event Rules and click your Default Global Ruleset.
  2. On the Event Rules screen, copy your Integration Key.
  1. Once you have your Integration Key, the Integration URL will be:

https://events.pagerduty.com/x-ere/[YOUR_INTEGRATION_KEY_HERE]

You can now proceed to the In the AWS Console section below.

Configure a Service Event Rules Integration

To use service-level event rules:

  1. Navigate to Services Service Directory select your preferred service Integrations tab Add a new integration.
  2. Enter an Integration Name, select Use our API directly and select your preferred Events API version (Events API v2 or Events API v1). Click Add Integration.
  3. Find the new integration in your integrations list and click its name. On the next page, copy the Integration Key and paste it into the following URL:

https://events.pagerduty.com/integration/[YOUR_INTEGRATION_KEY_HERE]/enqueue

You can now proceed to the In the AWS Console section below.

Integrating With a PagerDuty Service

  1. From the Services menu, select Service Directory.
  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”
  ]
}```


[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/9dfe5c1-aws-security-hub-custom-event-pattern.png",
        "aws-security-hub-custom-event-pattern.png",
        1188,
        691,
        "#f8f8f8"
      ]
    }
  ]
}
[/block]

9. 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](https://support.pagerduty.com/docs/aws-security-hub-integration-guide-pagerduty#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.

 

Updated about a month ago


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.