aiops/docs/specs/ai/agent-operation-hardening.md

AI 运维 Agent 第一阶段安全加固

字段	内容
状态	Accepted
级别	S3
负责人	Logan.Li
创建日期	2026-09-03
最后更新	2026-09-03
关联任务	AIOps、OpsXCLI、OpsXShell 三类运维 Agent 按产品边界实施 P0 安全优化

1. 背景与证据

AIOps 是多用户 Web 运维平台，其 Agent 通过平台资产和托管凭证执行 SSH/Kubernetes 操作。当前工具结果在 backend/pkg/agentcli/core/agent.go 中先进入自动分析、事件和 Evolver，持久化阶段才脱敏；backend/controller/agent_cli_api.go 删除会话时同时删除 AIRunSpan 与 OpsCommand；ssh_execute 接受未封顶超时，底层执行使用独立背景上下文；WebSocket 入口仅验证 JWT，未校验 aiops:agent-cli 权限。

OpsXCLI 是服务器本机 CLI，OpsXShell 是桌面当前 SSH 连接助手。二者与 AIOps 共享脱敏、风险和取消原则，但不共享目标、凭证、审批或审计实现。

2. 目标与非目标

目标

• AIOps 工具输出和错误在进入模型、WebSocket、缓存、Evolver及数据库前完成脱敏。
• AIOps Agent CLI 入口要求有效用户具备 aiops:agent-cli 权限，管理员保持兼容。
• AIOps 会话删除只删除用户可见的会话消息，不删除独立执行审计。
• SSH 工具限制最大超时，并在任务取消或超时时终止当前远端会话。
• 明确三个独立产品的执行与信任边界。

非目标

• 本阶段不合并三个项目的 Agent 内核或工具注册中心。
• 本阶段不新增数据库表、生产迁移或跨资产自动编排。
• 本阶段不宣称已有资产级授权模型；权限码是入口门禁，资产级授权仍作为后续 S3 工作。
• 本阶段不允许自动生成的记忆或技能直接获得无人值守执行权限。

3. 用户场景

• 当无 aiops:agent-cli 权限的用户连接 Agent CLI 时，系统必须在建立 WebSocket 前拒绝请求。
• 当远端输出包含凭证、令牌或私钥时，模型、浏览器事件、记忆和数据库只能收到脱敏文本。
• 当用户删除会话时，界面历史可被删除，但执行跨度和命令审计必须保留。
• 当用户取消任务或命令超过最大超时时，远端 SSH session 必须被关闭。

4. 需求

功能需求

• FR-01：Agent 核心必须在任何下游消费工具结果前执行统一脱敏。
• FR-02：Agent WebSocket 与会话 API 必须校验 aiops:agent-cli 权限；管理员不受权限码缺失影响。
• FR-03：删除会话不得删除 AIRunSpan 和 OpsCommand。
• FR-04：SSH 工具的调用方超时必须限制在 1 至 300 秒，默认值由平台配置决定。
• FR-05：SSH 执行必须继承调用上下文，超时或取消时关闭当前 session。
• FR-06：三个项目必须分别使用平台资产、本机身份、当前活跃连接作为唯一目标来源。

非功能需求

• NFR-01：脱敏失败不得回退到原文；不修改原始参数对象。
• NFR-02：现有 Agent CLI URL 和成功响应保持兼容；新增拒绝使用 HTTP 403 和统一响应体。
• NFR-03：安全拒绝、超时和取消必须可通过现有日志、Span 或命令审计观察。
• NFR-04：新增和修改的 Go 代码注释使用中文并署名 // Logan.Li。

5. 设计与契约

模块边界

guardrail 负责纯函数脱敏；core.Agent 保证脱敏时机；remoteexec 负责真实取消；middleware 负责功能权限；controller 负责会话可见性和审计生命周期。OpsXCLI 与 OpsXShell 只复用行为原则，不依赖 AIOps 包。

API / 事件

• GET /ws/agent-cli：JWT/API Key 认证后校验 aiops:agent-cli；无权限返回 HTTP 403，不升级连接。
• /api/v1/aiops/agent-cli/*：沿用统一响应结构；无权限返回 model.Response{Code:403}。
• 工具事件字段保持兼容，但 ToolArgs、Output、错误均为脱敏值。

数据与迁移

不新增表或字段。删除会话后保留 AIRunSpan 和 OpsCommand，其 run_id 继续作为不可变关联键。回滚不需要数据库迁移。

UI / 交互

现有页面和确认流程保持不变。权限不足时不进入 Agent 会话；敏感输出以 [REDACTED] 或 [REDACTED_PRIVATE_KEY] 展示。

6. 风险与可观测性

风险/失败模式	防护或降级	观测信号
正则未覆盖新凭证格式	JSON 敏感键与文本模式双层脱敏，持续补充测试	脱敏测试与审计抽检
角色未配置权限导致合法用户被拒	管理员兼容；发布前检查默认角色权限	403 响应与访问日志
取消时远端进程未立即退出	关闭 SSH session，并返回取消/超时状态	Span 状态、执行耗时、错误文本
会话删除后审计成为孤立记录	通过稳定 run_id 检索，不依赖 AIRun 外键级联	审计查询和数据库行数

7. 验收标准

• AC-01：给定包含密码、Bearer Token、连接串或私钥的工具结果，当核心处理结果时，所有下游内容均不含原始敏感值。
• AC-02：给定普通用户缺少 aiops:agent-cli 权限，当访问 Agent CLI 时，返回 403；管理员或具备权限的用户可继续。
• AC-03：给定存在 Span 和命令审计的会话，当用户删除会话时，消息和会话删除，Span 与命令审计保留。
• AC-04：给定超出范围的 SSH timeout，当执行工具时，实际值被限制到 300 秒以内。
• AC-05：给定调用上下文取消，当 SSH 命令运行中，session 被关闭且调用及时返回。
• AC-06：三个项目文档明确各自目标来源、凭证来源、审计和禁止越界行为。

8. 验证追踪

验收标准	测试或检查	结果
AC-01	go test ./pkg/agentcli/...	Pending
AC-02	middleware 单元测试 + go test ./middleware/...	Pending
AC-03	controller 删除行为测试或数据库集成检查	Pending
AC-04	ssh_execute 超时解析单元测试	Pending
AC-05	remoteexec 上下文取消单元测试/代码路径检查	Pending
AC-06	文档链接与内容检查	Pending

9. 发布与回滚

发布前运行后端测试、go vet ./... 与构建，确认默认角色包含 aiops:agent-cli。按单实例灰度观察 403、SSH 超时和审计写入，再滚动发布。出现兼容问题时回退到标签 agent-hardening-baseline-20260902；本阶段没有数据库结构变更，保留的审计数据无需回填或清理。

10. 决策记录

日期	决策	原因与影响
2026-09-03	三个项目独立实现执行边界	CLI 本机、桌面当前连接、Web 平台资产的信任模型不同
2026-09-03	会话删除不删除操作审计	用户历史管理不能破坏生产运维追责证据
2026-09-03	第一阶段先做入口权限，不虚构资产级 RBAC	当前仓库没有通用服务器授权关系模型，需要后续独立规格设计

11. 遗留事项

• 设计服务器、Kubernetes 集群与 Namespace 的资源级授权模型。
• 将审批令牌绑定用户、目标、命令摘要、风险等级和有效期。
• Evolver 记忆增加草稿、审核、发布、撤销、范围与保留期状态。