# AWS Security Hub Integration Guide | PagerDuty

Configure the AWS Security Hub integration

## PagerDuty + AWS Security Hub Integration Benefits

- Send AWS Security Hub finding events to PagerDuty.
- Use the PagerDuty platform to manage, organize, and respond to events that are relevant to your organization.
- You can define the Event Pattern that will send AWS Security Hub finding events to PagerDuty through SNS Topics. Example JSON for the Event Pattern is available below in our [CloudFormation template](#cloudformation-template).
- If you would like to manually send AWS Security Hub finding events instead of automatically sending them based on an Event Pattern, you can optionally [create a custom action](#custom-actions-for-manual-notifications) in AWS Security Hub. 

## Requirements

**In PagerDuty**:

- This integration requires a Manager, Admin, Global Admin or Account Owner base role to configure. 

**In AWS Security Hub**:

- If using the [CloudFormation template](#cloudformation-template) below, you must have access to create a CloudFormation template.

## How it Works

- Amazon EventBridge sends AWS Security Hub finding events to PagerDuty.
- These events then generate PagerDuty incidents and notify responders.

## Version

This guide details configuration of the **AWS Security Hub V1** integration.

## Integration Walkthrough

### In PagerDuty

There are two ways to integrate AWS Security Hub with PagerDuty: 

- [Integrate With Event Orchestration](#integrate-with-event-orchestration): Integrating with [Event Orchestration](/ai-automation/aiops/event-orchestration) may be beneficial if you want to build nested rules based on the payload coming from AWS. 
- [Integrate With a PagerDuty Service](#integrate-with-a-pagerduty-service): Integrating with a [PagerDuty service](/incident-management/services/services-and-integrations) directly can be beneficial if you don’t need to route alerts from AWS to different responders based on the event payload. You can still use service-level [Event Orchestration](/ai-automation/aiops/event-orchestration#incident-data) to perform actions such as alert suppression.

**Integrate With Event Orchestration**

##### Configure a Global Orchestration Integration

1. [Configure a Global Orchestration](/ai-automation/aiops/event-orchestration#global-orchestrations) in your PagerDuty account. 
2. Navigate to **AIOps**  →  **Event Orchestration**  →  click the **name** of your Global Orchestration.
3. Click the **Global Orchestration Key**  dropdown and then copy the **Integration Key**. 
4. 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 Management Console](#in-the-aws-management-console) section below. 

##### Configure a Service Orchestration Integration

1. [Configure a Service Orchestration](/ai-automation/aiops/event-orchestration#service-orchestrations) in your PagerDuty account. 
2. Create a [Generic Events API integration](/incident-management/services/services-and-integrations#create-a-generic-events-api-integration) on the same service. 
3. Once complete, copy the **Integration Key** and paste it into the following URL:

`https://events.pagerduty.com/x-ere/YOUR_INTEGRATION_KEY_HERE`

You can now proceed to the section [In the AWS Management Console](#in-the-aws-management-console) below.

**Integrate With a PagerDuty Service**

##### Add to a New Service

1. To [add the integration to a new service](/incident-management/services/services-and-integrations#create-a-new-service), navigate to **Services**  →  **Service Directory** and click **New Service**. 
2. Follow the prompts and [configure the service](/incident-management/services/services-and-integrations#create-a-new-service) to your preferences. On the Integrations screen, select **AWS Security Hub** from the search bar dropdown.
3. Once you are done entering your service settings, click **Create Service**.
4. You will now be in the service’s Integrations tab. Find your integration in the list and click the  to view and copy your **Integration URL**. Keep it in a safe place for later use.  

You can now proceed to the [In the AWS Management Console](#in-the-aws-management-console) section below. 

##### Add to an Existing Service

1. To [add an integration to an existing service](/incident-management/services/services-and-integrations#add-integrations-to-an-existing-service), go to **Services**  →  **Service Directory** and select the **service** where you would like to configure the integration. Select the **Integrations** tab and click **Add another integration**. 
2. Select **AWS Security Hub** from the search bar dropdown.
3. Click **Add**. Find your integration in the list and click the  to the right to view and copy your **Integration URL**. Keep it in a safe place for later use.

You can now proceed to the [In the AWS Management Console](#in-the-aws-management-console) section below.

### In the AWS Management Console

Next you will need to configure Amazon EventBridge to send AWS Security Hub events to PagerDuty. There are two ways to do this:

- [Use our provided CloudFormation template](#cloudformation-template)
- [Configure Amazon EventBridge manually](#configure-amazon-eventbridge-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 in steps above.

1. Download the [PagerDutyCloudFormation.template](https://github.com/PagerDuty/security-hub-cloudformation/blob/master/PagerDutyCloudFormation.template) file.
2. In the AWS Management Console, search and select **AWS CloudFormation** in the Services search bar. Select **Stacks** in the left menu and then click **Create stack**.
3. Select **Template is ready** and **Upload a template file**.
4. Upload the **PagerDutyCloudFormation.template** file and then click **Next**.
5. Enter a **Stack name** and then specify the following parameters:
   - **EventPatternParameter**: Enter a JSON Object that represents the Event Pattern.
     - **JSON Example**: `{ "source": [ "aws.securityhub" ] }`
   - **PagerDutyEventsEndpoint**: Enter the PagerDuty **Integration URL** generated in steps above.
   - Click **Next**.
6. On the next screen, configure stack options to your preference and then click **Next**.
7. On the final page, review your stack’s details and then click **Create stack**. The integration is now complete.

#### Configure Amazon EventBridge Manually

1. In the Services search bar, search and select **Simple Notification Service**. In the SNS dashboard left menu, select **Topics** and click **Create Topic** on the right. This topic will be used to route alerts to PagerDuty from AWS.
2. Select the **Standard** Topic **Type**.
3. Next, perform the following:
   - **Name**: Enter a **name** for your topic. You may want to name your topic after your PagerDuty service’s name.
   - **Display name** (_optional_): Enter an optional **display name**.
   - Click **Create topic**. 
4. Now that your topic has been created, select **Subscriptions** in the left menu and click **Create Subscription**.
5. Perform the following:
   - **Topic ARN**: Select the **Topic ARN** of the topic you just created. 
   - **Protocol**: Select **HTTPS**. 
   - **Endpoint**: Paste your **Integration URL** (generated in steps above).
   - Ensure that the **Enable raw message delivery** checkbox is **unchecked**.
   - Click **Create Subscription**.
6. Your subscription should be automatically confirmed. Refresh the page to make sure the **Status** is `Confirmed` and not `PendingConfirmation`.
7. Next, search and select  **EventBridge** from the Services search bar.
8. Select **Rules** from the left menu, then click **Create Rule**. 
9. On the next screen, perform the following: 
   - **Name**: Enter a **name** that can be easily identified.
   - **Description** _(optional)_: Enter a **description** of the rule, pattern and target(s).
   - **Event Bus**: Select **default**.
   - **Enable the rule on the selected event bus**: Toggle to the **on** position.
   - **Rule with an event pattern**: This will automatically be preselected.
   - Click **Next** to continue.
10. On the next page, perform the following: 
    - **Event source**: Select **AWS events or EventBridge partner events**.
    - **Sample event** (_optional_): If you would like to view sample events, you may do so in this section.
    - **Event Source**: Select **AWS services**.
    - **AWS Service**: Select **Security Hub**.
    - **Event type**: You may select **All Events**, **AWS API Call via CloudTrail**, **Security Hub Findings - Custom Action**, **Security Hub Findings - Imported** or **Security Hub Insight Results** based on your preferences.
    - Click **Next** to continue. 
11. On the next page, perform the following:
    - **Target types**: Select **AWS service**.
    - **Select a target**: Search and select **SNS topic**.
    - **Topic**: Search and select the **topic** created in previous steps.
    - Configure other additional settings to your preference.
    - Click **Next** to continue.
12. On the next page, _optionally_ add tags to your preference. Click **Next** to continue.
13. On the final page, review your settings and click **Create Rule**. If you would like to create more rules, repeat steps 7-13. Once you have finished configuring your rules, the integration is complete. 

### 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.

1. Follow Amazon’s documentation to [create a custom action](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-cwe-custom-actions.html), and ensure that you copy the **Custom action ARN**. 
2. Search and select **Amazon EventBridge** in the Services search bar.
3. Select **Rules** in the left menu and click the **Create Rule** button.
4. On the next screen, perform the following: 
   - **Name**: Enter a **name** that can be easily identified.
   - **Description** _(optional)_: Enter a **description** of the rule, pattern and target(s).
   - **Event Bus**: Select **default**.
   - **Enable the rule on the selected event bus**: Toggle to the **on** position.
   - **Rule with an event pattern**: This will automatically be preselected.
   - Click **Next** to continue.
5. On the next page, perform the following: 
   - **Event source**: Select **Other**.
   - **Sample event** (_optional_): If you would like to view sample events, you may do so in this section.
6. In the **Event Pattern** field, 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 above.

**Example**:

```json
{
  "source": [
    "aws.securityhub"
  ],
  "detail-type": [
    "Security Hub Findings - Custom Action"
  ],
  "resources": [
    “CUSTOM_ACTION_ARN_HERE”
  ]
}
```

- Click **Next** to continue.

7. On the next page, perform the following:
   - **Target types**: Select **AWS service**.
   - **Select a target**: Search and select **SNS topic**.
   - **Topic**: Search and select the **topic** created in previous steps.
   - Configure other additional settings to your preference.
   - Click **Next** to continue.
8. On the next page, _optionally_ add tags to your preference. Click **Next** to continue.
9. On the final page, review your settings and click **Create Rule**.

## FAQ

**What AWS Security Hub findings will be sent to PagerDuty when using the CloudFormation template?**

This will depend on your Event Pattern that is defined in the [CloudFormation template](#cloudformation-template) section, 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 notifications to PagerDuty, and updates will not be posted/synced back with the particular AWS Security Hub Finding.