nanChen/ai-security-xdr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
261f1d38e940e87032a6bc7e38aebf2cf20263ee
ai-security-xdr/haobang-security-dm/upgrade-doc/v6/api/README.md
T
王绍宏 261f1d38e9 feat(syslog-serve): 完善微步全量拉取、探针归属控制及诊断接口 
- 按 DEVICE_DEVICE.DEVICE_COLLECT_ID 过滤 API 拉取任务
- 仅允许与 APP_SERVICE_DEVICE_COLLECT_ID 匹配的节点执行任务
- 在任务扫描和数据库租约获取阶段双重校验设备归属
- 设备迁移后原节点不执行 HTTP 请求且不推进 NEXT_RUN_AT
- 保留数据库租约，避免同一探针的多实例重复拉取

- 微步 searchBySql 改为全量逐条日志查询
- 移除 net_data_type=attack/risk 固定过滤
- 支持采集 attack、action、risk 并原样写入 WAL/Kafka
- 保留空 sql、完整字段和时间窗口查询

- 新增微步原始查询诊断接口
- 支持自定义 size、page、pageSize、cur_page 等查询字段
- 复用任务绑定的地址、凭据、TLS 和超时配置
- 诊断查询不写 WAL/Kafka、不推进 checkpoint
- 响应隐藏 API Key、Secret、签名和认证字段

- 更新启动版本标识为 WEIBU_DIAGNOSTIC_V20260917_66
- 更新 v6 部署、验证和 curl 调用文档
- Docker 基础镜像调整为 eclipse-temurin:8-jre
- 补充探针归属、全量查询、诊断透传和状态隔离测试

测试：
- JDK 8
- Tests run: 165
- Failures: 0
- Errors: 0
- Skipped: 2
- git diff --check 通过
2026-09-17 22:25:40 +08:00

6.7 KiB
Raw Blame History

v6 API 现场操作

API 相关升级只看本页。示例设备：deviceId=40、IP=10.56.171.164、微步 TDP。 生产环境不映射管理端口，所有 API 命令都通过容器执行：

  • syslog-serve-dm：8189
  • syslog-consumer-rule-dm：8289

1. 发布顺序

  1. 先按 upgrade-doc/v6/README.md 执行 3 个数据库脚本。

  2. 确认启动配置：

    SYSLOG_SERVER_ENABLED=true
DEVICE_API_ENABLED=true
DEVICE_API_TLS_VERIFY_ENABLED=false
DEVICE_API_HOST_ALLOWLIST_ENABLED=false

  3. 更换并启动新 JAR。新版 JAR 不能在数据库字段升级前启动。

  4. 检查启动日志：

    docker logs syslog-serve-dm 2>&1 | grep '\[SYSLOG_BUILD_READY\]' | tail -n 1

    必须看到 codeRevision=WEIBU_DIAGNOSTIC_V20260917_66、apiPullEnabled=true，并确认 deviceCollectId 与设备 40 的 DEVICE_DEVICE.DEVICE_COLLECT_ID 一致。内网默认 apiTlsVerifyEnabled=false。

2. 配置微步 API 任务

真实 Key/Secret 已保存在 weibu-40-credential.json，该文件必须按生产密钥管理。

chmod 600 upgrade-doc/v6/api/weibu-40-credential.json

docker exec -i syslog-serve-dm curl -fsS -X POST \
  'http://127.0.0.1:8189/syslogserve/api/api-pull-credentials' \
  -H 'Content-Type: application/json' \
  --data-binary '@-' \
  < upgrade-doc/v6/api/weibu-40-credential.json

如果凭据已存在，不要重复创建。任务已存在时也直接复用。首次接入时，v6 目录已提供设备 40 的完整任务 JSON；执行前只把首次采集时间设为服务器当前时间减 2 分钟：

INITIAL_START_TIME=$(date -d '2 minutes ago' --iso-8601=seconds)
sed "s|__INITIAL_START_TIME__|${INITIAL_START_TIME}|" \
  upgrade-doc/v6/api/weibu-40-task.json \
  > /tmp/weibu-40-task.json

执行前检查生成结果：

cat /tmp/weibu-40-task.json

必须确认 deviceId=40、baseUrl=https://10.56.171.164，且 initialStartTime 已经是真实时间，不再包含 __INITIAL_START_TIME__。

docker exec -i syslog-serve-dm curl -fsS -X POST \
  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks' \
  -H 'Content-Type: application/json' \
  --data-binary '@-' \
  < /tmp/weibu-40-task.json

记录返回的 taskId 和 configVersion。任务创建后默认暂停，先验证：

docker exec syslog-serve-dm curl -fsS -X POST \
  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/<TASK_ID>/validate' \
  -H 'Content-Type: application/json' \
  -d '{"configVersion":<CONFIG_VERSION>}'

所有检查为 PASS 后，先在管理系统中给设备 40 关联能解析微步单条 JSON 的泛化规则，然后恢复任务：

docker exec syslog-serve-dm curl -fsS -X POST \
  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/<TASK_ID>/resume' \
  -H 'Content-Type: application/json' \
  -d '{"configVersion":<CONFIG_VERSION>}'

3. 将设备 40 设为仅 API 采集

禁止直接改数据库，必须调用 API，让三层设备缓存同时失效。

docker exec syslog-serve-dm curl -fsS -X PUT \
  'http://127.0.0.1:8189/syslogserve/api/devices/40/collection-mode' \
  -H 'Content-Type: application/json' \
  -d '{"collectionMode":"API_ONLY"}'

docker exec syslog-serve-dm curl -fsS \
  'http://127.0.0.1:8189/syslogserve/api/devices/40'

GET 必须返回 collectionMode=API_ONLY。此后 10.56.171.164 的 TCP/UDP Syslog 被丢弃，API 任务继续运行。

4. 微步原始查询诊断

诊断接口复用任务中的设备地址、凭据、TLS 和超时配置，只把请求 JSON 原样发送给微步。 它不会写入 WAL/Kafka，不会推进 checkpoint，也不会在响应中返回 API Key、Secret 或签名 URL。

查询最近 10 分钟，单次最多请求 1000 条：

TIME_TO=$(date +%s)
TIME_FROM=$((TIME_TO - 600))

docker exec syslog-serve-dm curl -fsS -X POST \
  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/21/diagnostics/weibu-query' \
  -H 'Content-Type: application/json' \
  -d "{\"time_from\":${TIME_FROM},\"time_to\":${TIME_TO},\"sql\":\"\",\"assets_group\":[],\"columns\":[],\"size\":1000}"

请求体不会限制微步字段，因此可以试验现场版本的页码和页大小字段。例如：

docker exec syslog-serve-dm curl -fsS -X POST \
  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/21/diagnostics/weibu-query' \
  -H 'Content-Type: application/json' \
  -d "{\"time_from\":${TIME_FROM},\"time_to\":${TIME_TO},\"sql\":\"\",\"assets_group\":[],\"columns\":[],\"page\":2,\"pageSize\":100,\"size\":100}"

微步当前文档只明确描述了查询条件，现场已有脚本确认 size 可用，但未确认真正的页码字段。 诊断接口会原样传递 page、pageSize、cur_page、page_size 等字段；应通过不同页返回的 response.data.data 和 response.data.total 判断设备是否接受，不能仅凭 HTTP 200 认定分页生效。

5. 验收

docker exec syslog-serve-dm curl -fsS \
  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/<TASK_ID>/runtime'
docker exec syslog-serve-dm curl -fsS \
  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/<TASK_ID>/runs?page=1&pageSize=5'

必须确认：

  • health=HEALTHY，最新 SCHEDULED 为 SUCCESS，HTTP 状态为 200。
  • checkpoint 持续推进；设备当时无日志时 recordsFetched=0 也是正常成功。
  • Kafka 中每条消息是一条微步 JSON，下游按设备 40 关联的泛化规则标准化。
  • 来自 10.56.171.164 的 Syslog 不进入 WAL/Kafka，其他默认 BOTH 设备不受影响。

6. 缓存清理

# syslog-serve：指定设备 / 全部设备
docker exec syslog-serve-dm curl -fsS -X DELETE \
  'http://127.0.0.1:8189/syslogserve/api/devices/40/cache'
docker exec syslog-serve-dm curl -fsS -X DELETE \
  'http://127.0.0.1:8189/syslogserve/api/devices/cache'

# syslog-consumer-rule：指定设备规则 / 全部规则
docker exec syslog-consumer-rule-dm curl -fsS -X DELETE \
  'http://127.0.0.1:8289/xdrrule/api/syslog/normalization/cache/devices/40'
docker exec syslog-consumer-rule-dm curl -fsS -X DELETE \
  'http://127.0.0.1:8289/xdrrule/api/syslog/normalization/cache'

规则缓存清理会通知所有正常订阅 Redis 消息的 syslog-consumer-rule 实例。不要使用旧的 DELETE /api/cache/all。

7. 快速回退

  1. 暂停微步 API 任务。

  2. 将设备改回 BOTH：

    docker exec syslog-serve-dm curl -fsS -X PUT \
  'http://127.0.0.1:8189/syslogserve/api/devices/40/collection-mode' \
  -H 'Content-Type: application/json' \
  -d '{"collectionMode":"BOTH"}'

  3. 恢复原泛化规则关联和旧 JAR。不删除 COLLECTION_MODE 字段，不删除任务、凭据或 checkpoint。

Reference in New Issue View Git Blame Copy Permalink