PagerDuty
Overview
Section titled “Overview”Adversarial sends notifications to PagerDuty as alerts through an Events API v2 integration. Each alert carries the risk or incident ID, its title, what changed, who changed it, and a link back to Adversarial. Item descriptions and comment text are never sent.
- Destination: the PagerDuty service (or Event Orchestration) the integration key belongs to
- In PagerDuty, open the service that should receive Adversarial alerts and go to its Integrations tab.
- Select Add an integration, choose Events API V2, and select Add.
- Copy the 32-character Integration Key.
- (Recommended) In the service’s Settings, under Assign and Notify, set How should responders be notified? to Dynamic notifications based on alert severity. This lets lower-level notifications open low-urgency incidents instead of paging on-call. With a fixed urgency, every alert uses that urgency.
- In Adversarial, go to Settings > Integrations and select Add.
- Select NTF in the PagerDuty row.
- Enter an Instance Name, such as
Security On-Call. This name labels the destination in notification settings. - Open Connection and select Add a connection….
- Enter a Connection Name, choose the Region that matches your PagerDuty account (US, or EU for accounts on
eu.pagerduty.com), and paste the Integration Key. - Select Save Connection, then Save.
- On Settings > Notifications under Organization settings, tick the notification types this service should receive. See Org-Level Notifications.
Testing
Section titled “Testing”The Test button on a connection only checks the integration key’s format. PagerDuty cannot check a key without opening an incident.
The Test button on the instance sends a real alert and resolves it right away, so it briefly opens a PagerDuty incident. Its urgency follows the service’s urgency setting. If the test reports that the incident could not be resolved, or that it may still be open, resolve it in PagerDuty.
If PagerDuty rejects the key, check the key and that the connection’s Region matches your PagerDuty account. A key from one region is rejected by the other region.
Severity Mapping
Section titled “Severity Mapping”Each alert’s severity comes from the level of the risk or incident it is about. Org-Level Notifications lists which notification types can reach PagerDuty. The threat-objective incident types and Risks Created and Incidents Created carry no level of their own, so they use the item’s current level. A downgrade uses the incident’s new level.
| Adversarial Level | PagerDuty Severity |
|---|---|
| Risk urgency Critical | Critical |
| Risk urgency High | Error |
| Risk urgency Medium | Warning |
| Risk urgency Low, Info, or unscored | Info |
| Incident SEV-1 | Critical |
| Incident SEV-2 | Error |
| Incident SEV-3 | Warning |
| Incident SEV-4, SEV-5, or unscored | Info |
With Dynamic notifications based on alert severity, Critical and Error open high-urgency incidents, and Warning and Info open low-urgency ones.
Alert Behavior
Section titled “Alert Behavior”- One alert per item and severity. Later notifications about the same item at the same severity are added to its open alert as log entries. That includes a return to a severity whose alert is still open or acknowledged (Medium → Critical → Medium → Critical pages once for Critical). When an item’s level rises to a new severity, a new alert opens at that severity, so on-call is paged again.
- Alerts stay open until resolved in PagerDuty. Adversarial never resolves an alert. An item that moves through several severities leaves one open alert per severity; resolve each in PagerDuty.
- Imports send one alert. Creating several risks or incidents at once, such as a CSV import, sends one summary alert instead of one alert per row. The alert is at the highest level among them and lists the item IDs.