ThreatMapper HTTP Endpoint 集成指南:将漏洞与合规告警转发到任意 HTTP 服务
ThreatMapper HTTP Endpoint 集成指南:将漏洞与合规告警转发到任意 HTTP 服务
ThreatMapper 支持将各类扫描告警(漏洞、密钥泄漏、恶意软件、合规检查、云合规)以 JSON 负载的形式转发到任意 HTTP 端点,适用于自建告警网关、Webhook 聚合器或内部 SIEM 等场景。本文以官方集成文档 docs/docs/integrations/http-endpoint.md 为核心,结合 HTTP Endpoint 集成实现源码 与 通知调度逻辑,完整讲解配置方法、认证头设置、消息格式与底层工作流,读者可据此快速搭建一条可用的 HTTP 告警通道。
功能概述与适用场景
HTTP Endpoint 是 ThreatMapper 集成体系(Integrations)中的一种通知渠道。在 ThreatMapper 中,任何一次新扫描发现结果(例如 CI 扫描 或 自动扫描 产生的漏洞、密钥、恶意软件、合规与云合规告警)都会触发通知,将被检测到的详细信息提交到已配置的通知服务,详见 Integrations 总览。
对于 HTTP Endpoint 集成,ThreatMapper 会在扫描产生结果后,通过 HTTP POST 请求将告警数据推送到你指定的 URL。它适合:
- 将告警接入自建的消息网关、告警聚合平台或内部监控系统;
- 对接需要自定义协议或自定义鉴权的企业系统;
- 用简单 Webhook 方式接收 ThreatMapper 的结构化扫描结果。
与其他聊天类通知(Slack、Teams、PagerDuty、Email、Jira 等)不同,HTTP Endpoint 属于**非消息格式(non-messaging format)**集成:在 integration.go 的 IsMessagingFormat 判断中,HTTP Endpoint 不在消息格式列表中,因此发送的负载是结构化 JSON 数组而非聊天消息模板,接收方可以按字段直接解析。同时 SendSummaryLink() 返回 false(见 http-endpoint.go),表示该集成不会发送扫描摘要链接,而是逐条发送扫描结果明细。
在 Management Console 中配置 HTTP Endpoint
在 ThreatMapper 控制台的 Integrations 页面选择 HTTP Endpoint,填写以下配置项:
| 配置项 | 是否必填 | 说明 |
|---|---|---|
| HTTP Endpoint URL | 必填 | 接收通知的目标地址,例如 http://10.3.16.2:8080。该地址需能被 ThreatMapper 服务器(deepfence_server)访问到 |
| Authentication Header | 可选 | 当目标 API 服务器要求认证时,可设置认证 HTTP 头(header)的值 |
配置完成后,每当有新扫描结果产生,ThreatMapper 就会向该端点推送通知。
配置项的校验规则
从源码 types.go 可以看到两个配置项的具体约束:
URL:JSON 字段url,带有validate:"required,url"标签,即必填且必须是合法 URL;AuthHeader:JSON 字段auth_header,可选,没有必填约束。
type Config struct {
URL string `json:"url" validate:"required,url" required:"true"`
AuthHeader string `json:"auth_header"`
}
在新增/更新集成时,服务端通过 ValidateConfig(validate) 调用 validate.Struct(h.Config) 对配置做校验(见 http-endpoint.go);校验不通过会直接返回 ValidatorError,配置不会入库。
另外需要注意:auth_header 被列入 constants.go 的 SensitiveFields 敏感字段集合。在控制台查询已配置的集成时,服务端会对敏感字段做脱敏处理——integration.go 中的 RedactSensitiveFieldsInConfig 会把 auth_header 的原值替换为掩码字段(形如 auth_header_masked),因此认证头值在列表接口中不会以明文返回。
认证头(Authentication Header)的使用方式
当目标 HTTP API 服务器要求认证时,在集成配置中填入认证头的值即可。底层实现中,该值会被作为 HTTP 请求的 Authorization 请求头发送。
从 http-endpoint.go 的实现可见:
if h.Config.AuthHeader != "" {
req.Header.Set("Authorization", h.Config.AuthHeader)
}
也就是说,只需把完整的认证头值(例如 Bearer <token>、Basic <base64> 或自定义的 token 字符串)填到 Authentication Header 字段,ThreatMapper 就会原样放入 Authorization 头中。如果留空,则发送不带认证的请求。
消息发送格式与请求细节
请求方式与头部
- 方法:HTTP
POST; - Content-Type:
application/json; - Body:扫描结果数组的 JSON 序列化结果(
json.Marshal(message)),其中message为[]map[string]interface{}类型,即一组告警记录对象。
实现见 http-endpoint.go。
负载结构示例
每个数组元素对应一条扫描结果,字段随扫描类型而不同,并会注入公共的节点/扫描上下文。从 notification.go 的 injectNodeDataMap 可以看出,每条记录都会附带以下字段:
| 字段 | 说明 |
|---|---|
node_id |
节点 ID |
scan_id |
扫描 ID |
node_name |
节点名称 |
node_type |
节点类型(host / image / container 等) |
docker_container_name |
容器名(若为容器扫描) |
docker_image_name |
镜像名(若为镜像扫描) |
host_name |
主机名(若为主机扫描) |
kubernetes_cluster_name |
Kubernetes 集群名(若适用) |
cloud_account_id |
云账号 ID(若适用) |
此外,外层还会通过 extras 携带扫描的公共信息(utils.ToMapany),包括 scan_type、scan_result_link(指向控制台扫描结果页的链接)以及 severity_counts(严重性统计)等。
不同扫描类型的字段差异(如漏洞扫描的 cve_id、cve_severity、cve_cvss_score,密钥扫描的 rule_id、matched_content,恶意软件扫描的 rule_name、file_severity 等)参见 notification.go 中的 fieldsMap 定义。注意:fieldsMap 主要用于消息格式集成(聊天应用)的字段映射;HTTP Endpoint 走非消息格式分支,发送的是扫描结果的全字段 JSON(见 notification.go 的 else 分支),接收方可按 utils.ToMapT 输出的完整字段自行解析。
连通性验证与错误处理
添加集成时的测试消息
在新增(或更新)集成时,服务端会先调用 IsValidCredential 做连通性验证(见 http-endpoint.go):向配置的 URL 发送一条测试消息:
{"text": "Test message from Deepfence"}
只有当目标端点返回 HTTP 200 时,验证才被认为通过;否则控制台会返回 ErrInvalidCredential 错误(见 integration.go),集成不会保存。因此,配置完成后立刻收到一条 Test message from Deepfence 是正常现象,可用来确认通道是否打通。
发送失败与重试
正式通知发送通过 utils.GetHTTPClient() 提供的 HTTP 客户端执行(utils.go),该客户端超时时间为 10 秒,并会继承环境代理设置。错误处理逻辑见 errors.go:
- 连接被拒绝(
syscall.ECONNREFUSED)→ 返回Connection Refused; - 连接超时(
net.Error且Timeout())→ 返回Connection Timeout; - 响应状态码非 200 → 返回带状态码的
HTTPError。
通知发送失败时,集成记录会被标记错误信息(UpdateIntegrationStatus,见 notification.go),并在 通知错误退避机制 生效期间跳过该集成:默认退避 15 分钟,可通过环境变量 DEEPFENCE_NOTIFICATION_ERROR_BACKOFF_MINUTES 调整。成功恢复后错误标记会被清除,告警通道自动恢复。
底层工作流:告警如何被推送到 HTTP 端点
了解整体链路有助于排查问题和设计接收端:
- 定时触发:调度器每 60 秒入队一次
TriggerSendNotificationsTask(见 scheduler.go)。 - 扫描增量查询:TriggerSendNotifications 读取所有已配置的集成,为每个集成入队
SendNotificationTask;SendNotifications 按集成配置的过滤器查询自上次发送以来新产生的扫描结果(默认时间窗口 60000 毫秒,见DefaultNotificationInterval)。 - 结果过滤与组装:按扫描类型(Vulnerability / Secret / Malware / Compliance / CloudCompliance)分别处理(processForResource),只取状态为成功的扫描结果,并注入节点上下文信息。
- 调用集成发送:对于 HTTP Endpoint,调用 SendNotification,将结果数组以 JSON POST 发送到目标 URL。
- 状态维护:发送成功后更新
last_event_updated_at与发送指标,确保同一批结果不会重复推送。
使用建议与注意事项
- 接收端应能快速响应:HTTP 客户端超时为 10 秒(utils.go),接收端建议尽快返回 200,避免因超时被判定为发送失败而触发退避。
- 测试消息与真实消息区分:通道验证阶段收到的是
{"text": "Test message from Deepfence"}测试消息,正式扫描结果则是结构化的数组负载,接收端可按text字段或scan_type字段区分两者。 - 认证头直接透传:Authentication Header 的值会原样写入
Authorization头,若端点使用 Bearer Token,应填入Bearer <token>完整形式。 - 敏感信息保护:
auth_header属敏感字段,在集成列表接口中会被掩码展示,不要在日志或配置导出中明文保存该值。 - 端点需可达:目标 URL 必须能被 deepfence_server(或执行通知任务的 deepfence_worker)所在网络访问,内网地址
http://10.3.16.2:8080这类示例仅适用于与控制台同网段的接收端。
相关参考
- 集成入口与工厂方法:integration.go
- HTTP Endpoint 配置模型:types.go
- HTTP Endpoint 发送实现:http-endpoint.go
- 通知调度与字段注入:notification.go
- 集成管理 API 路由:router.go
- 集成增删改查处理器:integration.go