企业官网建设流程全解析

• 网络安全
• 应用安全
• 云原生
• 漏洞扫描

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，填写以下配置项：

配置完成后，每当有新扫描结果产生，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头中。如果留空，则发送不带认证的请求。

消息发送格式与请求细节

请求方式与头部

• 方法：HTTPPOST；
• Content-Type：application/json；
• Body：扫描结果数组的 JSON 序列化结果（json.Marshal(message)），其中message为[]map[string]interface{}类型，即一组告警记录对象。

实现见 http-endpoint.go。

负载结构示例

每个数组元素对应一条扫描结果，字段随扫描类型而不同，并会注入公共的节点/扫描上下文。从 notification.go 的injectNodeDataMap可以看出，每条记录都会附带以下字段：

此外，外层还会通过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 端点

了解整体链路有助于排查问题和设计接收端：

1. 定时触发：调度器每 60 秒入队一次TriggerSendNotificationsTask（见 scheduler.go）。
2. 扫描增量查询：TriggerSendNotifications 读取所有已配置的集成，为每个集成入队SendNotificationTask；SendNotifications 按集成配置的过滤器查询自上次发送以来新产生的扫描结果（默认时间窗口 60000 毫秒，见DefaultNotificationInterval）。
3. 结果过滤与组装：按扫描类型（Vulnerability / Secret / Malware / Compliance / CloudCompliance）分别处理（processForResource），只取状态为成功的扫描结果，并注入节点上下文信息。
4. 调用集成发送：对于 HTTP Endpoint，调用 SendNotification，将结果数组以 JSON POST 发送到目标 URL。
5. 状态维护：发送成功后更新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

• 网络安全
• 应用安全
• 云原生
• 漏洞扫描