> ## 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.

# CrowdSec 告警集成

> 通过 HTTP 通知插件将 CrowdSec Security Engine 检测到的攻击来源同步到 Flashduty On-call。

CrowdSec Security Engine 是开源、可自建的入侵检测与防护引擎。它根据场景（scenario）识别暴力破解、扫描等行为，并可把检测结果交给通知插件。本集成使用其内置的 HTTP 通知插件，把每条 CrowdSec 告警转成一条 Flashduty 告警。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 CrowdSec 中配置

***

以下操作在运行 CrowdSec 本地 API（LAPI）的机器上完成。HTTP 通知插件随 CrowdSec 一起安装，无需另装。

<Steps>
  <Step title="配置 HTTP 通知插件">
    编辑 `/etc/crowdsec/notifications/http.yaml`（Docker 部署时是容器内的同名路径），保留默认的 `format`，填入 `url` 和 `method`：

    ```yaml theme={null}
    type: http
    name: http_default          # 必须与 profiles.yaml 中引用的名称一致
    log_level: info

    # 可选：每 30 秒集中推送一次队列中的告警，而不是立即推送；group_threshold 按告警条数触发
    group_wait: 30s

    format: |
      {{.|toJson}}

    url: https://api.flashcat.cloud/event/push/alert/crowdsec?integration_key=<your_integration_key>
    method: POST
    ```

    `format` 必须保持 `{{.|toJson}}`：Flashduty 解析的正是 CrowdSec 告警列表的默认 JSON 结构。`url` 换成 Flashduty 集成的完整推送地址。Flashduty 通过地址中的 `integration_key` 识别集成，请像保管密钥一样保管该文件。
  </Step>

  <Step title="在 profile 中启用通知">
    编辑 `/etc/crowdsec/profiles.yaml`，在需要通知的 profile 下加入 `notifications`：

    ```yaml theme={null}
    name: default_ip_remediation
    filters:
     - Alert.Remediation == true && Alert.GetScope() == "Ip"
    decisions:
     - type: ban
       duration: 4h
    notifications:
     - http_default
    on_success: break
    ```

    只有匹配该 profile 过滤条件的告警才会推送。保存后重载 CrowdSec：`sudo systemctl reload crowdsec`（Docker 部署时重启容器）。
  </Step>

  <Step title="开启超时自动关闭">
    CrowdSec 告警是一次性事件：封禁到期后 CrowdSec 不会再推送任何通知。请在接收这些告警的协作空间中开启 [超时自动关闭](/zh/on-call/channel/create-edit)，建议超时时长与封禁时长（上例为 4 小时）相同，计时起点选择 **故障触发**。故障关闭时，关联的告警一并关闭。
  </Step>

  <Step title="验证">
    在 CrowdSec 机器上执行：

    ```bash theme={null}
    sudo cscli notifications test http_default
    ```

    Flashduty 中会出现一条标题为 `test alert`、等级为 Info 的告警。它不会自动恢复，请手动关闭，或等待超时自动关闭。也可以用 `cscli notifications list` 查看插件是否已加载。
  </Step>
</Steps>

## 推送内容

***

CrowdSec 每次请求推送一个 JSON 数组，每个元素是一条告警；启用 `group_wait` 或 `group_threshold` 后，CrowdSec 会攒到下一次推送时机再发出，推送最多比检测晚 `group_wait`，一个请求可能包含多条。Flashduty 为数组中的每个元素创建一条告警。事件明细（`events`）和 `meta` 中的原始日志不会进入 Flashduty。

## Alert Key

***

Flashduty 使用 CrowdSec 为每条告警生成的 `uuid` 作为 Alert Key。请求重试时会带相同的 `uuid`，合并到同一条告警；同一个来源 IP 后续再次触发，会是新的 `uuid`，产生新的告警。

个别没有 `uuid` 的旧版本，Flashduty 用场景、来源类型、来源值和 `start_at` 计算 Alert Key。这些字段缺失时请求会被拒绝。

## 告警等级

***

CrowdSec 不提供严重程度，所有告警都以 **Warning** 等级触发，处于模拟模式（`simulated`）的告警也是。`cscli notifications test` 发出的测试告警为 **Info**，并使用独立的 Alert Key，不会与真实告警合并。

## 标签

***

| 标签 | 来源 |
| :- | :- |
| `check` / `scenario` | 触发的场景，如 `crowdsecurity/ssh-bf` |
| `resource` / `source_value` | 攻击来源的值，通常是 IP |
| `source_scope` | 来源类型，如 `Ip`、`Range` |
| `source_range` | 来源所在网段 |
| `as_name` / `as_number` | 来源的自治系统 |
| `country` | 来源国家代码 |
| `events_count` | 触发场景的事件数 |
| `start_at` / `stop_at` | 场景开始和结束时间 |
| `scenario_version` | 场景版本 |
| `machine_id` | 上报告警的机器 |
| `decision_type` / `decision_duration` / `decision_origin` | 处置类型、时长和来源 |
| `simulated` / `remediation` | 是否为模拟告警、是否产生处置 |
| `uuid` | CrowdSec 告警 ID，即 Alert Key |

告警标题为 `<场景> from <来源值>`，描述为 CrowdSec 的 `message`。

## 常见问题

***

<AccordionGroup>
  <Accordion title="推送后 Flashduty 没有告警？">
    先执行 `cscli notifications test http_default`，确认能收到测试告警。收不到时检查 `url` 是否包含 `integration_key`，以及 CrowdSec 日志（`/var/log/crowdsec.log`）中 http 插件的报错。测试告警能收到但真实告警没有，通常是 profile 的过滤条件没有匹配，或 profile 中没有列出 `http_default`。
  </Accordion>

  <Accordion title="需要配置签名或认证头吗？">
    不需要。Flashduty 只通过 `integration_key` 识别集成，不校验额外的请求头。
  </Accordion>

  <Accordion title="告警为什么一直不关闭？">
    CrowdSec 没有恢复事件。请开启协作空间的超时自动关闭，或在 Flashduty 中手动关闭该告警。
  </Accordion>
</AccordionGroup>

更多配置项请参阅 [CrowdSec HTTP 通知插件](https://docs.crowdsec.net/docs/notification_plugins/http)。