1- # 4.8.1 自定义设备接入 ` #api ` ` #web2cli `
1+ # 4.8.1 自定义设备接入
22
33自定义设备接入用于把未预置的安全设备纳入 ** 设备接入** 页面。它的目标不是只生成一个普通 API 工具，而是生成设备页可识别、可配置、可按实例启停和测试的 ** device 插件** 。
44
5- 适合接入的对象包括： NDR、WAF、防火墙、HIDS、EDR、态势感知平台、资产平台、告警平台、堡垒机，以及企业内部只有私有接口或 Web 控制台的系统。
5+ 适合接入的对象包括 NDR、WAF、防火墙、HIDS、EDR、态势感知平台、资产平台、告警平台、堡垒机，以及企业内部只有私有接口或 Web 控制台的系统。
66
7- ## 接入方式
7+ ## 1. 接入入口
88
9- 进入 ** 设备接入** 后，选择 ** 添加设备** ，在厂商选择中进入 ** 自定义设备** 。自定义设备当前主要有两条路径：
9+ 进入 ** 设备接入** 后，选择 ** 添加设备** ，在厂商选择中进入 ** 自定义设备** 。自定义设备当前主要支持 API 接入、WebCLI 接入和 Workflow 接入三条路径。
1010
11- ![ 选择自定义设备接入方式] ( ../../../img/modules/devices/custom-access-mode.png )
11+ <figure class =" device-doc-shot device-doc-shot--medium " >
12+ <img src =" ../../../img/modules/devices/custom-access-mode.png " alt =" 选择自定义设备接入方式 " >
13+ <figcaption >从设备接入页面选择自定义设备，并按设备条件选择 API、WebCLI 或 Workflow。</figcaption >
14+ </figure >
1215
1316| 接入方式 | 适用场景 | 生成结果 |
1417| --- | --- | --- |
1518| API 接入 | 设备提供官方 API、私有 API、OpenAPI 文档或可整理出的 HTTP 接口。 | Rex 使用 ` tool-builder ` 生成可复用的 device 插件。 |
1619| WebCLI 接入 | 设备没有开放 API，或关键能力只能从 Web 控制台完成。 | Rex 使用 ` web2cli ` 沉淀页面行为和隐藏接口，并按需生成 WebCLI device 插件。 |
20+ | Workflow 接入 | 设备数据以 Syslog、Kafka、Webhook 等形式持续推送。 | 前往 Workflow 发布 / 集成页面配置输入源，把设备事件流接入指定工作流。 |
1721
18- 如果设备支持 Syslog、Kafka 或 Webhook 推送，优先把这类事件流接到 [ Workflow 工作流] ( /md/modules/workflow ) 的 Integration 入口 ，而不是在这里创建 device 插件。
22+ 如果设备支持 Syslog、Kafka 或 Webhook 推送，优先选择 ** Workflow 接入 ** ，把这类事件流接到 [ Workflow 工作流] ( /md/modules/workflow#4-5-正式运行 ) 的发布 / 集成入口 ，而不是在这里创建 device 插件。可以前往 Workflow 页面的任意工作流，进入 ** 发布 / 集成 ** 页面查看并配置对应入口 。
1923
20- ## API 接入流程
24+ ## 2. API 接入流程
2125
2226API 接入适合长期运行、定时任务、批量查询和需要稳定审计记录的场景。你需要向 Rex 提供 API 文档或接口说明，Rex 会先澄清缺失信息，再生成设备页可识别的 device 插件。
2327
24- ![ API 接入时向 Rex 提供资料] ( ../../../img/modules/devices/custom-api-rex-prompt.png )
28+ ### 2.1 提供接口资料
29+
30+ <figure class =" device-doc-shot device-doc-shot--wide " >
31+ <img src =" ../../../img/modules/devices/custom-api-rex-prompt.png " alt =" API 接入时向 Rex 提供资料 " >
32+ <figcaption >把产品信息、接口文档、认证方式和期望能力范围交给 Rex。</figcaption >
33+ </figure >
2534
2635建议至少准备：
2736
@@ -31,9 +40,14 @@ API 接入适合长期运行、定时任务、批量查询和需要稳定审计
3140- 认证方式和凭据类型，例如 API Key、Token、AK/SK、用户名密码、签名规则。
3241- 希望接入的能力范围；如果只接部分接口，要明确接口名或路径。
3342
43+ ### 2.2 配置设备实例
44+
3445生成插件后，返回设备接入页刷新模板，选择新生成的设备模板并填写实例配置。配置表单来自插件 ` _provider.yaml ` 的 ` credential_fields ` ，所以不同设备会展示不同字段。
3546
36- ![ API device 插件配置表单] ( ../../../img/modules/devices/custom-api-config.png )
47+ <figure class =" device-doc-shot device-doc-shot--narrow " >
48+ <img src =" ../../../img/modules/devices/custom-api-config.png " alt =" API device 插件配置表单 " >
49+ <figcaption >API 设备实例配置表单，密钥类字段由设备实例配置保存。</figcaption >
50+ </figure >
3751
3852常见字段含义：
3953
@@ -45,11 +59,16 @@ API 接入适合长期运行、定时任务、批量查询和需要稳定审计
4559- ** 启用设备** ：关闭后 Agent 不会调用此设备的工具。
4660- ** 连通测试** ：对当前设备实例发起测试，并把成功、失败和延迟写回设备状态。
4761
48- ## WebCLI 接入流程
62+ ## 3. WebCLI 接入流程
4963
5064WebCLI 接入适合没有稳定 API、API 覆盖不足，或必须通过 Web 控制台才能完成查询和操作的设备。它不是把浏览器点击流程直接作为长期运行主路径，而是优先从页面行为和浏览器请求中沉淀稳定接口，再封装为 device 插件。
5165
52- ![ WebCLI 接入时向 Rex 提供资料] ( ../../../img/modules/devices/custom-webcli-rex-prompt.png )
66+ ### 3.1 提供页面资料
67+
68+ <figure class =" device-doc-shot device-doc-shot--wide " >
69+ <img src =" ../../../img/modules/devices/custom-webcli-rex-prompt.png " alt =" WebCLI 接入时向 Rex 提供资料 " >
70+ <figcaption >提供登录入口、目标页面、操作目标和认证限制，便于 Rex 沉淀稳定动作。</figcaption >
71+ </figure >
5372
5473建议至少准备：
5574
@@ -59,9 +78,14 @@ WebCLI 接入适合没有稳定 API、API 覆盖不足，或必须通过 Web 控
5978- 认证限制、权限要求和可用登录态。
6079- 是否需要人工扫码、验证码、堡垒机跳转或只读账号。
6180
81+ ### 3.2 配置登录态
82+
6283WebCLI 设备插件默认使用 ` cookie/auth-state ` 思路：优先复用浏览器保存的登录态文件，并在需要时通过用户名、密码辅助刷新登录态。不要把 Cookie、Token 或 auth state JSON 直接写进插件文件。
6384
64- ![ WebCLI device 插件配置表单] ( ../../../img/modules/devices/custom-webcli-config.png )
85+ <figure class =" device-doc-shot device-doc-shot--narrow " >
86+ <img src =" ../../../img/modules/devices/custom-webcli-config.png " alt =" WebCLI device 插件配置表单 " >
87+ <figcaption >WebCLI 设备实例通常配置 Base URL 和浏览器登录态文件路径。</figcaption >
88+ </figure >
6589
6690常见字段含义：
6791
@@ -72,7 +96,13 @@ WebCLI 设备插件默认使用 `cookie/auth-state` 思路：优先复用浏览
7296
7397WebCLI 的最终产物应当是设备页可识别的 device 插件。CLI 可以作为调试或回归入口保留，但不应作为设备运行时的主路径。
7498
75- ## device 插件如何被设备页识别
99+ ## 4. Workflow 接入说明
100+
101+ Workflow 接入用于持续接收设备数据，适合设备已经能通过 Syslog、Kafka 或 Webhook 推送日志、告警、资产变更事件等数据的场景。它不生成 device 插件，而是把设备事件流配置为某个 Workflow 的输入源，由 Workflow 负责后续解析、研判、通知或处置。
102+
103+ 配置入口不在自定义设备插件表单中。请前往 [ Workflow 工作流] ( /md/modules/workflow#4-5-正式运行 ) 页面，打开任意一个需要接收设备数据的 Workflow，在 ** 发布 / 集成** 页面查看并配置 Syslog、Kafka 等入口。
104+
105+ ## 5. device 插件识别规则
76106
77107设备页不会手工维护自定义设备清单，而是从插件元数据中发现模板。一个自定义 device 插件至少需要包含：
78108
@@ -108,11 +138,14 @@ credential_fields:
108138- 工具 YAML 的 `provider` 必须与 `_provider.yaml.service_id` 一致。
109139- 高风险写操作应在工具 YAML 中开启确认，不要把删除、封禁、隔离类动作做成无确认默认动作。
110140
111- # # 接入后的设备列表
141+ # # 6. 接入后的设备列表
112142
113143配置保存后，设备会回到主列表。列表会显示机房、设备数量、连接状态、模板标识、厂商和最近测试结果。
114144
115- 
145+ <figure class="device-doc-shot device-doc-shot--wide">
146+ <img src="../../../img/modules/devices/device-list-custom.png" alt="自定义设备出现在设备接入列表">
147+ <figcaption>自定义设备保存后会回到设备列表，并展示连接状态和模板标识。</figcaption>
148+ </figure>
116149
117150状态含义：
118151
@@ -123,7 +156,7 @@ credential_fields:
123156
124157在设备详情里还可以查看 **工具** 标签。设备工具支持按单个设备实例启停；如果同一个插件接入了多台设备，可以只关闭某一台设备上的特定工具，不影响其他实例。
125158
126- # # 常见问题
159+ # # 7. 常见问题
127160
128161| 问题 | 处理方式 |
129162| --- | --- |
@@ -133,10 +166,55 @@ credential_fields:
133166| 内网自签名证书导致测试失败 | 在设备配置里关闭 **SSL 验证** 后重新测试。 |
134167| 字段里有密码、Token、Cookie | 放在 `credential_fields` 的 secret 字段中，由设备实例配置保存，不要写入插件代码或文档。 |
135168
136- # # 相关文档
169+ # # 8. 相关文档
137170
138171- [设备管理](/md/modules/devices)：查看设备管理主页面说明。
139172- [工具清单](/md/modules/tools)：维护 API 工具、MCP 能力和设备工具。
140173- [Workflow 工作流](/md/modules/workflow)：接入 Syslog、Kafka、Webhook 等事件流。
141174- [内网安全产品接入](/md/scenarios/network-integration)：查看 API 接入主路径。
142175- [浏览器自动化与网页登录](/md/scenarios/browser-automation)：查看浏览器和 WebCLI 场景边界。
176+
177+ <style>
178+ .device-doc-shot {
179+ margin : 24px auto 28px;
180+ text-align : center;
181+ }
182+
183+ .device-doc-shot img {
184+ display : block;
185+ width : 100%;
186+ margin : 0 auto;
187+ border : 1px solid var(--vp-c-divider);
188+ border-radius : 10px;
189+ box-shadow : 0 8px 28px rgb(0 0 0 / 8%);
190+ }
191+
192+ .device-doc-shot figcaption {
193+ margin-top : 10px;
194+ color : var(--vp-c-text-2);
195+ font-size : 14px;
196+ line-height : 1.6;
197+ }
198+
199+ .device-doc-shot--wide {
200+ max-width : 920px;
201+ }
202+
203+ .device-doc-shot--medium {
204+ max-width : 760px;
205+ }
206+
207+ .device-doc-shot--narrow {
208+ max-width : 620px;
209+ }
210+
211+ @media (max-width: 640px) {
212+ .device-doc-shot {
213+ margin : 18px auto 22px;
214+ }
215+
216+ .device-doc-shot img {
217+ border-radius : 8px;
218+ }
219+ }
220+ </style>
0 commit comments