Amazon GuardDuty Integration Guide | PagerDuty

Configure the Amazon GuardDuty integration

Amazon GuardDuty + PagerDuty Benefits

  • The Amazon GuardDuty integration allows you to automate response workflows for security issues that could affect your AWS infrastructure.
  • PagerDuty ensures that the right people are notified about things like unauthorized behavior, and you can use PagerDuty’s alert grouping to reduce noise by grouping similar alerts into a single issue.

Requirements

To Configure the Integration:

  • In PagerDuty: Managers, Admins, Global Admins and Account Owners can configure the integration.
  • In AWS: Users who set up and manage AWS Config must have full-access permissions. Please read Amazon’s documentation Granting Permissions for AWS Config Administration for more information about managing permissions in AWS.

How it Works

  • This is a one-way integration. GuardDuty rules send finding events to PagerDuty, and those events generate incidents.

Version

This guide details configuration of the Amazon GuardDuty V1 integration.

Integration Walkthrough

In PagerDuty

There are three ways to integrate Amazon GuardDuty with PagerDuty:

Integrate With Event Orchestration

Expand

Configure a Global Orchestration Integration

  1. Configure a Global Orchestration in your PagerDuty account.
  2. Navigate to Automation 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 section below.

Configure a Service Orchestration Integration

  1. Configure a Service Orchestration in your PagerDuty account.
  2. 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 In the AWS Management Console section below.

Integrate With Rulesets

Expand

❗️

Rulesets End-of-Life

Rulesets and Event Rules will end-of-life in 2024. We recommend using Event Orchestration instead, which offers new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting.

Configure a Global Ruleset Integration

  1. From the Automation menu, select Event Rules and click your Default Global Ruleset.
  2. On the Event Rules screen, click the Incoming Event Source dropdown and copy your Integration Key.
  3. 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 section below.

Configure a Service Event Rules Integration

To use service-level event rules:

  1. Configure service event rules on your preferred service.
  2. 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/integration/[YOUR_INTEGRATION_KEY_HERE]/enqueue

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

Integrate With a PagerDuty Service

Expand

Add to a New Service

  1. To add the integration to a new service, navigate to Services Service Directory and click New Service.
  2. Follow the prompts and configure the service to your preferences. On the Integrations screen, select Amazon GuardDuty 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.
  5. You can now proceed to the In the AWS Management Console section below.

Add to an Existing Service

  1. To add an integration 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 Amazon GuardDuty 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.
  4. You can now proceed to the In the AWS Management Console section below.

In the AWS Management Console

  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).
    • Perform the following based on your preference:
      • If you are integrating with Global Rulesets or Global Orchestrations: It is recommended that the Enable raw message delivery checkbox is checked.
      • If you are not integrating with Global Rulesets or Global Orchestrations: 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. Once you have enabled GuardDuty, you can begin building EventBridge Rules to send alerts to PagerDuty. Search and select EventBridge from the Services search bar.
  8. Select Rules from the left menu, then click Create Rule. One or more rules can be created to send specific events to PagerDuty when a GuardDuty finding is opened.
  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 GuardDuty.
    • Event type: Select GuardDuty Finding.
    • 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 9-14.
  14. The integration is now complete. To ensure the configuration was successful, navigate back to the Amazon GuardDuty console, select Settings in the left menu, scroll down and click Generate Sample Findings, then select Findings in the left menu. You will see the sample findings that have been generated, and in PagerDuty you will see the correlating sample alert.