ThreatMapper 集成 PagerDuty 实战:从告警订阅配置到事件投递机制全解析
ThreatMapper 集成 PagerDuty 实战:从告警订阅配置到事件投递机制全解析
ThreatMapper 作为开源云原生应用保护平台(CNAPP),在完成漏洞、恶意软件、敏感信息与合规扫描后,可以借助 PagerDuty 的告警与值班(on-call)体系,把安全事件第一时间推送给响应团队。本文以官方文档为主线,完整讲解在 PagerDuty 控制台创建集成、在 ThreatMapper 管理控制台填写集成密钥并订阅扫描结果的步骤,同时深入仓库源码,剖析 ThreatMapper 侧的事件构建、严重级别映射、凭据校验与后台定时投递链路,帮助你不仅会配置,还能理解每一次告警背后的完整调用链。
集成原理概览
ThreatMapper 通过 PagerDuty API(v1 或 v2)向其事件平台(Events API)投递通知:每当有新的扫描结果命中订阅条件时,后台会把格式化后的告警消息封装为 PagerDuty 事件并发送到 https://events.pagerduty.com/v2/enqueue(该端点常量定义于 pagerduty.go)。PagerDuty 随后依据路由密钥(routing key / integration key)将该事件关联到对应服务,触发事件通知与值班升级流程。
整体配置涉及两个控制台:
- PagerDuty 控制台:创建服务(Service)与集成(Integration),获取 API 版本对应的集成密钥(Integration Key);
- ThreatMapper 管理控制台:在「Integrations」页面新增 PagerDuty 集成,填写密钥、选择订阅的扫描类型(默认示例为 vulnerabilities)并保存。
第一步:在 PagerDuty 控制台准备服务与集成
-
登录 PagerDuty 控制台,导航到 Configuration(配置) > Services(服务):
- 如果是为集成创建新服务,点击 Add New Service;
- 如果是把集成挂到已有服务,点击目标服务名称,进入 Integrations 标签页,再点击 New Integration,如下图所示:
-
创建集成时,选择与你预期 API 版本匹配的集成类型(Events API v1 或 v2)。PagerDuty 会为该集成生成唯一的 Integration Key(集成密钥):
关于 API 版本,需要说明的是:从当前仓库源码看,ThreatMapper 的投递实现固定使用 Events API v2 端点
https://events.pagerduty.com/v2/enqueue(见 pagerduty.go),并采用 v2 事件结构(RoutingKey+Action+Payload)完成告警触发;v1/v2 的选择更多影响你在 PagerDuty 侧拿到的集成密钥形态,ThreatMapper 侧只需把该密钥填入「Service Key」字段即可。 -
记下新集成对应的 Integration Key,随后进入 ThreatMapper 管理控制台。
第二步:在 ThreatMapper 控制台新增 PagerDuty 集成
返回 ThreatMapper 管理控制台,进入集成(Integrations)页面:
-
选择 PagerDuty 集成类型;
-
填写集成密钥(Integration Key),即上一步在 PagerDuty 创建集成时获得的密钥;
-
选择要订阅的通知类型,官方示例为订阅 vulnerabilities(漏洞),你也可以按需订阅其他扫描结果;
-
点击保存,完成订阅配置:
配置保存后,每当有满足条件的新扫描结果出现,ThreatMapper 便会向 PagerDuty 推送对应告警事件。
配置字段与数据结构详解
从源码层面看,PagerDuty 集成的请求结构与配置项定义在 types.go 中:
type PagerDuty struct {
Config Config `json:"config"`
IntegrationType string `json:"integration_type"`
NotificationType string `json:"notification_type"`
Filters reporters.FieldsFilters `json:"filters"`
Message string `json:"message"`
Resource string `json:"resource"`
Severity string `json:"severity"`
}
type Config struct {
ServiceKey string `json:"service_key" validate:"required,min=1" required:"true"`
APIKey string `json:"api_key" validate:"required,min=1" required:"true"`
}
其中关键字段含义如下:
| 字段 | 对应 JSON 键 | 含义与要求 |
|---|---|---|
Config.ServiceKey |
service_key |
PagerDuty 集成的 Integration Key(routing key),必填,长度至少 1 字符 |
Config.APIKey |
api_key |
PagerDuty API Token(用于 REST API 凭据校验与请求鉴权),必填,长度至少 1 字符 |
IntegrationType |
integration_type |
固定为 pagerduty,与 constants.go 中 PagerDuty = "pagerduty" 对应 |
NotificationType / Resource |
notification_type / resource |
订阅的扫描类型,如漏洞扫描 |
Severity |
severity |
告警严重级别(critical / high / medium / low / info) |
Filters |
filters |
节点、容器与字段过滤条件,用于缩小告警范围 |
ValidateConfig 通过 go-playground/validator 校验 service_key 与 api_key 均非空(types.go);在 handler/integration.go 的 AddIntegration 流程中,请求会依次经过解码、ValidateConfig 校验与 IsValidCredential 凭据校验,全部通过后才写入 PostgreSQL 集成表。
告警事件如何构建:严重级别映射与 Payload
当扫描结果产生后,ThreatMapper 会调用 SendNotification 构建 PagerDuty 事件(见 pagerduty.go):
var pagerdutySeverityMapping = map[string]string{
"critical": "critical",
"high": "error",
"medium": "warning",
"low": "info",
"info": "info",
}
严重级别映射表是理解告警等级的关键:ThreatMapper 的扫描严重级别会被转换为 PagerDuty 事件级别,high 映射为 error、medium 映射为 warning、low/info 映射为 info、critical 保持 critical;未命中映射时兜底为 info。这样 PagerDuty 的自动升级与值班策略就能按 critical/error 等真实事件级别正确响应。
构建的 v2 事件结构如下:
incident := pagerduty.V2Event{
RoutingKey: p.Config.ServiceKey, // 集成密钥
Action: "trigger", // 触发事件
Payload: &pagerduty.V2Payload{
Summary: fmt.Sprintf("Deepfence - %s Subscription", p.Resource),
Source: "deepfence",
Severity: sev,
Details: map[string]string{
"alert": m, // 格式化后的扫描结果文本
},
},
}
事件标题固定为 Deepfence - <订阅类型> Subscription,来源标识为 deepfence,详情体(Details)中携带格式化后的告警文本 alert。
消息本身的格式化逻辑在 FormatMessage(pagerduty.go):每条扫描结果以 <Resource> #序号 开头,随后逐行输出字段名与取值,多条结果之间用空行分隔,便于值班人员在 PagerDuty 中直接阅读。
投递端点与鉴权方式
实际发送通过 createPagerDutyEvent 完成(pagerduty.go):
- 目标端点:
POST https://events.pagerduty.com/v2/enqueue; - 请求头:
Content-Type: application/json,Authorization: Token token=<APIKey>; - 响应校验:只有 HTTP
200 OK才视为投递成功,否则按非 200 状态码返回错误; - 网络层错误(连接拒绝、超时)会被统一封装,见 errors.go。
此外,SendNotification 开头会先检查 APIKey 与 ServiceKey 是否为空,为空时直接记录日志并跳过发送(pagerduty.go),避免无效配置产生无意义请求。
凭据校验与敏感信息保护
新增或更新集成时,服务端会调用 IsValidCreds(pagerduty.go)对 API Token 做可用性探测:向 https://api.pagerduty.com/services?include[]=integrations 发起请求,携带 Authorization: Token token=<APIKey> 与 Accept: application/vnd.pagerduty+json;version=2,返回 200 OK 即视为凭据有效(源码中以 TODO 注释标明该校验逻辑尚待进一步细化错误信息)。
出于安全考虑,service_key 与 api_key 均被列入 constants.go 的 SensitiveFields 敏感字段表。在 integration.go 的 RedactSensitiveFieldsInConfig 中,集成列表接口返回配置时会对这些字段做脱敏处理(保留前半段、后半段替换为 ****),确保密钥不会明文回显到前端。
后台投递链路:从扫描完成到 PagerDuty 告警
PagerDuty 告警并非即时同步推送,而是由 deepfence_worker 的定时任务统一调度。完整调用链如下:
- 定时触发:scheduler.go 周期性地将
TriggerSendNotificationsTask入队; - 任务分派:
TriggerSendNotifications(notification.go)从 PostgreSQL 读取全部集成配置,为每个集成生成唯一任务 ID 并投递SendNotificationTask;若某集成上次发送失败且处于错误退避期内(默认 15 分钟,可通过环境变量DEEPFENCE_NOTIFICATION_ERROR_BACKOFF_MINUTES调整,见 notification.go),则会跳过本次触发; - 增量取数:
processIntegration(notification.go)按订阅类型(漏洞/机密/恶意软件/合规/云合规,见processForResource的分派逻辑)查询自上次发送时间戳以来、状态为success的新扫描; - 结果格式化:命中结果先经
FormatForMessagingApps(notification.go)按fieldsMap把内部字段名映射为可读标签(如cve_id→CVE Id、cve_severity→Severity、rule_name→Rule Name等),再经injectNodeDataMap注入节点级上下文(节点 ID、扫描 ID、节点名称、容器/镜像/主机名、Kubernetes 集群名等,见 notification.go); - 发送与统计:调用集成对象的
SendNotification推送至 PagerDuty,并按成功/失败条数更新集成指标与状态(notification.go)。
其中第 4 步之所以会做「字段名 → 人类可读标签」的映射,是因为 IsMessagingFormat(integration.go)将 PagerDuty 与 Slack、Teams、Email、Jira 一并归类为消息型(messaging)集成,这类集成需要输出适合值班人员直接阅读的文本消息,而非结构化 JSON。需要留意的是,PagerDuty 的 SendSummaryLink 返回 false(pagerduty.go),即它不支持仅推送摘要链接的模式,始终发送完整的结果明细。
验证与常见问题排查
配置完成后,可从以下几方面验证与排障:
- 触发一次新扫描:让某个被监控节点产生新的漏洞扫描结果,观察 PagerDuty 服务是否收到
Deepfence - <类型> Subscription事件; - 查看集成状态:ThreatMapper 集成列表页会展示
last_error_msg(最近一次错误信息);发送失败时 worker 会将错误写入集成状态,并在退避期内暂停该集成的重试; - 校验密钥:确认
service_key(集成密钥)与api_key(API Token)均非空且具备相应权限,可通过集成新增/更新接口的凭据校验步骤提前发现无效 Token; - 确认端点可达:ThreatMapper 服务器需能访问
events.pagerduty.com(事件投递)与api.pagerduty.com(凭据校验),网络隔离环境需放行这两个域名; - 关注严重级别映射:若希望
high漏洞直接触发 PagerDuty 的紧急值班策略,需在 PagerDuty 侧将error事件级别纳入对应升级规则。
小结
ThreatMapper 的 PagerDuty 集成虽然配置入口只有「PagerDuty 控制台建集成、ThreatMapper 控制台填密钥并订阅」两步,但其背后是一条完整的自动化告警流水线:worker 定时扫描增量结果 → 字段语义化与节点信息注入 → 严重级别映射 → v2 事件封装 → Token 鉴权投递 → 失败退避与状态回写。理解这条链路,可以帮助你在部署 ThreatMapper 时更精准地设计告警订阅范围与 PagerDuty 值班策略,让每一次安全扫描结果都能被正确、及时地送达响应团队。
可进一步阅读的仓库资料:集成实现源码、集成数据结构、后台通知流水线、集成管理 API 处理器。


