Demisto Integration Guide

This integration requires use of our v1 REST API which is currently in a decommissioning period, please contact support to gain access to a v1 REST API key to configure this integration.

For more information about the v1 REST API deprecation take a look at our FAQ here: https://v2.developer.pagerduty.com/v2/docs/v1-rest-api-decommissioning-faq

We are working with partners to upgrade integrations to use our v2 REST API.

Demisto provides a security operations/Incident Response platform that manages both technical and non-technical aspects of security incidents. The platform combines:

  • Automation that provides data enrichment, auto-triage and automated response through integration with threat intelligence, SIEMs, Firewalls, EDRs, sandboxes, forensic tools, messaging systems, and more
  • A Virtual War Room where stakeholders collaborate around incidents and investigations
  • Auto-documentation of all incidents and investigations
  • Playbooks ensuring that processes are followed and important steps are never missed even during crises
  • Strong search capabilities that provide auto-detection of duplicate and related investigations
  • Evidence gathering and tamper proof storage

By integrating with PagerDuty on-call team members can be called to investigations both manually and automatically, investigators can check who is currently on call and who would be on call at other times, investigators can also view the status of current calls and create events/incidents.

 

This integration requires an API Access key which can only be created by an admin or the account owner.

In PagerDuty

  1. From the Configuration menu, select Services.
  2. On your Services page:If you are creating a new service for your integration, click +Add New Service. If you are adding your integration to an existing service, click the name of the service you want to add the integration to. Then click the Integrations tab and click the +New Integration button.RS-Add-New-ServiceRS-Add-Integration-Existing-Service
  3. Select your app from the Integration Type menu and enter an Integration Name.If you are creating a new service for your integration, in General Settings, enter a Name for your new service. Then, in Incident Settings, specify the Escalation Policy, Notification Urgency, and Incident Behavior for your new service.
  4. Click the Add Service or Add Integration button to save your new integration. You will be redirected to the Integrations page for your service.
    RS-Integration-Settings
  5. Copy and save the Integration Key for your new integration, we will need it in a moment. RS_API_pd_3
  6. From the Configuration menu, select API Access.
    apiaccess-0
  7. On your API Access page, click the +Create New API Key button.apiaccess-1
  8. In the dialog that pops up, you’ll be prompted to enter a Description for your key, and choose an API version. You will also have the option to create the key as Read-only; leaving this box unchecked will create a full access key._int3__API_Keys_-_PagerDuty A note about versioning: API v2.0 is designed to make it easier for new integrations to communicate with PagerDuty. Most existing PagerDuty integrations will require an API v1.0 key. If you have questions on which API version to use, please contact support@pagerduty.com
  9. Once you have filled in your options, click Create Key.
  10. Once you click Create Key, you will see a dialog displaying your key and confirming the options you filled in on the previous step. Make sure to copy this key into any application that needs it now, as you will not have access to the key after this step. If you lose a key that you created previously and need access to it again, you should remove the key and create a new one. Click Close once you have successfully copied your key.api__2_
  11. Once created, you will see your key appear in the list of keys on the API Access page, with versioning noted.api__3_

In Demisto

  1. Go to Settings and click Add Server next to PagerDuty.pd1
  2. Next, you will need to fill in the authentication details and click Done when you are finish:
    • Name: A name that will be used in Demisto to identify PagerDuty.
    • API Key: PagerDuty API access key that you created earlier.
    • Subdomain: your subdomain in pagerduty (https://<subdomain>.pagerduty.com)
    • Service key: the PagerDuty integration key you created earlier.
    • Engine: in case that the Demisto server cannot connect directly to the Internet, a Demisto engine that is connected to the Internet should be used.pd4__1_
  3. Once  you are done you can go to the playground, or to an investigation war room and the following commands will be available:
    • !PagerDutyAssignOnCallUser – assigns the first on-call user to an investigation (all incidents in the investigation will be owned by the on call user). This is executed using a script. It is possible to change the on call user by editing the script (in the automation screen) or providing a script argument named “query” for example:
      • !PagerDutyAssignOnCallUser query=mike will assign the on call user mike to the investigation
    • !PagerDutyGetAllSchedules – receive all schedules from PagerDuty
    • !PagerDutyGetUsersOnCall – returns the names and details of on call users at a certain time or by specific schedule
    • !PagerDutyGetUsersOnCallNow – returns the names and details of current on call personnel
    • !PagerDutyIncidents – shows incidents in PagerDuty (can show all, by status, by time, etc. Demisto’s CLI autocomplete will show all available options)
    • !pagerDutySubmitEvent – creates a new event/incident in PagerDutypd2
  4. Note that as with any ! command available in the War Room, you can create scripts that run the commands as well as associate the scripts with playbooks.

You have now completed the integration! If you have any questions about this guide please contact support@pagerduty.com.

FAQ

Can I add multiple pagerduty services to Demisto Enterprise?

Yes, you can add multiple pagerduty services to Demisto Enterprise. You can accomplish this by adding new server to the pagerduty integration inside Demisto Enterprise interface and each server can be a new service.

Can I customize how the user on call is decided from the schedules in pagerduty?

You can customize the scripts in Demisto and choose how the user on call is decided. The default scripts are written in javascript. You can choose to edit the scripts or create absolutely new scripts using the commands defined above in python.