Add geyecloud-ATD service adapter

[shiyueyi-1111]

Refs #468

This PR adds a read-only OctoBus Service Adapter for geyecloud-ATD 2.3.6.

The service package has been locally tested, imported into OctoBus runtime, and validated against a real geyecloud-ATD environment. Detailed validation evidence, commands, and screenshots are included below.

Add geyecloud-ATD OctoBus Service Adapter

Add geyecloud-ATD OctoBus Service Adapter

1. Summary

本次新增 geyecloud-ATD / 高级威胁检测系统 的 OctoBus Service 适配器，用于将 geyecloud-ATD 的常用只读查询能力接入 OctoBus。

基础信息：

Item	Value
Service package name	geyecloud-atd
Service directory	services/geyecloud__atd_v2-3-6/
Package artifact	Not committed
Runtime mode	long-running
Capability boundary	read-only
RPC count	13

5. Auth Pattern

该服务包使用 geyecloud-ATD API key 作为 OctoBus instance secret。

Secret 示例：

{
  "apiKey": "<masked>"
}

运行时请求会携带以下认证相关 Header：

api-key: <masked>
user-key: ""
X-Ca-Timestamp: <timestamp>
X-Ca-Nonce: <nonce>
X-Ca-Sign: md5(timestamp + nonce)

说明：

• Service 包不保存账号密码。
• Service 包不自动处理 UI 登录验证码。
• 如果 geyecloud-ATD 环境需要通过验证码登录获取 API key，则该步骤作为运维/管理员侧的 key provisioning 流程。
• OctoBus 实例只需要配置稳定的 secret.apiKey 即可调用。

6. Config / Secret

Config 示例：

{
  "baseUrl": "https://192.0.2.10:5443",
  "skipTlsVerify": true,
  "timeoutMs": 10000
}

Secret 示例：

{
  "apiKey": "<masked>"
}

补充说明：

• baseUrl 可以填写 geyecloud-ATD UI 地址。
• 如果包含 /#/workBench 这类前端 hash route，适配器会自动归一化为 API origin。
• 实际 API 路径统一调用 /workbenchApi/furious/...。

7. Implementation Notes

实现要点：

• 使用 @chaitin-ai/octobus-sdk。
• Runtime mode 为 long-running。
• 当前 13 个方法全部为 read-only。
• 同时兼容 snake_case 和 lowerCamelCase 请求字段，便于 Connect JSON 调用。
• 对 geyecloud-ATD 实机返回格式做了统一兼容：
• wrapped response: {code,msg,data}
• unwrapped pagination response: {total,size,current,page,records}
• 对威胁事件风险等级做了增强：
• 数字字段继续保留为 severity
• 中文等级如 高危、中危 通过 severity_text 输出
• 网络日志列表到详情链路已做适配：
• 列表记录实际返回 uuid
• Service 层映射为可用于详情查询的 uid
• 详情调用时将 detail_id/detailId 转换为 geyecloud-ATD 实际接受的 upstream uuid
• 对日志和事件输出采用 whitelist mapping，避免直接暴露上游 raw response 中可能存在的敏感字段。

8. Local Package Validation

Terminal 执行命令：

cd services/geyecloud__atd_v2-3-6
npm test
npm run validate
npm run pack:check

预期结果：

npm test
  tests 8
  pass 8
  fail 0
npm run validate

service package is valid

unary methods: 13
npm run pack:check

package dry-run succeeded

total files: 9

Evidence screenshots:

9. Real Device Validation

已使用提供的 geyecloud-ATD demo 环境完成过实机 API 验证。以下证据已脱敏，不包含 API key、账号密码、验证码、session 或 cookie；demo 环境地址按内部验证需要保留。

Terminal 执行命令：

cd services/geyecloud__atd_v2-3-6
node /tmp/atd-real-validate.mjs

预期脱敏结果：

[
  {"name":"AggregateThreatEvents","status":"OK","code":200,"message":"success","items":4},
  {"name":"GetNetworkLogTimeTrend","status":"OK","code":200,"message":"success","items":19},
  {"name":"GetNetworkLogDimensionStatistics","status":"OK","code":200,"message":"success","items":0},
  {"name":"ListNetworkLogs","status":"OK","code":200,"message":"success","items":5,"hasDetailId":true},
  {"name":"GetNetworkLogDetail","status":"OK","code":200,"message":"success","hasLog":true},
  {"name":"ListFileDetectionLogs","status":"OK","code":200,"message":"success","items":5,"hasDetailId":true},
  {"name":"GetFileDetectionLogDetail","status":"OK","code":200,"message":"success","hasLog":true},
  {"name":"GetFileDetectionSeverityStats","status":"OK","code":200,"message":"success"},
  {"name":"ListSceneMonitors","status":"OK","code":200,"message":"success","items":1,"hasSceneId":true},
  {"name":"SearchSceneMonitorEvents","status":"OK","code":200,"message":"success","items":1},
  {"name":"GetSituationOverview","status":"OK","code":200,"message":"success","sections":5},
  {"name":"SearchThreatEvents","status":"OK","code":200,"message":"success","items":5,"hasDetailId":true},
  {"name":"GetThreatEventDetail","status":"OK","code":200,"message":"success","hasEvent":true,"hasRaw":true}
]

验证链路：

• ListNetworkLogs -> GetNetworkLogDetail
• ListFileDetectionLogs -> GetFileDetectionLogDetail
• SearchThreatEvents -> GetThreatEventDetail
• ListSceneMonitors -> SearchSceneMonitorEvents

Evidence screenshot:

10. OctoBus Runtime Validation

本节保留 OctoBus runtime 必要证据，包括 service import、instance create/update-secret 和最终 RPC 调用。runtime check、capset catalog、产品 UI 和 agent task 截图不是本次提交的必要材料，可按需补充。

10.1 Service Import

Terminal 执行命令：

cd services/geyecloud__atd_v2-3-6
octobus service import geyecloud-atd . --build auto

Evidence screenshots:

10.2 Instance Config / Secret

注意：截图前请确认 Terminal 画面里没有明文真实 API key。

Config 文件示例：

cat > /tmp/geyecloud-atd-config.json <<'JSON'
{
  "baseUrl": "https://192.0.2.10:5443",
  "skipTlsVerify": true,
  "timeoutMs": 10000
}
JSON

Secret 文件示例：

cat > /tmp/geyecloud-atd-secret.json <<'JSON'
{
  "apiKey": "<masked-or-real-key-only-in-local-file>"
}
JSON

创建实例：

octobus instance create geyecloud-atd-demo \
  --service geyecloud-atd \
  --config /tmp/geyecloud-atd-config.json \
  --secret /tmp/geyecloud-atd-secret.json

如实例已存在，可更新 secret：

octobus instance update-secret geyecloud-atd-demo \
  --secret /tmp/geyecloud-atd-secret.json \
  --restart

查看实例：

octobus instance get geyecloud-atd-demo

Evidence screenshots:

10.3 Direct RPC Call Through OctoBus

当前 OctoBus CLI 版本未提供 octobus call 子命令，因此本次使用 capset 暴露的 Connect RPC endpoint 完成直接调用验证。

查看实例状态：

octobus instance get geyecloud-atd-demo

查看 capset 暴露的方法：

octobus capset list-methods geyecloud-atd-readonly-investigation

通过 Connect RPC 直接调用 AggregateThreatEvents：

curl -sS -X POST \
  "http://127.0.0.1:9000/capsets/geyecloud-atd-readonly-investigation/connect/geyecloud-atd-demo/geyecloud.atd.v1.GEYECloudATD/AggregateThreatEvents" \
  -H "Content-Type: application/json" \
  -d '{
    "start": 1773644567000,
    "end": 1774249367000,
    "page": 1,
    "pageSize": 10,
    "terms": "severity",
    "tableName": "hw"
  }' | python3 -m json.tool

10.4 OctoBus Trigger and Product UI Correlation

本节用于补充端到端 UI 对照证据：Terminal 侧通过 OctoBus Connect RPC 触发一次只读查询，产品 UI 侧展示同一类威胁事件/风险等级统计数据。

该证据不是本次提交的必需项，但可作为“OctoBus 已实际触发业务查询，且 geyecloud-ATD 产品侧存在对应数据”的补充说明。

Terminal 执行命令：

curl -sS -X POST \
  "http://127.0.0.1:9000/capsets/geyecloud-atd-readonly-investigation/connect/geyecloud-atd-demo/geyecloud.atd.v1.GEYECloudATD/AggregateThreatEvents" \
  -H "Content-Type: application/json" \
  -d '{
    "start": 1773644567000,
    "end": 1774249367000,
    "page": 1,
    "pageSize": 10,
    "terms": "severity",
    "tableName": "hw"
  }' | python3 -m json.tool

证据对应关系：

Terminal 通过 OctoBus Connect RPC 调用 AggregateThreatEvents 并返回 success；产品 UI 同步展示威胁事件/风险等级统计数据。两张截图组合证明 OctoBus Service 调用链路和 geyecloud-ATD 数据读取链路可用。

Terminal evidence screenshot:

Product UI evidence screenshot:

11. Integration Evidence

实机验证过程中发现并已修复/兼容的文档与真实接口差异：

• 部分接口返回 {code,msg,data} 包裹结构。
• 部分接口直接返回 {total,size,current,page,records} 裸分页结构。
• 网络日志列表记录使用 uuid，而网络日志详情接口实际接受 upstream uuid，不是文档/同类接口中常见的 detailId。
• 威胁事件风险等级可能返回中文字符串，因此新增 severity_text 保留语义。
• geyecloud-ATD 日志类接口可能存在敏感原始字段，因此 Service 输出采用白名单字段映射。

这些差异已经通过单元测试和通用响应归一化逻辑覆盖。

12. Security / Evidence Hygiene

安全和脱敏处理：

• 未提交真实账号、密码、API key、session、cookie、验证码等敏感凭据；demo 环境地址按内部验证需要保留。
• 测试用例使用 dummy-api-key 和文档保留 IP 段。
• 实机验证结果只保留方法名、状态、code、message、条数和链路可用性。
• 当前版本为只读能力，不执行写操作，不修改 geyecloud-ATD 配置。

13. Known Limits

当前限制：

• 暂不包含策略配置、处置下发、配置修改等 writable API。
• 暂不自动化 UI 登录验证码流程。
• API key 需要由管理员或运维侧在 geyecloud-ATD 环境中预先生成，再配置到 OctoBus instance secret。
• 本次必要证据聚焦 Service 包本地验证、真实 API 验证、OctoBus 导入、实例配置和直接 RPC 调用；UI 和 agent 端到端截图可按需追加。

14. Review Checklist

• Service package created under services/geyecloud__atd_v2-3-6/
• service.json / proto / src / bin / schemas / tests / README included
• 13 unary RPCs implemented
• Local tests passed
• octobus-sdk validate --strict passed
• npm run pack:check passed
• Real geyecloud-ATD API validation flow prepared
• Secrets and real environment details masked
• Current capability boundary documented as read-only