ai-security-xdr/haobang-security-dm/upgrade-doc/v2/api/NDRServer任务配置示例.md

# NDRServer API 拉取配置示例

以下命令在 `syslog-serve` 启动、v2 数据库脚本验证通过后执行。示例中的地址、设备 ID 和凭据需要替换为现场值。

先说明两个概念：

- 凭据：设备提供的 AppKey 和 AppSecret，一台设备的两个任务可以共用一份凭据；
- 任务：具体拉取哪一类日志。告警和流量日志是两个任务，各自记录已经拉到的时间。
- `configVersion`：任务每修改一次都会增加，用于防止两个人同时覆盖配置。调用修改、暂停或恢复接口时使用查询结果中的最新值。

## 1. 准备变量

```bash
export SERVE_API=http://127.0.0.1:8189/syslogserve
export DEVICE_ID=<设备ID>
export NDR_BASE_URL=https://<设备证书域名>/ndr/api
export CREDENTIAL_REF=<凭据引用>
export APP_KEY=<AppKey>
export APP_SECRET=<AppSecret>
export INITIAL_START_TIME=<YYYY-MM-DDTHH:mm:ss+08:00>
```

变量说明：

| 变量 | 填写内容 | 示例格式 |
| --- | --- | --- |
| `SERVE_API` | `syslog-serve` 管理地址 | `http://127.0.0.1:8189/syslogserve` |
| `DEVICE_ID` | 平台中的设备 ID | 整数 |
| `NDR_BASE_URL` | NDR 接口根地址，结尾固定为 `/ndr/api` | `https://ndr.example.com/ndr/api` |
| `CREDENTIAL_REF` | 本次凭据的名称 | `ndr-prod-01` |
| `APP_KEY` | 设备提供的 AppKey | 字符串 |
| `APP_SECRET` | 设备提供的 AppSecret | 字符串 |
| `INITIAL_START_TIME` | 第一次从什么时间开始拉取 | `2026-09-06T00:00:00+08:00` |

尖括号表示待填写内容，不能把 `<设备ID>` 这样的文字直接执行。

凭据通过现场受控终端录入，不提交到代码库。

## 2. 创建凭据

```bash
curl -fsS -X POST "${SERVE_API}/api/api-pull-credentials" \
  -H 'Content-Type: application/json' \
  --data-binary "{
    \"credentialRef\":\"${CREDENTIAL_REF}\",
    \"deviceId\":${DEVICE_ID},
    \"adapterType\":\"NDRSERVER_V1\",
    \"credentialVersion\":\"initial-v1\",
    \"appKey\":\"${APP_KEY}\",
    \"appSecret\":\"${APP_SECRET}\"
  }"
```

接口响应不返回 AppKey、AppSecret 和 Token。

创建成功时 HTTP 状态码为 `201`，响应中会有 `credentialRef` 和 `configVersion`。返回 `409` 一般表示同名凭据已经存在，此时先查询现有凭据，不要反复创建。

## 3. 创建告警任务

```bash
curl -fsS -X POST "${SERVE_API}/api/api-pull-tasks" \
  -H 'Content-Type: application/json' \
  --data-binary "{
    \"deviceId\":${DEVICE_ID},
    \"taskName\":\"NDR-威胁告警-API拉取\",
    \"adapterType\":\"NDRSERVER_V1\",
    \"streamKey\":\"NDR_ALERT\",
    \"baseUrl\":\"${NDR_BASE_URL}\",
    \"credentialRef\":\"${CREDENTIAL_REF}\",
    \"pollIntervalSeconds\":1,
    \"pageSize\":100,
    \"maxPagesPerRun\":1000,
    \"schedulerPriority\":100,
    \"connectTimeoutMs\":5000,
    \"requestTimeoutMs\":30000,
    \"windowSizeSeconds\":60,
    \"safetyDelaySeconds\":120,
    \"lookbackSeconds\":300,
    \"maxResponseBytes\":16777216,
    \"initialStartTime\":\"${INITIAL_START_TIME}\",
    \"extraConfig\":{}
  }"
```

## 4. 创建流量日志任务

流量任务和告警任务分别维护 checkpoint：

```bash
curl -fsS -X POST "${SERVE_API}/api/api-pull-tasks" \
  -H 'Content-Type: application/json' \
  --data-binary "{
    \"deviceId\":${DEVICE_ID},
    \"taskName\":\"NDR-原始网络日志-API拉取\",
    \"adapterType\":\"NDRSERVER_V1\",
    \"streamKey\":\"NDR_FLOW_LOG\",
    \"baseUrl\":\"${NDR_BASE_URL}\",
    \"credentialRef\":\"${CREDENTIAL_REF}\",
    \"pollIntervalSeconds\":1,
    \"pageSize\":500,
    \"maxPagesPerRun\":1000,
    \"schedulerPriority\":10,
    \"connectTimeoutMs\":5000,
    \"requestTimeoutMs\":30000,
    \"windowSizeSeconds\":60,
    \"safetyDelaySeconds\":120,
    \"lookbackSeconds\":0,
    \"maxResponseBytes\":16777216,
    \"initialStartTime\":\"${INITIAL_START_TIME}\",
    \"extraConfig\":{}
  }"
```

`pageSize=500` 是初始值，上线前根据响应大小、接口耗时和实际吞吐调整。

## 5. 验证和启用

任务创建后默认为暂停状态。记录响应中的 `taskId` 和 `configVersion`，执行验证：

```bash
curl -fsS -X POST \
  "${SERVE_API}/api/api-pull-tasks/<taskId>/validate" \
  -H 'Content-Type: application/json' \
  --data-binary '{"configVersion":<当前版本>}'
```

验证返回 `valid=true` 后恢复任务：

```bash
curl -fsS -X POST \
  "${SERVE_API}/api/api-pull-tasks/<taskId>/resume" \
  -H 'Content-Type: application/json' \
  --data-binary '{"configVersion":<当前版本>}'
```

上线时先启用告警任务，核对数量、事件时间和字段后，再启用流量日志任务。

常见返回说明：

| 返回内容 | 处理方式 |
| --- | --- |
| `valid=false` | 查看 `checks` 中状态为 `FAIL` 的项目，处理后重新验证 |
| `CONFIG_VERSION_CONFLICT` | 重新查询任务，使用最新的 `configVersion` |
| `enabled=true` | 任务已经开始调度 |
| `recordsFetched=recordsDurable` | 本次拉取的数据已经写入 WAL |
| `recordsQuarantined>0` | 有数据被隔离，需要查看服务日志 |

查询任务进度：

```bash
curl -fsS "${SERVE_API}/api/api-pull-tasks/<taskId>/runtime"
```

`committedWindowEnd` 表示已经完整处理到的时间。它持续向后变化，说明任务正在推进。