Onesig Use

OneSIG Use

First

先判断操作模式：API V.S Browser。

何时使用 API

• 默认先判断当前诉求是否被新版 Strategy API 覆盖；覆盖时优先使用 API
• 查询类请求与配置写入类请求必须严格区分；用户没有明确要求写操作时，默认只使用只读查询能力
• 当前项目内最新工具包是 .flocks/plugins/tools/device/onesig_v2_5_3，只暴露两个 grouped tool：
  • onesig_strategy_api_query：只读查询，requires_confirmation=false
  • onesig_strategy_api_ops：写操作，requires_confirmation=true

当前 Strategy API 覆盖的能力：

• 设备状态：平台状态、系统状态、网络状态
• 资产：资产组、资产列表、资产类型，以及资产 / 资产组的新增、更新、删除
• 防护策略：策略列表、策略更新、策略删除
• 全局白名单、全局黑名单、封禁白名单
• HTTP 黑名单

何时使用浏览器

• 当前 Strategy API 没有覆盖目标能力，例如威胁监控、仪表盘、失陷主机、入站 / 出站事件、报告、IPS、Syslog 自动封禁、FTP/SFTP 联动、高危端口防护、用户管理、HTTPS 解密、网口 / 路由 / DNS、HA、OneCC、升级备份、license、MDR、诊断、帮助文档
• API 工具未检测到、未配置、无权限、ApiKey / Secret 缺失、认证失败、SSL 验证失败或服务不可达
• 任务必须查看页面级详情、攻击链、威胁图、报表预览或人工确认弹窗
• 页面需要人工登录、图形验证码、TOTP、强制改密或页面级确认
• 用户明确要求使用浏览器，或者已经在浏览器操作过程中

请求确认

除非用户要求使用浏览器，否则如果 API 不可用，应提示用户检查 OneSIG Strategy API 配置，或确认是否改用浏览器模式。

当确定操作模式后：

• API 模式：必须阅读 API 模式使用指南
• 浏览器模式：必须阅读浏览器模式使用指南

API 模式使用指南

必须阅读：

各 grouped tool 与 action 的详细说明、最小调用示例、失败处理见 references/api-reference.md。

核心调用约定：

• onesig_strategy_api_query 用于所有只读查询
• onesig_strategy_api_ops 用于所有写操作；调用前必须确认影响范围
• 入参优先使用 { "action": "...", "body": { ... } }
• Strategy API 认证是 ApiKey + Secret 的 HMAC-SHA1 签名，handler 会自动生成 apikey / timestamp / sign，agent 不要手工拼签名
• Strategy API 走 /api/v3/... 路径；不要混用旧控制台 Cookie 版 /v3/... 工具说明
• 分页字段使用 pageNo / pageSize；不要传 OneSEC 的 cur_page / page_size / page_items_num
• 当前 Strategy API action 没有 OneSEC 风格的 time_from / time_to；不要把 OneSEC 时间参数套进 OneSIG
• 查询单条或写操作前，如果缺少业务 ID，应先调用对应 list action 获取主键，再执行下一步

高风险写操作要特别谨慎，例如：

• asset_group_create / asset_group_update / asset_group_delete
• asset_create / asset_update / asset_delete
• protection_policy_update / protection_policy_delete
• whitelist_create / whitelist_update / whitelist_delete / whitelist_remove
• blacklist_create / blacklist_update / blacklist_delete / blacklist_remove
• banned_whitelist_create / banned_whitelist_update / banned_whitelist_delete
• http_blacklist_create / http_blacklist_update / http_blacklist_enable / http_blacklist_delete

浏览器模式使用指南

• 如果 OneSIG 设备的访问地址不清楚，请先询问用户，不要擅自填写域名
• 用 --headed 打开浏览器，人工完成登录（OneSIG 部署可能启用了图形验证码 / TOTP / 强制改密策略）
• OneSIG 控制台与 OneSEC / 青藤是不同产品；不要把 OneSEC 的页面路径或 OneSEC 的 API 套用到 OneSIG

只要进入浏览器模式，就请阅读并按照 browser-workflow 操作，不要直接跳过本 skill 去套用其他通用浏览器 skill。

请严格按照以下文档执行：

• references/browser-workflow.md