feat: 加固 Agent CLI 执行边界并更新模型目录
收紧 SSH 命令护栏、权限校验与远程执行会话，并同步主流大模型供应商列表。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Logan.LiandCursor committed
1 parent
67660ae1d6
commit
2fd1624bec
18 files changed
+480
-49
No files matched your search
@@ -1,6 +1,6 @@
|
||||
# AI Agent / Agent CLI 设计文档
|
||||
|
||||
> 更新：2026-07-05
|
||||
> 更新：2026-09-03
|
||||
> 范围：AIOps 平台内置的 AI 运维 Agent、Agent CLI WebSocket 执行页、主机 AI 任务、Kubernetes AI 排障。// Logan.Li
|
||||
|
||||
---
|
||||
@@ -21,7 +21,7 @@ AI Agent / Agent CLI 是 AIOps 的智能执行入口。用户在浏览器中选
|
||||
|
||||
## 文档目录
|
||||
|
||||
当前目录压缩为 8 篇正文，避免把同一条链路拆得过碎：
|
||||
当前目录包含 9 篇正文，避免把同一条链路拆得过碎：
|
||||
|
||||
| 编号 | 文档 | 说明 |
|
||||
|------|------|------|
|
||||
@@ -33,6 +33,7 @@ AI Agent / Agent CLI 是 AIOps 的智能执行入口。用户在浏览器中选
|
||||
| 06 | [会话记忆与 Evolver](06-会话记忆与Evolver.md) | 会话表、消息表、历史恢复、记忆注入、自进化 |
|
||||
| 07 | [路线图与评测](07-路线图与评测.md) | 可用堡垒机、企业堡垒机、智能闭环、评测指标 |
|
||||
| 08 | [代码审计与平台智能化优化](08-代码审计与平台智能化优化.md) | Agent CLI 代码差距、AIOps 上下文工具、告警分析和预测分析升级路线 |
|
||||
| 09 | [三产品定位与执行边界](09-三产品定位与执行边界.md) | OpsXCLI、OpsXShell、AIOps 的独立目标、凭证、执行和审计边界 |
|
||||
|
||||
---
|
||||
|
||||
@@ -109,8 +110,10 @@ backend/pkg/agentcli/
|
||||
3. **工具最小化**：工具暴露越少，模型误调用和越权风险越低。
|
||||
4. **安全前置**：危险命令硬拒，高危操作必须确认，后续接审批。
|
||||
5. **过程可见**：思考、工具调用、工具输出、确认和最终结果均走 WebSocket 事件流。
|
||||
6. **历史可追溯**：会话和消息入库，支持回放、删除、继续追问。
|
||||
7. **记忆可控**：Evolver 记忆按用户隔离，后续逐步 DB 化和可视化管理。
|
||||
6. **审计独立**：会话和消息可按用户需求删除，但远程执行跨度和命令审计不得随聊天历史删除。
|
||||
7. **历史可追溯**：会话和消息入库，支持回放、删除、继续追问。
|
||||
8. **记忆可控**：Evolver 记忆按用户隔离，后续增加审核、发布、撤销和保留期治理。
|
||||
9. **产品不越界**：AIOps 只执行平台授权资产，不复用 OpsXCLI 本机执行器或 OpsXShell 当前连接执行器。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
# 三产品 AI 运维 Agent 定位与执行边界
|
||||
|
||||
> 更新：2026-09-03
|
||||
> 适用范围：OpsXCLI、OpsXShell、AIOps 三个独立项目的 AI 运维能力。
|
||||
|
||||
## 设计声明
|
||||
|
||||
三个项目服务不同的运维入口，必须独立实现目标选择、凭证取得、风险裁决和执行生命周期。可以共享安全原则、结构化结果和评测用例，但不得共享一个可在本机、桌面 SSH 与 Web 平台之间自由切换的“通用远程执行器”。
|
||||
|
||||
| 项目 | 产品角色 | 唯一默认目标来源 | 凭证边界 | 审计边界 |
|
||||
|------|----------|------------------|----------|----------|
|
||||
| OpsXCLI | 服务器本机 CLI 运维工具 | 当前操作系统和当前工作目录 | 当前 OS 用户；SSH 仅显式启用并使用本机密钥 | 本机权限受限的会话/执行记录 |
|
||||
| OpsXShell | 桌面远程终端助手 | 用户当前活跃 SSH connectionId | 已建立连接内部持有，模型不得选择或读取凭证 | 默认仅当前窗口，不建设堡垒机审计 |
|
||||
| AIOps | 多用户 Web 运维管理平台 | 平台授权的资产 ID 或 Kubernetes 目标 | 后端凭证库按权限解析，模型只见目标摘要 | 独立、可检索、不可随聊天会话删除 |
|
||||
|
||||
## 强制不变量
|
||||
|
||||
1. OpsXCLI 默认本地执行。远程 SSH 是例外能力，必须显式指定，严格校验 `known_hosts`，不得因校验文件缺失而降级为信任所有主机。
|
||||
2. OpsXShell Agent 只能复用任务开始时的活跃 SSH 连接。执行期间连接改变、断开或被替换时，任务必须停止，不得自动切换到其他标签或保存的主机。
|
||||
3. AIOps Agent 只能使用后端注入的平台目标和凭证。模型不得提供任意 IP、用户名、密码、私钥路径或集群凭证绕过资产系统。
|
||||
4. 工具结果和错误必须先脱敏，再进入模型上下文、UI、记忆、缓存或持久化。
|
||||
5. 风险确认只批准精确的目标与命令。目标、命令或参数发生变化后必须重新裁决。
|
||||
6. 自动学习内容默认不可信，未经审核不得成为无人值守执行依据。
|
||||
|
||||
## 统一结果语义
|
||||
|
||||
三个项目的工具结果至少应表达运行 ID、工具调用 ID、目标摘要、动作摘要、退出码、成功状态、开始/结束时间、超时、取消、脱敏数量和验证结果。具体类型可以独立实现，但语义不得依靠解析自由文本猜测。
|
||||
|
||||
## 推荐执行链
|
||||
|
||||
```text
|
||||
用户意图
|
||||
→ 生成计划
|
||||
→ 锁定产品内合法目标
|
||||
→ 参数与风险校验
|
||||
→ 必要时人工确认/平台审批
|
||||
→ 独立执行器执行
|
||||
→ 输出脱敏
|
||||
→ 结果验证
|
||||
→ 产品范围内审计或会话记录
|
||||
```
|
||||
|
||||
## 禁止的错误复用
|
||||
|
||||
- 不把 OpsXCLI 的本机任意 Shell 直接暴露给 AIOps Web 用户。
|
||||
- 不让 OpsXShell Agent 创建第二套 SSH 连接或读取保存凭证。
|
||||
- 不把 AIOps 的平台审批、资产库存和永久审计强加给轻量桌面终端。
|
||||
- 不以共享正则文件代替各项目执行前的最终安全裁决。
|
||||
|
||||
## 演进优先级
|
||||
|
||||
- P0：脱敏、目标锁定、危险操作拒绝、超时与真实取消、记忆不自动获得执行权。
|
||||
- P1：结构化结果、只读诊断工具、执行后验证、目标与命令绑定确认。
|
||||
- P2：版本化 Runbook、受控经验库、场景评测、跨资产自动化与熔断。
|
||||
@@ -0,0 +1,125 @@
|
||||
# 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 记忆增加草稿、审核、发布、撤销、范围与保留期状态。
|
||||
Reference in new issue
Block a user