Logan.LiandCursor
2fd1624bec
收紧 SSH 命令护栏、权限校验与远程执行会话，并同步主流大模型供应商列表。 Co-authored-by: Cursor <cursoragent@cursor.com>
126 lines
7.2 KiB
Markdown
126 lines
7.2 KiB
Markdown
# 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 记忆增加草稿、审核、发布、撤销、范围与保留期状态。
|