Endpoint AIops

Endpoint AIops

免责声明：由社区维护的开源项目。**与任何终端管理供应商均无关联，未获其认可或赞助。**产品名称和商标归其所有者所有。采用 MIT 许可。

为受管终端机群提供受治理的 AI 运维——包括瘦客户端、VDI 终端和其他集中管理的设备——并内置治理机制：统一审计日志、令牌／失控预算保护、撤销令牌记录，以及描述性风险等级。不绑定供应商：通过可配置的方言，使用 Bearer 身份验证与终端管理服务的 REST API 通信——参见方言。独立运行：除 httpx 和 MCP SDK 外没有其他依赖。测试套件基于模拟；终端管理 REST 路径尚未在实际管理服务上进行过验证——参见 docs/VERIFICATION.md。

功能

两种核心分析，以及围绕它们的受保护读写操作：

• 登录风暴分析——在“所有人都于上午 9 点登录”的故障期间，检测风暴（滑动时间窗口内并发登录激增），并对拖慢登录和启动时间的终端／用户进行排名。每个标记都会附上具体数值，而不是给出黑箱判定。
• 补丁／配置漂移——找出偏离机群基线的终端（补丁级别过旧、Agent 版本异常、操作系统构建版本或配置文件不一致）。若未声明基线，则根据机群多数情况推导，因此在尚无黄金镜像时也能使用。

可用功能

• 命令行（endpoint-aiops ...）：init、overview、endpoint list/get/assign-profile/reboot、session list/storm、drift report/patch、secret set/list/rm/migrate/rotate-password、doctor、mcp。
• MCP 服务（endpoint-aiops mcp 或 endpoint-aiops-mcp）：13 个工具（10 个读取工具、3 个写入工具），全部由内置的 @governed_tool 机制封装。
• 加密凭据：管理服务 API 密钥存储在加密存储文件 ~/.endpoint-aiops/secrets.enc 中（Fernet + scrypt）——绝不会以明文形式存储在磁盘上。通过 ENDPOINT_AIOPS_MASTER_PASSWORD（MCP／CI）提供主密码解锁，或通过交互式提示输入（命令行）。
• 可逆性：endpoint_assign_profile（高风险）会捕获先前的配置文件，并记录一个“重新分配先前配置文件”的逆向撤销描述符。endpoint_reboot（中风险）会捕获先前的在线状态并写入审计记录，但不会声明撤销操作（重启没有安全的逆操作）。
• 安全性：会更改状态的命令行操作（endpoint assign-profile、endpoint reboot）需要二次确认，并支持 --dry-run。

功能矩阵（13 个 MCP 工具）

类别	工具	数量	读／写
概览	overview	1	读取
清单	endpoint_list、endpoint_get、endpoint_health_score	3	读取
会话	session_list、login_storm_analysis	2	读取
漂移	drift_report、patch_status、patch_compliance	3	读取
修复	endpoint_assign_profile	1	写入（高风险）
	endpoint_reboot	1	写入（中风险）
撤销	undo_list	1	读取
	undo_apply	1	写入（中风险）

分析工具（login_storm_analysis、drift_report、patch_status、 patch_compliance、endpoint_health_score）支持注入记录，以便进行纯离线分析；endpoint_health_score 和 patch_compliance 仅支持注入数据，其他工具还可以从已配置的目标获取实时数据。

此工具会做什么，以及不会决定什么

此工具可准确、高效地执行受管端点操作——读取和写入——并记录每一次操作。它不会决定是否允许执行写入。这由 Agent 判断，或由你连接的账号权限决定：为它提供一个限定为只读角色的管理控制台账号或 API 令牌，写入操作就会在服务器端失败——权限实际由服务器掌控。

因此，无需配置只读开关、策略文件或审批关卡。此工具唯一保证的是不会有操作悄无声息：通过 MCP 和 CLI 发起的每次调用，都会在 ~/.endpoint-aiops/audit.db 中生成一条审计记录；可撤销的写入仍会捕获写入前状态，并在存在反向操作时记录该操作。

每个工具都会声明一个 risk_level，并由测试确保它与 [READ]/[WRITE] 文档标签一致；该级别也会作为描述性层级写入审计记录，以便审查者一眼看出某条记录对应的是高风险写入。它只是标签，不是关卡。

正在运行较小的 / 本地模型？请参阅 agent-guardrails.md——其中列出了此工具现在为你执行的护栏（这样你就不用浪费提示词预算重复说明），并提供了剩余部分的现成系统提示词。

载荷约定

• 缺失不等于空。 管理服务器未报告的字段会以 null 返回，而不是 ""——键始终存在，因此不会把缺失的补丁级别误认为空白值。
• 列表被截断时会明确说明。 任何可能被 limit 截短的列表都会采用截断封装：{"items": [...], "returned": N, "limit": L, "truncated": bool}；truncated 是实际测得的，而非推断得出。附带的总数（driftedCount、behindCount、nonCompliantCount、stormCount 和健康状况 summary）始终是完整的、未截断的数值。

快速开始

作为 Claude Code 插件

安装一次，即可同时为 Agent 提供技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install endpoint-aiops@aiops-tools

MCP 服务通过 uv 获取，并固定为此插件声明的软件包版本，因此可以追溯审计记录对应的代码。凭据仍通过 endpoint-aiops init 配置——详见下文。

作为 OpenClaw 插件

相同的软件包也发布在 ClawHub 上，一次安装即可同时获取技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/endpoint-aiops
openclaw skills info endpoint-aiops          # expect: Visible to model: yes

之后重启 OpenClaw 网关，使其加载插件。MCP 服务通过 uv 获取，并固定为此确切版本，因此 uvx 必须位于 PATH 中——如果没有，技能仍会安装，但会报告 Visible to model: no。凭据按下文所述的方式配置。

作为 CLI 或独立 MCP 服务

uv tool install endpoint-aiops          # or: pipx install endpoint-aiops
endpoint-aiops init                     # wizard: add a target + store its API key (encrypted)
endpoint-aiops doctor                   # verify config, secrets, connectivity
endpoint-aiops overview                 # one-shot fleet health
endpoint-aiops session storm            # detect a login storm + slow contributors
endpoint-aiops drift report             # endpoints drifted from the fleet baseline

作为 MCP 服务运行（stdio）：

export ENDPOINT_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
endpoint-aiops-mcp

密码之后会存放在哪里：导出的变量可被此 shell 启动的每个进程读取，也会记录在 shell 历史记录中。在共享主机或长期运行的主机上，建议使用交互式提示，或在需要它的单条命令运行期间从密钥管理器注入密码。

治理

每项操作——无论是 MCP 还是 CLI——都会经过内置的 @governed_tool 处理机制。它负责记录，不负责授权（见上文）。

• 审计 — 每次调用（参数、结果、状态、耗时、风险等级，以及操作员提供的审批人／理由）都会记录到 ~/.endpoint-aiops/audit.db （可通过 ENDPOINT_AIOPS_HOME 更改位置）。CLI 写入的记录与 MCP 路径写入的相同——不存在未经审计的入口。
• 失控保护 — 这是安全后备机制，而非授权门槛：如果在短时间内反复调用同一操作，会触发断路器，防止失控的 Agent 无限消耗调用次数和时间。通过 ENDPOINT_RUNAWAY_MAX=0 禁用；也可选用硬性上限 ENDPOINT_MAX_TOOL_CALLS / ENDPOINT_MAX_TOOL_SECONDS。
• 撤销记录 — 可逆写入会根据获取的变更前状态记录逆向描述符。
• 风险等级 — 根据 risk_level 得出的审计记录描述性标签；不会限制任何操作。

范围

这是 AIops-tools 系列中面向 IT 端点 的成员（具备审计、预算、撤销和风险等级管理的治理型 AI 运维）。 对于 OT／工业边缘（Modbus、OPC-UA、PROFINET，……），请参阅单独的 industrial-aiops 系列。

方言——你实际连接的是哪种服务？

方言是管理服务的 API 形式：资源路径、响应字段名称、传输默认值（端口和 API 基路径），以及身份验证方式。在 config.yaml 中为每个目标设置方言；endpoint-aiops init 会询问方言，并显示配置结果。

方言	传输	身份验证	状态
generic（默认）	443 上的 /api/v2.0	静态 Bearer API 密钥	中性占位项——并非真实供应商 API。 只有在 dialect: 块中描述服务的路径后才有用。
igel-ums	8443 上的 /umsapi/v3	HTTP Basic 登录 → JSESSIONID Cookie	面向 IGEL UMS (IMI) 的文档化但未经验证的方言。这并不表示 IGEL 受支持——请参阅状态。

targets:
  - name: ums1
    host: ums.example.local
    dialect: igel-ums        # IMI paths, port 8443, /umsapi/v3, Basic-login auth
    username: ums-admin      # UMS account; the password lives in secrets.enc
    scheme: https            # or 'http' for a reverse-proxied server
    verify_ssl: false        # self-signed lab UMS only

默认的 generic 不是 IGEL 配置，也从来不是：IGEL 在 8443 的 /umsapi/v3 提供 IMI，因此使用通用形式的目标在首次探测时就会返回 404。这种不匹配正是此预设存在的原因。

如果服务确实没有某项资源，方言会明确说明，而不是猜测 URL——IMI 不提供登录／启动会话资源，因此针对 igel-ums 目标调用 session_list 和 login_storm_analysis 时，会返回一条指出缺失资源的说明性错误，而不是调用虚构的路径。

方言不仅选择路径，也会选择身份验证方案——IMI 会拒绝通用方言发送的静态 Bearer 令牌，因此它会通过 POST /umsapi/v3/login 使用 HTTP Basic 登录，并携带返回的 JSESSIONID Cookie（每个连接登录一次，之后会缓存）。由于身份验证方案由方言决定，凭据错误和方言错误会以不同方式报告：401 错误会指出已提供的方案；如果服务发送了 WWW-Authenticate 挑战，还会指出服务实际要求的方案——这样，方言不匹配就不会让你误以为需要轮换一个完全有效的密钥。

⚠️ IGEL 专项说明：权限不足的 UMS 账户收到的是空列表，而不是 403。endpoint-aiops doctor 会将身份验证作为独立于可达性探测的步骤执行，并在登录成功但未返回任何端点时发出警告，因为“没有设备”和“不允许查看设备”这两种情况原本无法区分。

状态

测试套件基于模拟。本软件包中的任何方言都未在真实管理服务器上进行过测试，因此本软件包不声称支持任何特定产品，包括 IGEL。

• generic 是一种占位结构，不是厂商 API。
• igel-ums 是一种已有文档但未经验证的方言。其路径和字段别名根据 IGEL 发布的 IMI 文档建模；其身份验证方案记录在 IMI 手册中，并且与三个独立的真实 IMI 客户端所用方案一致。本项目从未在设备上运行过其中任何一项——IGEL UMS 没有免费版本，因此维护者无法在自己的硬件上验证。

两者都在 docs/VERIFICATION.md 中标记为 UNKNOWN-pending-live。该文档按实时运行最可能发现的问题排序，并定义了必须涵盖的检查清单。如果你有 UMS 并运行了该清单，非常欢迎通过 issue 提交结果。缺少某项功能或服务器方言？欢迎提交 issue 或 PR——欢迎贡献。