PagerDuty Integration with DefectDojo

PagerDuty Integration with DefectDojo

PagerDuty is an incident management and on-call platform from PagerDuty, Inc. Teams organize their systems as Services, each with an escalation policy that decides who is notified when an incident opens. An incident moves from triggered to acknowledged to resolved, and carries an urgency of high or low, plus a priority on accounts that have Priorities enabled. DefectDojo Pro creates and updates incidents through PagerDuty's REST API.

PagerDuty Integration with DefectDojo

Our on-call engineers live in PagerDuty, and the handful of security findings that cannot wait until Monday need to reach them the same way an outage does. The PagerDuty Downstream Connector in DefectDojo Pro opens a PagerDuty incident for a Finding or Finding Group on the Service we pick, maps severity to urgency, and moves the incident to acknowledged or resolved as the Finding is risk-accepted or closed. DefectDojo still owns triage and deduplication, so what pages someone is a confirmed, current problem rather than raw scanner output.

Why PagerDuty Matters

Escalation is a solved problem in most engineering organizations, and PagerDuty is often where it was solved.

• Escalation policies and schedules already decide who responds and what happens when they do not, which a security team should reuse rather than rebuild.
• Urgency controls how aggressively PagerDuty notifies people, so a security incident can follow the same high or low rules as an operational one.
• Incidents tie into the reporting and postmortem habits teams already have.
• Without a connector, urgent findings rely on someone watching a dashboard or sending a message, which is unreliable at 2 a.m.

Advantages of This Integration

What DefectDojo adds in front of PagerDuty:

• Pages only for what qualifies. Assignment push filters can limit automatic incident creation to a minimum severity and to active Findings. Everything else stays in DefectDojo unless someone pushes it by hand.
• Severity to urgency by default. Critical and High map to high urgency. Medium, Low, and Info map to low.
• Priority if you use it. Accounts with PagerDuty Priorities enabled can map severities to Priority names, such as P1 through P5, and leave urgency to the Service's own rules.
• Status mirrors the Finding. Active maps to triggered, Closed and False Positive map to resolved, and Risk Accepted maps to acknowledged.
• Groups instead of floods. Pushing a Finding Group opens one incident for a set of related findings.
• Traceable from both sides. Each linked Finding shows the integration type, the incident ID, a direct link, and a changelog of DefectDojo's updates.

How This Integration Works

Downstream Connectors are a DefectDojo Pro feature, generally available on Cloud and On-Premise instances. Community Edition's issue tracking integration supports Jira only, so PagerDuty requires DefectDojo Pro.

Every Downstream Connector has an Integration Instance (connection and credentials), one or more Issue Tracker Mappings (destination plus severity and status mappings), and Issue Tracker Assignments (which Assets or Engagements use each mapping, and how). Configure them under Connect > Downstream in the Pro UI.

1. Create a REST API key in PagerDuty. An account administrator creates one under Integrations > API Access Keys > Create New API Key. Leave Read-only unchecked, because DefectDojo needs to create and update incidents.

2. Create the Integration Instance.

• Label: a name for this integration.
• Location: https://api.pagerduty.com, or https://api.eu.pagerduty.com for the EU service region.
• API Token: the REST API key.
• From Email: the email address of a valid user on your PagerDuty account. PagerDuty requires it when creating or updating incidents and shows it as the requester.

3. Create an Issue Tracker Mapping. Set the Service ID to the PagerDuty Service that should receive incidents. It appears at the end of the Service's URL in the PagerDuty service directory.

4. Choose urgency or priority. By default the Severity Field Name is Urgency, which accepts only high or low. To use Priorities instead, set the Severity Field Name to Priority and enter your account's Priority names as the mapping values.

5. Confirm status mappings and assign. The Status Field Name is Status, with the defaults in the table below. Then create Issue Tracker Assignments for the Assets or Engagements that should page, choose a push behavior, and set push filters.

Data Granularity: What Gets Sent

Because PagerDuty does not allow an incident's title or description to change after creation, pushing an updated Finding syncs status, urgency, and priority only. Resolved is final, so a resolved incident cannot be reopened.

Use Cases

A security on-call Service: A team creates a dedicated PagerDuty Service with its own escalation policy and maps it as the destination for internet-facing Assets. An assignment that automatically links new Findings, filtered to Critical and active only, opens a high-urgency incident whenever a new Critical appears.

Using existing priorities: An organization that already runs P1 to P5 Priorities for incidents maps DefectDojo severities onto those names, so a security incident sorts into the same queue order as an outage.

Showing accepted risk: When a Finding is risk-accepted after review, its incident moves to acknowledged, which tells responders the issue is owned even though it is not fixed.

One incident for a widespread issue: When a single vulnerability shows up across many hosts, pushing the Finding Group opens one incident rather than paging once per host.

Operational Tips

• Use a From Email that belongs to a real, long-lived PagerDuty user, such as a service account. PagerDuty requires a valid user's address whenever an incident is created or updated.
• Get the finding content right before pushing. PagerDuty will not accept later title or description edits, so updates only change status, urgency, and priority.
• Keep automatic creation tight. Pair automatic linking with a high Minimum Severity and Active findings only, and use manual Push to Integrator for anything borderline.
• When mapping to Priority, remember urgency is then left to the Service's own urgency rules. Check those rules so a P1 security incident still notifies at high urgency.
• Resolved is final in PagerDuty. If you reactivate a Finding later, its old incident will not reopen.
• Check the Total Errors column on the All Issue Tracker Mappings & Assignments page after key or Service changes, and use Diagnostics to see failures across all integrations.