王绍宏
00c0a1fb7f
- 接入 NDRServer 告警和流量日志，支持凭据与任务管理 - 支持分页拉取、窗口拆分、调度优先级及 WAL 持久化后推进断点 - 增加迟到告警规则重放，优化多条泛化规则选择和事件时间处理 - 补充回归测试、数据库升级脚本及部署文档
155 lines
5.2 KiB
Markdown
155 lines
5.2 KiB
Markdown
# 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` 表示已经完整处理到的时间。它持续向后变化，说明任务正在推进。
|