> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aqua Tracee 告警集成

> 通过 Tracee 的 Webhook 输出目的地，将运行时安全检测事件同步到 Flashduty On-call。

通过 Tracee 的 Webhook 输出目的地，将运行时安全检测事件（detection）同步到 Flashduty On-call。同一条检测规则在同一个容器中再次命中时，合并到同一条告警。Tracee 的 Webhook 只推送检测事件，不推送恢复通知，告警需要由协作空间的超时自动关闭或手动关闭。

<div className="hide">
  ## 在 Flashduty On-call

  ***

  您可通过以下两种方式获取集成推送地址，任选其一即可。

  ### 使用专属集成

  1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
  2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
  3. 选择 **Aqua Tracee**，点击 **保存**
  4. 打开生成的集成卡片，复制 **推送地址**

  ### 使用共享集成

  1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
  2. 选择 **Aqua Tracee**，填写集成名称
  3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 Tracee 中配置

***

<Steps>
  <Step title="添加 Webhook 输出目的地">
    Tracee 通过 `--output` 参数或配置文件的 `output:` 段定义输出目的地。把 Flashduty 推送地址填入 `url`，格式保持默认的 `json`（Webhook 默认以 `application/json` 向该地址 POST 每个事件，请求中不带签名，也不需要额外的请求头）。

    命令行：

    ```console theme={null}
    tracee \
      --output destinations.flashduty.type=webhook \
      --output 'destinations.flashduty.url=https://api.flashcat.cloud/event/push/alert/tracee?integration_key=<your_integration_key>'
    ```

    配置文件：

    ```yaml theme={null}
    output:
      destinations:
        - name: flashduty
          type: webhook
          url: https://api.flashcat.cloud/event/push/alert/tracee?integration_key=<your_integration_key>
    ```
  </Step>

  <Step title="只推送检测事件">
    Flashduty 只为带有 `threat` 字段的检测事件创建告警，不带 `threat` 的普通事件（例如 `sched_process_exec`）会被确认并丢弃。为避免把全部事件发往 Flashduty，建议用 stream 只把检测事件路由到这个目的地：

    ```yaml theme={null}
    output:
      destinations:
        - name: flashduty
          type: webhook
          url: https://api.flashcat.cloud/event/push/alert/tracee?integration_key=<your_integration_key>
      streams:
        - name: flashduty_stream
          destinations:
            - flashduty
          filters:
            events:
              - anti_debugging
              - <your_detection_event_name>
    ```

    `events` 中填写需要告警的检测事件名称（detector 或 signature 产生的事件，例如 `anti_debugging`）。

    <Warning>
      请使用默认的 `json` 格式。使用 `gotemplate=` 自定义模板时，Flashduty 仍按默认 JSON 的字段名解析，缺失的字段会导致告警缺少标签或被合并到同一条告警。
    </Warning>
  </Step>

  <Step title="开启超时自动关闭">
    Tracee 的检测事件没有恢复通知：威胁被处置后，Flashduty 不会收到通知。

    请在接收这些告警的协作空间中开启 [超时自动关闭](/zh/on-call/channel/create-edit)，建议时长 24 小时。同一条规则在同一个容器中再次命中，在合并窗口内会更新同一条告警，告警已关闭后再次命中会触发新的告警。
  </Step>

  <Step title="验证">
    Tracee 没有"发送测试通知"功能。让 Tracee 触发一次真实检测，或用下面的命令向推送地址发送一条示例检测事件：

    ```console theme={null}
    curl -X POST 'https://api.flashcat.cloud/event/push/alert/tracee?integration_key=<your_integration_key>' \
      -H 'Content-Type: application/json' \
      -d '{"name":"anti_debugging","threat":{"name":"Anti-Debugging detected","severity":1,"description":"example"},"workload":{"process":{"host_pid":1234,"pid":1234}}}'
    ```

    确认 Flashduty 出现活动告警，标题为 `threat.name`。示例事件会产生一条真实告警，请在验证后手动关闭。
  </Step>
</Steps>

## Alert Key

***

Tracee 的事件没有唯一 ID。Flashduty 用规则标识加运行位置组成 Alert Key（对 `"tracee"`、规则标识、运行位置用 NUL 分隔后取 MD5）：

* **规则标识**：依次取 `threat.properties.signatureID`、`threat.properties.id`、事件 `name`。Tracee 文档将 `threat.properties.signatureID` 列为检测的签名 ID；新版 detector 产生的事件没有该字段，用事件 `name` 代替
* **运行位置**：事件在容器中时取 `workload.container.id`；不在容器中时取 `workload.process.host_pid`，再退到 `workload.process.pid`

因此同一条规则在同一容器中的重复命中会合并为一条告警，不同规则或不同容器是独立的告警。事件时间、进程名、事件数据、告警等级和 `threat.name` 的变化不会改变 Alert Key。

<Note>
  不在容器中的事件只能用进程 ID 区分。Tracee 事件不携带主机名，多台主机上的同一条规则如果恰好有相同的进程 ID，会合并为一条告警；这类场景建议为每台主机使用单独的集成。
</Note>

## 告警等级

***

Tracee 的 `threat.severity` 在默认 JSON 中为数字（`INFO`=0 到 `CRITICAL`=4）：

| Tracee `threat.severity` | Flashduty 等级 |
| :- | :- |
| `4`（CRITICAL）、`3`（HIGH） | Critical |
| `2`（MEDIUM） | Warning |
| `1`（LOW）、`0`（INFO） | Info |
| 空值或未知值 | Warning |

## 标签

***

Flashduty 写入以下标签（有值才写入）：`rule_id`、`signature_id`、`event_name`、`category`、`threat_severity`、`mitre_tactic`、`mitre_technique_id`、`mitre_technique`、`container_id`、`container_name`、`image`、`pod`、`namespace`、`process`、`executable`、`pid`、`host_pid`、`policies`、`detected_from`。事件的 `data` 数组（文件路径、命令参数等）不会写入标签。

## 排查问题

***

* **Tracee 日志出现 `Error sending webhook, http status`**：确认 URL 完整且包含 `integration_key`
* **没有收到告警**：确认事件带有 `threat` 字段；普通事件不会产生告警，且 stream 的 `events` 需要包含该检测事件
* **告警没有恢复**：Tracee 不推送恢复通知，请开启协作空间的超时自动关闭，或手动关闭告警
* **不同主机的告警被合并**：不在容器中的事件只靠进程 ID 区分，参见上文 Alert Key 的说明

更多字段含义请参阅 [Tracee 输出文档](https://aquasecurity.github.io/tracee/latest/outputs/) 和 [事件结构](https://aquasecurity.github.io/tracee/latest/outputs/event-structure/)。