ThreatMapper 集成 PagerDuty 实战:从告警订阅配置到事件投递机制全解析

原创2026-10-12 11:40:371,699 阅读
文章标签:网络安全云原生漏洞扫描SBOM供应链安全可观测性合规审计容器编排后端

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 控制台准备服务与集成

  1. 登录 PagerDuty 控制台,导航到 Configuration(配置) > Services(服务):

    • 如果是为集成创建新服务,点击 Add New Service;
    • 如果是把集成挂到已有服务,点击目标服务名称,进入 Integrations 标签页,再点击 New Integration,如下图所示:

    PagerDuty 服务页面中选择新建集成入口

  2. 创建集成时,选择与你预期 API 版本匹配的集成类型(Events API v1 或 v2)。PagerDuty 会为该集成生成唯一的 Integration Key(集成密钥):

    PagerDuty 中选择 API 版本创建集成

    关于 API 版本,需要说明的是:从当前仓库源码看,ThreatMapper 的投递实现固定使用 Events API v2 端点 https://events.pagerduty.com/v2/enqueue(见 pagerduty.go),并采用 v2 事件结构(RoutingKey + Action + Payload)完成告警触发;v1/v2 的选择更多影响你在 PagerDuty 侧拿到的集成密钥形态,ThreatMapper 侧只需把该密钥填入「Service Key」字段即可。

  3. 记下新集成对应的 Integration Key,随后进入 ThreatMapper 管理控制台。

第二步:在 ThreatMapper 控制台新增 PagerDuty 集成

返回 ThreatMapper 管理控制台,进入集成(Integrations)页面:

  1. 选择 PagerDuty 集成类型;

  2. 填写集成密钥(Integration Key),即上一步在 PagerDuty 创建集成时获得的密钥;

  3. 选择要订阅的通知类型,官方示例为订阅 vulnerabilities(漏洞),你也可以按需订阅其他扫描结果;

  4. 点击保存,完成订阅配置:

    ThreatMapper 控制台中填写 PagerDuty 集成密钥并订阅漏洞

配置保存后,每当有满足条件的新扫描结果出现,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 的定时任务统一调度。完整调用链如下:

  1. 定时触发:scheduler.go 周期性地将 TriggerSendNotificationsTask 入队;
  2. 任务分派:TriggerSendNotifications(notification.go)从 PostgreSQL 读取全部集成配置,为每个集成生成唯一任务 ID 并投递 SendNotificationTask;若某集成上次发送失败且处于错误退避期内(默认 15 分钟,可通过环境变量 DEEPFENCE_NOTIFICATION_ERROR_BACKOFF_MINUTES 调整,见 notification.go),则会跳过本次触发;
  3. 增量取数:processIntegration(notification.go)按订阅类型(漏洞/机密/恶意软件/合规/云合规,见 processForResource 的分派逻辑)查询自上次发送时间戳以来、状态为 success 的新扫描;
  4. 结果格式化:命中结果先经 FormatForMessagingApps(notification.go)按 fieldsMap 把内部字段名映射为可读标签(如 cve_id → CVE Id、cve_severity → Severity、rule_name → Rule Name 等),再经 injectNodeDataMap 注入节点级上下文(节点 ID、扫描 ID、节点名称、容器/镜像/主机名、Kubernetes 集群名等,见 notification.go);
  5. 发送与统计:调用集成对象的 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 处理器。

登录后查看全文
ThreatMapper