nanChen/ai-security-xdr

Fork 0

Files

T

nanChen 037cca32dd 新增syslog-collector-api 采集模块，通过api 方式采集天眼、微步的设备日志。

2026-09-07 15:34:17 +08:00

34 KiB

Raw Permalink Blame History

智能安全运营平台设备API接口数据采集功能模块开发设计说明文档版本：V1.0.0 文档密级：内部 2026年08月24日文档修订记录

[TABLE] | 版本号 | 修订日期 | 修订内容 | 修订人 | | V1.0.0 | 2026-08-24 | 初始版本，创建文档 | | | | | | | | | | | | [/TABLE]

1 概述

1.1 编写目的本文档描述智能安全运营平台"设备API接口数据采集功能模块"的需求与开发设计，涵盖从奇安信天眼分析平台、微步在线威胁感知平台、深信服XDR平台三类安全设备通过API接口定时采集安全数据（Web访问日志、告警日志、攻击流量、日志流量）的功能需求、非功能性需求、接口规范及详细设计方案。本文档的预期读者为：项目开发人员、系统测试人员、项目管理人员及运维人员。 1.2 系统架构设备API接口数据采集功能模块部署于智能安全运营平台侧，采用"定时拉取—字段映射—标准化数据格式—写入Kafka"的处理模式，整体数据流如下： ┌─────────┐ ┌─────────┐ ┌─────────┐ │ 天眼平台 │ │ 微步平台 │ │ 深信服XDR│ └────┬────┘ └────┬────┘ └─── ─┬────┘ │ HTTPS API │ │ └──────┬───────┴──────┬──────┘ ▼ ▼ ┌────────────────────────────┐ │ 设备API数据采集模块 │ │ (定时调度/认证/分页/映射) │ └────────────┬───────────────┘ ▼ ┌────────────┐ ┌──────┐ │ Kafka │───▶│ Redis │(断点/Token缓存) └─────┬──────┘ └──────┘ ▼ syslog-consumer-rule 消费处理(泛化规则) 采集源汇总：共3个设备平台、4种数据类型、2种认证机制（免密登录/HMAC签名）、3种API协议。 1.3 适用范围本文档适用于智能安全运营平台设备API接口数据采集功能模块的设计、开发、测试与验收工作。 1.4 术语与缩略语

1.5 参考文档

[TABLE] | 序号 | 文档名称 | 版本 | | 1 | 奇安信网神威胁监测与分析系统（天眼-分析平台）V4.0.12.0-API调用手册V1.0 | V1.0.0 | | 2 | 微步在线API配置文档 | 最新 | | 3 | 深信服XDR开放API认证方案及接口开放列表 | 最新 | | 4 | 智能安全运营平台系统架构设计文档 | V1.0.0 | [/TABLE]

2 功能需求

2.1 数据采集设备API接口数据采集模块需要从以下安全设备平台定时拉取安全数据，采集的数据类型主要包括Web访问日志、告警日志、攻击流量和日志流量。 2.1.1 天眼分析平台API接口

2.1.1.1 功能需求

通过天眼分析平台API接口，定时采集以下两类数据： • Web访问日志（skyeye-weblog）：记录外部对内网的HTTP/HTTPS访问行为，包括源/目的IP、端口、URI、Host、Method、状态码、Cookie、Referer等。 • 告警日志（alarm_collection等）：记录各类安全告警事件，包括规则告警、威胁情报告警、蜜罐告警、WebShell检测、Web攻击检测、IDS入侵检测等。

2.1.1.2 认证机制

天眼分析平台采用免密登录（OAuth式）认证，流程如下：

获取login_key（系统管理-账号管理）
生成client_id = SHA256("mNSLP9UJCtBHtegjDPJnK3v" + "|" + login_key)
生成client_secret = SHA256("3460681205014671737" + "|" + login_key)
生成timestamp（10位Unix时间戳，与平台时差不能超过10分钟）
生成X-Authorization = SHA256(JSON({"client_id":..,"username":"tapadmin"}) + timestamp + client_secret)
POST /skyeye/v1/admin/auth 获取access_token
GET /skyeye/v1/admin/auth?token=... 提取csrf_token和cookies
携带csrf_token + cookies请求业务数据接口注意：csrf_token有效期约30分钟，需在每次采集周期前重新认证；cookies需在后续请求Header中携带，格式为 key1=value1;key2=value2;。

2.1.1.3 相关API接口说明

（1）Web访问日志查询接口

请求参数：

响应字段（Web访问日志核心数据字段）：

（2）告警日志查询接口

告警日志数据字段（核心字段）：

（3）告警列表查询接口

核心请求参数：start_time、end_time、threat_type、hazard_level（0低危/1中危/2高危/3危急）、host_state（攻击结果）、status（处理状态）、offset（页码）、limit（每页条数）等。 2.1.2 微步API接口

2.1.2.1 功能需求

通过微步在线威胁感知平台API接口，定时采集以下两类数据： • 攻击流量（net_data_type: ["attack"]）：检测到的攻击行为日志，包括威胁名称、攻击结果、严重级别、攻击阶段、源/目的IP端口、HTTP详情、IOC等。 • 日志流量（net_data_type: ["info"]）：网络流量日志记录，用于行为分析和审计。

2.1.2.2 认证机制

微步平台采用HMAC-SHA256签名认证，流程如下：

获取当前时间戳 Timestamp（10位Unix秒级时间戳）
拼接签名数据：SignData = ApiKey + Timestamp
计算签名：Sign = Base64.encodeBase64URLSafeString(HmacSHA256(SignData, Secret))
构造请求URL： POST https://domain/api/v1/log/searchBySql?api_key=&auth_timestamp=&sign= 说明：Base64 URL Safe编码将"+"替换为"-"、"/"替换为"_"并去除末尾"="，防止URL参数解析不完整；请求方时间与服务端时间差须在10分钟以内，否则签名过期。

2.1.2.3 相关API接口说明

请求Body参数：

[TABLE] | 参数名 | 类型 | 必填 | 说明 | 示例 | | net_data_type | Array | 是 | 数据类型：attack-攻击流量，info-日志流量 | ["attack"] | | time_from | Integer | 是 | 开始时间戳（秒级） | 1787500800 | | time_to | Integer | 是 | 截止时间戳（秒级） | 1787587199 | | assets_group | Array | 否 | 业务组ID列表 | [] | | search_connection | Boolean | 否 | 是否搜索关联连接 | false | | sql | String | 否 | 查询SQL条件 | (threat.level IN ('attack','action')) | | columns | Array | 否 | 查询字段列表（label+value对） | [{"label":"告警时间","value":"time"}] | | asc | Boolean | 否 | 是否升序排列 | false | | page | Object | 否 | 分页参数：cur_page, page_size, sort | {"cur_page":1,"page_size":100} | [/TABLE]

查询字段列表（columns）：

响应数据结构（示例）： { "data": { "data": [ { "data": "URL或域名", "index": "tdp-2026-08-24", "src_tag": "外", "dest_tag": "内", "ip_reputation_zh": ["网关"], "assets": {"group_id":1, "group_name":"互联网应用", "name":["蜜罐系统"], "id":36}, "machine": "172.20.34.33", "time": 1787545680, "threat": { "severity": 1, "result": "unknown", "phase": "exploit", "level": "attack", "name": "路径穿越攻击", "tag": ["Mitre: T1190..."], "type": "exploit", "is_apt": 0, "status": 0 }, "id": "J7UGMqABp3egYciwfG0Z", "net": { "src_ip": "119.132.173.119", "src_port": 55105, "dest_ip": "172.20.34.33", "dest_port": 80, "type": "http", "http": {"method":"POST", "reqs_header":"Host: ...", "reqs_body":"...", "resp_header":"...", "resp_body":"..."} }, "hit_whitelist": 0, "direction": "in" } ] }, "response_code": 0, "verbose_msg": "OK" } 2.1.3 XDR OpenAPI接口（深信服）

2.1.3.1 功能需求

通过深信服XDR平台开放API接口，采集告警事件等安全数据，作为天眼和微步数据的补充。

2.1.3.2 认证机制

深信服XDR平台采用AK/SK HMAC-SHA256签名认证，流程如下： • 从XDR平台"配置管理-系统设置-开放性-联动码管理"页面获取联动码（authCode）。 • 联动码解码获取AK/SK（AES-CBC解密）。 • 构造请求，生成签名头；签名后直接发送请求，不可修改任何参数。签名算法说明：

[TABLE] | 步骤 | 说明 | | 联动码解码 | Hex解码 -> 按"|"分割为14段 -> 通过SHA256计算AES密钥 -> AES-CBC解密第10段得到AK，第11段得到SK | | 添加公共头 | sdk-content-type: application/json; sdk-host: {host}; sign-date: {UTC时间(yyyyMMdd'T'HHmmssZZ)} | | 构造规范串 | METHOD + "\n" + URI(转义+末尾加/) + "\n" + QueryString(排序) + "\n" + Headers(排序key:value\n) + SignedHeaders(;) + "\n" + PayloadHash(SHA256(payload去空格+排序)) | | 计算签名 | stringToSign = "HMAC-SHA256\n" + signDate + "\n" + SHA256(规范串)；signature = HMAC-SHA256(stringToSign, SK) -> Hex编码 | | 构造Authorization | algorithm=HMAC-SHA256, Access={AK}, SignedHeaders={排序后的header keys}, Signature={signature} | [/TABLE]

XDR平台信息：

3 非功能性需求

4 假设与约束条件

4.1 时间周期

5 开发设计

5.1 数据采集处理流程数据采集处理主流程（9步）：定时触发 -> 认证管理 -> 构造请求 -> 调用API -> 解析响应 -> 字段映射（标准化数据格式） -> 写入Kafka（指定topic） -> 更新断点 -> 记录日志 5.1.1 认证管理流程

5.1.2 分页拉取流程 int page = 1; int pageSize = 100; boolean hasMore = true; while (hasMore) { params.put("offset", page); params.put("limit", pageSize); JSONObject response = httpClient.get(apiUrl, params, headers); JSONArray items = response.getJSONObject("data").getJSONArray("items"); int total = response.getJSONObject("data").getInt("total"); for (Object item : items) { StandardMessage msg = fieldMapper.map((JSONObject) item, deviceType); kafkaTemplate.send(topic, JSON.toJSONString(msg)); } hasMore = (page * pageSize) < total; page++; Thread.sleep(rateLimitInterval); // 限流控制（微步50/s） } 5.1.3 断点续传机制使用Redis记录每个设备+数据类型的最后采集时间戳，确保重启后不丢数据： // Redis Key设计 key: device:api:last_collect_time:{deviceIp}:{deviceType}:{dataType} value: 1787534756117 (最后成功采集的数据时间戳) TTL: 7天 (过期自动清理) // 采集时间窗口计算 long lastTime = redis.get(key); // 上次采集结束时间 long endTime = System.currentTimeMillis(); // 当前时间 long startTime = lastTime - 60000; // 回退1分钟，防止边界丢数据 5.2 设备API接口设计 5.2.1 统一采集器接口 /**

设备数据采集器统一接口
所有设备采集器实现此接口，由调度器统一管理 / public interface DeviceDataCollector { /* 获取设备类型 / String getDeviceType(); /* 认证/获取访问凭证 / void authenticate() throws CollectorException; /*
- 采集数据
- @param dataType 数据类型（weblog/alarm/attack/info等）
- @param startTime 开始时间
- @param endTime 结束时间
- @return 采集结果统计 / CollectResult collect(String dataType, long startTime, long endTime) throws CollectorException; /* 检查认证是否有效 / boolean isAuthenticated(); } 5.2.2 天眼采集器设计 @Slf4j @Component public class TianyanDataCollector implements DeviceDataCollector { @Value("${device.tianyan.host}") private String host; @Value("${device.tianyan.loginKey}") private String loginKey; @Value("${device.tianyan.branchId}") private String branchId; private static final String CLIENT_ID_SEED = "mNSLP9UJCtBHtegjDPJnK3v"; private static final String CLIENT_SECRET_SEED = "3460681205014671737"; private static final String AUTH_URI = "/skyeye/v1/admin/auth"; private static final String LOG_SEARCH_URI = "/skyeye/v1/analysis/log-search/list"; private static final String CSRF_TOKEN_CACHE_KEY = "device:tianyan:csrf_token"; private static final String COOKIES_CACHE_KEY = "device:tianyan:cookies"; private static final long CSRF_TOKEN_TTL = 25 * 60; // 25分钟 @Override public void authenticate() throws CollectorException { // 1. 检查Redis缓存 2. 生成client_id/client_secret // 3. 生成X-Authorization签名 4. POST获取access_token // 5. GET提取csrf_token+cookies 6. 缓存到Redis } @Override public CollectResult collect(String dataType, long startTime, long endTime) { // weblog: index=skyeye-weblog, category=skyeye, mode=fast_model // alarm : index=alarm_collection,... category=event, mode=advance_model // 分页拉取并写入Kafka } } 5.2.3 微步采集器设计 @Slf4j @Component public class WeibuDataCollector implements DeviceDataCollector { @Value("${device.weibu.host}") private String host; @Value("${device.weibu.apiKey}") private String apiKey; @Value("${device.weibu.secret}") private String secret; private static final String SEARCH_BY_SQL_URI = "/api/v1/log/searchBySql"; /*
- 生成微步API签名:
- Sign = Base64.encodeBase64URLSafeString(HmacSHA256(ApiKey+Timestamp, Secret)) / private String generateSign(long timestamp) { String signData = apiKey + timestamp; byte[] hmacBytes = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, secret).hmac(signData); return Base64.encodeBase64URLSafeString(hmacBytes); } @Override public CollectResult collect(String dataType, long startTime, long endTime) { long timestamp = System.currentTimeMillis() / 1000; String sign = generateSign(timestamp); String url = host + SEARCH_BY_SQL_URI + "?api_key=" + apiKey + "&auth_timestamp=" + timestamp + "&sign=" + sign; // 构造Body: net_data_type/time_from/time_to/sql/columns/分页参数 // 分页拉取... } } 5.2.4 深信服XDR采集器设计（暂缓） @Slf4j @Component public class XdrDataCollector implements DeviceDataCollector { @Value("${device.xdr.host}") private String host; @Value("${device.xdr.authCode}") private String authCode; private String ak; private String sk; @PostConstruct public void init() { String[] akSk = decodeAuthCode(authCode); this.ak = akSk[0]; this.sk = akSk[1]; } /* 对请求进行HMAC-SHA256签名 */ private HttpRequest signRequest(HttpRequest request) { String signDate = DateFormatUtils.formatUTC(new Date(), "yyyyMMdd'T'HHmmssZZ"); request.header("sdk-content-type", "application/json"); request.header("sdk-host", request.uri().getHost()); request.header("sign-date", signDate); String canonicalStr = buildCanonicalStr(request); String canonicalHash = Hex.encodeHexString(DigestUtils.sha256(canonicalStr), false); String stringToSign = "HMAC-SHA256\n" + signDate + "\n" + canonicalHash; String signature = Hex.encodeHexString( new HmacUtils(HmacAlgorithms.HMAC_SHA_256, sk).hmac(stringToSign), false); String authorization = String.format( "algorithm=HMAC-SHA256, Access=%s, SignedHeaders=%s, Signature=%s", ak, getSignedHeaders(request), signature); request.header("Authorization", authorization); return request; } } 5.3 数据表设计 5.3.1 设备API采集配置表 -- 达梦DM8 DDL CREATE TABLE device_api_config ( id BIGINT IDENTITY(1,1) PRIMARY KEY, -- 主键，自增 device_id INT, -- 设备ID，关联 device_device.id device_type VARCHAR(50) NOT NULL, -- 设备类型: tianyan/weibu/xdr device_name VARCHAR(100) NOT NULL, -- 设备名称 device_ip VARCHAR(200) NOT NULL, -- 设备IP地址 host_api VARCHAR(200) NOT NULL, -- 设备API地址 auth_config TEXT, -- 认证配置JSON data_types VARCHAR(500) NOT NULL, -- 数据类型: weblog,alarm / attack,info collect_interval_sec INT DEFAULT 300, -- 采集间隔（秒） enabled INT DEFAULT 1, -- 是否启用: 0-禁用, 1-启用 remark VARCHAR(500), -- 备注 create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); COMMENT ON TABLE device_api_config IS '设备API采集配置表'; 5.3.2 采集任务执行日志表 CREATE TABLE device_api_collect_log ( id BIGINT IDENTITY(1,1) PRIMARY KEY, -- 主键，自增 device_id INT NOT NULL, -- 设备ID，关联 device_device.id device_type VARCHAR(50) NOT NULL, -- 设备类型 data_type VARCHAR(50) NOT NULL, -- 数据类型 start_time TIMESTAMP NOT NULL, -- 采集窗口开始时间 end_time TIMESTAMP NOT NULL, -- 采集窗口结束时间 total_count INT DEFAULT 0, -- 采集记录总数 success_count INT DEFAULT 0, -- 成功写入数 fail_count INT DEFAULT 0, -- 失败数 cost_ms BIGINT DEFAULT 0, -- 耗时（毫秒） status VARCHAR(20) NOT NULL, -- 状态: SUCCESS/FAIL error_msg TEXT, -- 错误信息 create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); COMMENT ON TABLE device_api_collect_log IS '设备API采集执行日志'; 5.3.3 标准化消息格式（Kafka消息体） [receive_time=20260825143015235 device_id=1001 device_name=天眼01 vendor=天眼, data_type=json device_collect_id=1 eventId=20260822-f47ac10b-58cc-4372-a567-0e02b2c3d479] { "deviceType": "tianyan", "dataType": "alarm", "collectTime": 1787534756117, "rawData": { ... 各设备原始JSON ... } } 5.4 核心类设计

5.5 定时任务设计 @Slf4j @Component public class CollectScheduler { @Autowired private List collectors; @Autowired private DeviceApiConfigService configService; @Autowired private RedisTemplate<String, String> redisTemplate; /** 主采集任务 - 每5分钟执行 */ @Scheduled(fixedDelayString = "${device.collect.interval:300000}") public void scheduleCollect() { List configs = configService.listEnabled(); for (DeviceApiConfig config : configs) { for (String dataType : config.getDataTypes().split(",")) { try { collectForDevice(config, dataType.trim()); } catch (Exception e) { log.error("采集失败: {}-{}", config.getDeviceType(), dataType, e); } } } } private void collectForDevice(DeviceApiConfig config, String dataType) { // 1. 查找采集器 2. 认证检查 // 3. 计算时间窗口（上次时间-1分钟 ~ 当前时间） // 4. 采集 5. 更新断点 6. 记录日志 } } 5.6 配置设计

application.yml 设备API采集配置

device: collect: interval: 300000 # 采集间隔(毫秒), 默认5分钟 retry: max-attempts: 3 # 最大重试次数 initial-delay: 5000 # 初始重试延迟(毫秒) multiplier: 2.0 # 重试延迟倍数 kafka: topic: device-api-collect tianyan: # 天眼分析平台 host: https://10.56.171.xxx:443 login-key: ${TIANYAN_LOGIN_KEY} branch-id: QbJK/sLHi data-types: weblog,alarm page-size: 100 weibu: # 微步在线 host: https://10.56.171.164 api-key: ${WEIBU_API_KEY} secret: ${WEIBU_SECRET} data-types: attack,info rate-limit: 50 # 每秒最大请求数 page-size: 100 xdr: # 深信服XDR host: https://10.56.171.157 auth-code: ${XDR_AUTH_CODE} api-base: /api/openapi/ data-types: alarm,asset page-size: 1000

6开发计划

6.1 任务计划总工期 2周（2026-08-25至2026-9-3，共10个工作日），设置5个里程碑：

[TABLE] | 里程碑 | 名称 | 计划完成日期 | 达成标准（出口准则） | | M1 | 需求与设计基线确认 | 2026-08-25 | 设计说明评审通过并基线化；API账号凭证（天眼login_key、微步ApiKey/Secret、XDR联动码）全部到位 | | M2 | 采集框架与环境就绪 | 2026-08-27 | 模块骨架搭建完成；两张DM8表建表并通过验证；Kafka/Redis连通；统一接口与调度器编译通过 | | M3 | 天眼采集器完成 | 2026-08-28 | 免密登录认证调通；weblog与alarm两类数据可稳定拉取并写入Kafka；断点续传验证通过 | | M4 | 微步与XDR采集器完成 | 2026-08-31 | 微步签名调通、attack/info双类型采集正常；XDR联动码解码与签名调通、数据可拉取 | | M5 | 联调测试与上线 | 2026-09-04 | 7×24小时连续运行无丢数；重试/断点/限流场景测试通过；测试报告与部署方案归档 | [/TABLE]

6.2任务分解与进度安排 6.2.1 阶段一：需求确认与基础环境准备开发（第1周，08-25~08-27）

6.2.3 阶段二：天眼、微步采集器开发（第1-2周8.28-8.31）

6.2.5 阶段三：系统调试与上线（第2周，09.01~09-04）

6.2.6 人员分工与资源需求

[TABLE] | 角色 | 人数 | 主要职责 | 投入占比 | | 开发负责人 | 1 | 设计评审、任务分派、进度与质量把控、里程碑验收 | 30% | | 后端开发（Java） | 1 | 采集框架、三个采集器、调度与断点、字段映射编码实现及自测 | 100% | | 测试工程师 | 1 | 测试用例编写、集成与异常场景测试、测试报告 | 100%（1周） | | 运维工程师 | 1 | 申请网络策略开通（3台采集服务器->安全设备）、环境准备、Docker部署、监控接入 | 20% | | 厂商接口支持 | 2 | 天眼/微步接口问题答疑、凭证发放（按需） | 按需 | [/TABLE]

7 附录

7.1天眼接口数据样例 7.2微步口数据样例

34 KiB Raw Permalink Blame History Unescape Escape