694 lines
34 KiB
Markdown
694 lines
34 KiB
Markdown
智能安全运营平台
|
||
设备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 术语与缩略语
|
||
|
||
[TABLE]
|
||
| 术语/缩略语 | 全称 | 说明 |
|
||
| 天眼 | 奇安信威胁监测与分析系统 | 奇安信天眼分析平台，提供日志检索与告警API |
|
||
| 微步 | 微步在线威胁感知平台(TDP) | 提供攻击流量与日志流量查询API |
|
||
| XDR | Extended Detection and Response | 深信服扩展检测与响应平台，提供开放API |
|
||
| csrf_token | Cross-Site Request Forgery Token | 天眼免密登录后获取的业务请求令牌 |
|
||
| AK/SK | Access Key / Secret Key | XDR联动码解码获得的访问密钥对 |
|
||
| HMAC-SHA256 | Hash-based Message Authentication Code | 微步与XDR采用的请求签名算法 |
|
||
| IOC | Indicators of Compromise | 失陷威胁指标 |
|
||
| ATT&CK | Adversarial Tactics, Techniques & Common Knowledge | 攻击战术技术知识库 |
|
||
[/TABLE]
|
||
|
||
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式）认证，流程如下：
|
||
1. 获取login_key（系统管理-账号管理）
|
||
2. 生成client_id = SHA256("mNSLP9UJCtBHtegjDPJnK3v" + "|" + login_key)
|
||
3. 生成client_secret = SHA256("3460681205014671737" + "|" + login_key)
|
||
4. 生成timestamp（10位Unix时间戳，与平台时差不能超过10分钟）
|
||
5. 生成X-Authorization = SHA256(JSON({"client_id":..,"username":"tapadmin"}) + timestamp + client_secret)
|
||
6. POST /skyeye/v1/admin/auth 获取access_token
|
||
7. GET /skyeye/v1/admin/auth?token=... 提取csrf_token和cookies
|
||
8. 携带csrf_token + cookies请求业务数据接口
|
||
注意：csrf_token有效期约30分钟，需在每次采集周期前重新认证；cookies需在后续请求Header中携带，格式为 key1=value1;key2=value2;。
|
||
|
||
#### 2.1.1.3 相关API接口说明
|
||
（1）Web访问日志查询接口
|
||
|
||
[TABLE]
|
||
| 属性 | 说明 |
|
||
| 接口URL | /skyeye/v1/analysis/log-search/list |
|
||
| 请求协议 | HTTPS |
|
||
| 请求方法 | GET |
|
||
| 认证方式 | csrf_token + cookies（免密登录获取） |
|
||
| 数据格式 | JSON |
|
||
[/TABLE]
|
||
|
||
请求参数：
|
||
|
||
[TABLE]
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||
| branch_id | string | 是 | 级联单位ID | QbJK/sLHi |
|
||
| start_time | number | 是 | 开始时间（毫秒时间戳） | 1787534456117 |
|
||
| end_time | number | 是 | 结束时间（毫秒时间戳） | 1787534756117 |
|
||
| index | string | 是 | 索引名称（web日志固定为skyeye-weblog） | skyeye-weblog |
|
||
| category | string | 是 | 索引类别 | skyeye |
|
||
| offset | int | 是 | 页码，从1开始 | 1 |
|
||
| limit | int | 是 | 每页条数 | 100 |
|
||
| mode | string | 否 | 查询模式（fast_model快速查询） | fast_model |
|
||
| keyword | string | 否 | 关键词检索 | |
|
||
| csrf_token | string | 是 | 认证令牌（免密登录获取） | 8696f4a3f08fe4c48b310f269bd4adad |
|
||
| r | string | 否 | 随机数（防缓存） | 0.8929389461785662 |
|
||
[/TABLE]
|
||
|
||
响应字段（Web访问日志核心数据字段）：
|
||
|
||
[TABLE]
|
||
| 字段名 | 说明 |
|
||
| serial_num | 设备序列号 |
|
||
| access_time | 访问时间 |
|
||
| sip / dip | 源IP / 目的IP |
|
||
| sport / dport | 源端口 / 目的端口 |
|
||
| uri / uri.raw | 请求URI / 原始URI |
|
||
| host / host_raw | 主机域名 |
|
||
| method | HTTP方法（GET/POST等） |
|
||
| status | HTTP状态码 |
|
||
| agent | User-Agent |
|
||
| xff | X-Forwarded-For |
|
||
| data | 请求体数据 |
|
||
| content_type | Content-Type |
|
||
| setcookie / cookie / referer | Set-Cookie / Cookie / Referer |
|
||
| authorization | Authorization头 |
|
||
| device_ip | 设备IP |
|
||
| src_mac / dst_mac | 源MAC / 目的MAC |
|
||
| vlan_id | VLAN ID |
|
||
| sess_key | 会话Key |
|
||
| priv_info | 私有信息（产品类型等） |
|
||
| geo_sip.* / geo_dip.* | 源/目的IP地理位置（城市、国家、经纬度） |
|
||
| @timestamp | ES时间戳 |
|
||
| sipv6 / dipv6 | IPv6源/目的地址 |
|
||
| origin / accept_language | Origin / Accept-Language |
|
||
[/TABLE]
|
||
|
||
（2）告警日志查询接口
|
||
|
||
[TABLE]
|
||
| 属性 | 说明 |
|
||
| 接口URL | /skyeye/v1/analysis/log-search/list |
|
||
| 请求方法 | GET |
|
||
| 索引名称 | alarm_collection, skyeye-sandbox, sandbox_mail, alarm_honeypot, alarm_yunsuo, webids-webshell_dolog, webids-webattack_dolog, webids-ids_dolog, webids-ioc_dolog |
|
||
| 查询模式 | advance_model（高级模式） |
|
||
[/TABLE]
|
||
|
||
告警日志数据字段（核心字段）：
|
||
|
||
[TABLE]
|
||
| 字段名 | 说明 |
|
||
| rule_id / rule_name | 规则ID / 规则名称 |
|
||
| dolog_count | 告警次数 |
|
||
| severity | 严重级别 |
|
||
| rule_version | 规则版本 |
|
||
| sip / dip / sport / dport | 源/目的IP、端口 |
|
||
| method / host / uri | HTTP方法 / 主机 / URI |
|
||
| file_name / referer / agent / cookie / parameter | 文件名 / Referer / UA / Cookie / 参数 |
|
||
| req_header / req_body | 请求头 / 请求体 |
|
||
| rsp_status / rsp_content_length / rsp_content_type / rsp_header / rsp_body / rsp_body_len | 响应状态/长度/类型/头/体 |
|
||
| victim_type / attack_flag | 受害类型 / 攻击标识 |
|
||
| attacker / victim | 攻击者 / 受害者 |
|
||
| attack_type / attack_result | 攻击类型 / 攻击结果 |
|
||
| confidence | 置信度 |
|
||
| detail_info / solution | 详细信息 / 解决方案 |
|
||
| vuln_desc / vuln_harm / vuln_name / vuln_type | 漏洞描述/危害/名称/类型 |
|
||
| kill_chain / att_ck_all | 杀伤链 / ATT&CK |
|
||
| cve_id / bid_id / cwe_id / msb_id | CVE/BID/CWE/MSB编号 |
|
||
| webrules_tag / rule_labels | Web规则标签 |
|
||
| code_language / site_app | 代码语言 / 站点应用 |
|
||
| device_ip / vendor_id | 设备IP / 厂商ID |
|
||
[/TABLE]
|
||
|
||
（3）告警列表查询接口
|
||
|
||
[TABLE]
|
||
| 属性 | 说明 |
|
||
| 接口URL | /alarm/alarm/list |
|
||
| 请求方法 | GET |
|
||
| 认证方式 | csrf_token + cookies |
|
||
[/TABLE]
|
||
|
||
核心请求参数：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签名认证，流程如下：
|
||
1. 获取当前时间戳 Timestamp（10位Unix秒级时间戳）
|
||
2. 拼接签名数据：SignData = ApiKey + Timestamp
|
||
3. 计算签名：Sign = Base64.encodeBase64URLSafeString(HmacSHA256(SignData, Secret))
|
||
4. 构造请求URL：
|
||
POST https://domain/api/v1/log/searchBySql?api_key=<ApiKey>&auth_timestamp=<Timestamp>&sign=<Sign>
|
||
说明：Base64 URL Safe编码将"+"替换为"-"、"/"替换为"_"并去除末尾"="，防止URL参数解析不完整；请求方时间与服务端时间差须在10分钟以内，否则签名过期。
|
||
|
||
#### 2.1.2.3 相关API接口说明
|
||
|
||
[TABLE]
|
||
| 属性 | 说明 |
|
||
| 接口URL | /api/v1/log/searchBySql |
|
||
| 请求协议 | HTTPS |
|
||
| 请求方法 | POST |
|
||
| 频率限制 | 50次/秒 |
|
||
| 认证方式 | api_key + auth_timestamp + sign（HMAC-SHA256） |
|
||
| Content-Type | application/json |
|
||
[/TABLE]
|
||
|
||
请求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）：
|
||
|
||
[TABLE]
|
||
| 字段（value） | 中文名（label） | 说明 |
|
||
| time | 告警时间 | 事件发生时间（秒级时间戳） |
|
||
| threat.name | 威胁名称 | 如"路径穿越攻击"、"疑似冰蝎Webshell" |
|
||
| threat.result | 攻击结果 | success/failed/unknown |
|
||
| threat.severity | 严重级别 | 0:信息, 1:低, 2:中, 3:高, 4:严重 |
|
||
| threat.phase | 攻击阶段 | 如exploit, post_exploit |
|
||
| threat.type | 威胁类型 | 如exploit, virus, c2 |
|
||
| threat.level | 威胁分类 | attack-攻击, action-事件, risk-风险 |
|
||
| threat.ioc | IOC | 威胁指标 |
|
||
| threat.is_apt | 是否APT | 0:否, 1:是 |
|
||
| threat.tag | 威胁标签 | Mitre ATT&CK标签等 |
|
||
| threat.status | 处理状态 | 处理状态标识 |
|
||
| machine | 告警主机 | 受影响主机IP |
|
||
| net.src_ip / net.src_port | 源IP / 源端口 | 攻击源地址与端口 |
|
||
| net.dest_ip / net.dest_port | 目的IP / 目的端口 | 目标地址与端口 |
|
||
| net.type | 协议 | 应用层协议（http等） |
|
||
| net.http.method / status | HTTP方法 / 状态码 | GET/POST等 / 响应状态码 |
|
||
| net.http.reqs_header / reqs_body | 请求头 / 请求体 | HTTP请求信息 |
|
||
| net.http.resp_header / resp_body | 响应头 / 响应体 | HTTP响应信息 |
|
||
| data | URL/域名 | 告警主体数据 |
|
||
| assets.name / assets.group_name | 资产名称 / 业务组 | 受影响资产信息 |
|
||
| direction | 告警方向 | in:外部攻击, out:失陷破坏, lateral:内网渗透 |
|
||
| src_tag / dest_tag | 来源/目的标签 | 内/外 |
|
||
| ip_reputation / ip_reputation_zh | IP信誉 | IP信誉标签（英文/中文） |
|
||
| hit_whitelist | 命中白名单 | 0:未命中, 1:命中 |
|
||
[/TABLE]
|
||
|
||
响应数据结构（示例）：
|
||
{
|
||
"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平台信息：
|
||
|
||
[TABLE]
|
||
| 属性 | 值 |
|
||
| 平台地址 | https://10.56.171.157/api/openapi/ |
|
||
| API Token | dTTQ8esIvaZOETpT4NWX |
|
||
| 接口示例 | /api/xdr/v1/assets/list（资产列表）、/api/xdr/v1/assets/department（部门资产） |
|
||
| 签名依赖库 | commons-codec（Hex/HmacUtils/DigestUtils）、Spring HttpHeaders |
|
||
[/TABLE]
|
||
|
||
|
||
# 3 非功能性需求
|
||
|
||
[TABLE]
|
||
| 需求项 | 指标 | 说明 |
|
||
| 性能 | 采集延迟 | 数据采集周期为5分钟，从设备API获取到数据写入Kafka的延迟不超过30秒 |
|
||
| 吞吐量 | 处理能力 | 单次采集批量处理1000条记录，支持多设备并行采集 |
|
||
| 可靠性 | 容错机制 | API调用失败自动重试3次（间隔递增：5s/10s/15s），重试失败记录错误日志并跳过当前批次 |
|
||
| 可靠性 | 断点续传 | 记录每批次最后采集时间戳，重启后从上次位置继续采集，不丢数据 |
|
||
| 可用性 | 认证缓存 | csrf_token（天眼）和AK/SK签名缓存于Redis，避免频繁认证 |
|
||
| 安全性 | 凭证管理 | login_key、ApiKey、Secret、authCode等敏感信息加密存储于配置文件，不记录在日志中 |
|
||
| 安全性 | HTTPS | 所有设备API调用使用HTTPS协议，关闭SSL证书校验（设备使用自签证书） |
|
||
| 可扩展性 | 设备适配 | 采用策略模式，新增设备类型只需实现统一的DataCollector接口，无需修改调度逻辑 |
|
||
| 可维护性 | 配置化 | 设备地址、认证信息、采集间隔、数据类型等全部通过application.yml配置，支持热刷新 |
|
||
| 采集监控 | 采集统计 | 记录每次采集的设备名、数据类型、采集条数、耗时、成功/失败状态，写入采集日志表 |
|
||
[/TABLE]
|
||
|
||
|
||
# 4 假设与约束条件
|
||
4.1 时间周期
|
||
|
||
[TABLE]
|
||
| 约束项 | 约束值 | 说明 |
|
||
| 天眼认证有效期 | 约30分钟 | csrf_token有效期约30分钟，需在每次采集周期前检查并刷新 |
|
||
| 微步签名有效期 | 10分钟 | auth_timestamp与服务端时间差须在10分钟以内 |
|
||
| 天眼时间同步 | 10分钟 | 第三方系统时间与天眼分析平台时间差不能超过10分钟 |
|
||
| 微步频率限制 | 50次/秒 | 微步API调用频率限制为50次/秒，需控制并发请求速率 |
|
||
| 采集间隔 | 5分钟 | 默认每5分钟采集一次，可配置 |
|
||
| 时间窗口重叠 | -1分钟 | 每次采集的时间窗口结束时间为当前时间减1分钟，开始时间为上次采集结束时间 |
|
||
| 分页大小 | 100条/页 | 单次请求最大100条，需循环分页拉取 |
|
||
[/TABLE]
|
||
|
||
|
||
# 5 开发设计
|
||
5.1 数据采集处理流程
|
||
数据采集处理主流程（9步）：
|
||
定时触发 -> 认证管理 -> 构造请求 -> 调用API -> 解析响应
|
||
-> 字段映射（标准化数据格式） -> 写入Kafka（指定topic） -> 更新断点 -> 记录日志
|
||
5.1.1 认证管理流程
|
||
|
||
[TABLE]
|
||
| 设备 | 认证策略 |
|
||
| 天眼 | 1. 检查Redis中缓存的csrf_token是否有效（TTL=25分钟）2. 若无效，执行免密登录流程：生成client_id/secret/signature -> POST获取access_token -> GET提取csrf_token+cookies3. 缓存csrf_token和cookies到Redis（TTL=25分钟） |
|
||
| 微步 | 1. 每次请求实时生成签名（Timestamp + HmacSHA256）2. 无需缓存Token，但Api_key和Secret从配置文件读取 |
|
||
| 深信服XDR | 1. 启动时解码联动码获取AK/SK，缓存到内存2. 每次请求实时生成sign-date和签名头3. 签名后直接发送，不可修改请求 |
|
||
[/TABLE]
|
||
|
||
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 核心类设计
|
||
|
||
[TABLE]
|
||
| 类名 | 类型 | 职责 |
|
||
| DeviceDataCollector | 接口 | 定义统一的采集器接口规范 |
|
||
| TianyanDataCollector | 实现类 | 天眼平台数据采集，含免密登录认证、Web日志/告警日志查询 |
|
||
| WeibuDataCollector | 实现类 | 微步平台数据采集，含HMAC-SHA256签名、攻击/日志流量查询 |
|
||
| XdrDataCollector | 实现类 | 深信服XDR数据采集，含联动码解码、AK/SK签名 |
|
||
| CollectScheduler | 调度器 | 基于Spring @Scheduled定时调度，管理所有采集器的执行周期 |
|
||
| AuthManager | 认证管理器 | 统一管理各设备的Token缓存与刷新策略 |
|
||
| FieldMapper | 字段映射器 | 将各设备原始字段映射为统一标准化格式 |
|
||
| CollectResult | 结果对象 | 封装采集结果统计信息（总数、成功数、失败数、耗时） |
|
||
| CollectorException | 异常类 | 采集过程中异常的统一封装 |
|
||
| DeviceApiConfig | 实体类 | 设备API配置实体，对应device_api_config表 |
|
||
| DeviceApiCollectLog | 实体类 | 采集日志实体，对应device_api_collect_log表 |
|
||
[/TABLE]
|
||
|
||
5.5 定时任务设计
|
||
@Slf4j
|
||
@Component
|
||
public class CollectScheduler {
|
||
@Autowired private List<DeviceDataCollector> collectors;
|
||
@Autowired private DeviceApiConfigService configService;
|
||
@Autowired private RedisTemplate<String, String> redisTemplate;
|
||
/** 主采集任务 - 每5分钟执行 */
|
||
@Scheduled(fixedDelayString = "${device.collect.interval:300000}")
|
||
public void scheduleCollect() {
|
||
List<DeviceApiConfig> 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）
|
||
|
||
[TABLE]
|
||
| 任务编号 | 任务名称 | 工作内容 | 工期(天) | 责任角色 |
|
||
| T1.1 | 设计评审与基线 | 组织设计说明评审，确认接口清单、字段映射规则、消息格式 | 1 | 开发负责人 |
|
||
| T1.2 | 凭证与环境确认 | 获取三类设备API凭证；确认测试环境网络可达（防火墙开通HTTPS策略） | 1 | 开发+运维 |
|
||
| T1.3 | 模块骨架搭建 | 新建syslog-collector-api模块；引入依赖（httpclient/commons-codec/fastjson）；统一异常与日志规范 | 2 | 后端开发 |
|
||
| T2.1 | 数据表与实体层 | device_api_config、device_api_collect_log建表（DM8）；entity/mapper/service代码生成 | 1 | 后端开发 |
|
||
| T2.2 | 统一采集器接口 | DeviceDataCollector接口、CollectResult、CollectorException定义 | 1 | 后端开发 |
|
||
| T2.3 | 调度器开发 | CollectScheduler定时调度、时间窗口计算、采集日志落库 | 2 | 后端开发 |
|
||
| T2.4 | 断点续传与重试 | Redis断点Key读写；指数退避重试（3次：5s/10s/15s）；限流器 | 1 | 后端开发 |
|
||
[/TABLE]
|
||
|
||
6.2.3 阶段二：天眼、微步采集器开发（第1-2周8.28-8.31）
|
||
|
||
[TABLE]
|
||
| 任务编号 | 任务名称 | 工作内容 | 工期(天) | 责任角色 |
|
||
| T3.1 | 免密登录认证 | client_id/client_secret/X-Authorization生成；access_token获取；csrf_token+cookies提取与Redis缓存（TTL=25分钟） | 2 | 后端开发 |
|
||
| T3.2 | Web访问日志采集 | skyeye-weblog索引查询、分页拉取（100条/页）、fast_model模式适配 | 2 | 后端开发 |
|
||
| T3.3 | 告警日志采集 | 9个告警索引联合查询、advance_model模式适配、响应字段解析 | 3 | 后端开发 |
|
||
| T3.4 | 字段映射与联调 | 天眼字段映射；与真实环境联调，验证数据完整性 | 2 | 后端开发 |
|
||
| T4.1 | 签名与请求封装 | HmacSHA256+Base64URLSafe签名；api_key/auth_timestamp/sign URL构造 | 1 | 后端开发 |
|
||
| T4.2 | 查询接口对接 | searchBySql接口对接；columns字段列表构造；分页参数封装 | 2 | 后端开发 |
|
||
| T4.3 | 双类型采集与限流 | attack/info两种net_data_type采集；50次/秒限流控制；字段映射与联调 | 2 | 后端开发 |
|
||
[/TABLE]
|
||
|
||
6.2.5 阶段三：系统调试与上线（第2周，09.01~09-04）
|
||
|
||
[TABLE]
|
||
| 任务编号 | 任务名称 | 工作内容 | 工期(天) | 责任角色 |
|
||
| T5.1 | 集成测试 | 采集器并行运行7×24小时；采集量/延迟/丢数核对；Kafka消息抽检 | 2 | 开发+测试 |
|
||
| T5.2 | 异常场景测试 | Token过期重认证、API失败重试、服务重启断点续传、限流压测 | 1 | 开发+测试 |
|
||
| T5.3 | 部署上线（依赖现场网络策略开通） | Docker Compose编排；生产配置核对；监控告警接入；测试报告归档 | 2 | 开发+运维 |
|
||
[/TABLE]
|
||
|
||
6.2.6 人员分工与资源需求
|
||
|
||
[TABLE]
|
||
| 角色 | 人数 | 主要职责 | 投入占比 |
|
||
| 开发负责人 | 1 | 设计评审、任务分派、进度与质量把控、里程碑验收 | 30% |
|
||
| 后端开发（Java） | 1 | 采集框架、三个采集器、调度与断点、字段映射编码实现及自测 | 100% |
|
||
| 测试工程师 | 1 | 测试用例编写、集成与异常场景测试、测试报告 | 100%（1周） |
|
||
| 运维工程师 | 1 | 申请网络策略开通（3台采集服务器->安全设备）、环境准备、Docker部署、监控接入 | 20% |
|
||
| 厂商接口支持 | 2 | 天眼/微步 接口问题答疑、凭证发放（按需） | 按需 |
|
||
[/TABLE]
|
||
|
||
|
||
# 7 附录
|
||
7.1天眼接口数据样例
|
||
7.2微步口数据样例 |