rustmistmcp

rustmistmcp

面向 HPE Juniper Mist 云的异步 Rust Model Context Protocol 服务
mechub 项目 — 自主可控的网络安全自动化

非官方社区项目。 这是一个独立的社区项目， 不声称与 Hewlett Packard Enterprise 或 Juniper Networks 存在关联，也未获其认可。产品名称和商标仅用于 标识本软件可互操作的系统。

---

rustmistmcp 将 Juniper Mist 云中的组织、站点、AP、交换机、 网关、WLAN、客户端、SLE 和 Marvis 暴露给 MCP 客户端，提供范围受限、 可审计的工具界面。

rustjunosmcp 通过 NETCONF 与各个 SRX 设备通信，而 rustpanosmcp 通过 XML-API 与 各个 PAN-OS 防火墙通信；本服务则连接到一个多租户云控制平面。一次按组织范围限定的调用即可访问整个网络中的每个站点和每个接入点，因此范围限定、响应有界和变更控制并非点缀， 而是设计核心。

功能目标是实现 nowireless4u/hpe-networking-mcp 中 Mist 相关部分——站点健康状况和 SLE、设备清单和统计信息、WLAN/SSID 管理、客户端 连接、事件和警报、审计日志、RRM 和恶意设备检测、固件、 NAC/策略、访客访问、webhook、楼层平面图和 Marvis——在 mecmcp 基础上用 Rust 重新实现，而不是采用 Python 的规范驱动注册表。 该项目注册了约一千个生成的工具；而本项目会有意避免这种做法。重新实现的核心目的， 正是提供一套经过精选、范围明确且有独立文档说明的工具界面。

与 mecmcp 的关系

mecmcp 是 mechub MCP 服务系列共享的厂商中立 Rust 基础框架。本仓库是该基础框架的使用者，而不是其分支：

关注点	所在位置
令牌签发/摘要生成/验证、tokens.json、范围、授权、调用方上下文	mecmcp-auth
归因、审计事件、脱敏、接收端	mecmcp-audit
Streamable-HTTP 传输、主机/Origin 检查、速率和并发限制	mecmcp-transport
CLI 基础结构、TLS 引导、信号处理、平滑关闭	mecmcp-runtime
变更控制：计划 → 摘要 → 批准 → 应用 → 验证	mecmcp-changeset
组织/站点/租户注册表	mecmcp-inventory
Mist REST 客户端、API 令牌认证、响应模型、工具界面	本仓库

所有非 Mist API 特有的内容都属于上游。如果你发现自己在此处编写通用认证或传输代码， 那它就应该属于 mecmcp。 目前没有临时例外：docs/UPSTREAM_COMPATIBILITY.md 中的记录—— 一个 Mist 专用的令牌生命周期适配器——在满足移除条件后已被删除。任何新的例外都必须记录在该文件中，并注明客观的移除条件。

API

Mist 在 /api/v1 下提供版本化 REST API，通过各区域的云端点提供服务。组织的主区域决定主机地址：

区域	端点
Global 01	api.mist.com
EU 01	api.eu.mist.com
GovCloud	api.gc1.mist.com

此外还存在其他区域云；权威列表见 Juniper 的 API Endpoints and Global Regions 表格。区域必须由操作员配置，不能靠猜测。

Mist 厂商 API 支持 API 令牌和外部 OAuth 2.0。API 令牌通过 Authorization: Token <token> 发送，可按用户或组织签发，并继承创建令牌的账户权限。rustmistmcp v1 有意仅实现 API 令牌认证，不接受 OAuth 凭据。使用 Juniper Mist 登录凭据进行 HTTP Basic 认证的方式将于 2026 年 9 月弃用，本项目不会实现该方式。

主要参考资料：

• RESTful API 概述
• 创建 API 令牌
• Mist API 参考

在客户端代码落地之前，我们会直接对照实时 API 参考文档，核验具体的端点映射、分页和速率限制语义。本 README 不会复述未经核实的接口内容。

状态

基础功能已构建；通过只读实时租户验收。 工作区包含经过审计的操作目录、严格的配置档元数据、授权模型，以及与目录绑定的 MistClient 契约，可验证 Mist 操作输入，并将不透明游标绑定到已配置的源。mecmcp#90 已关闭，因此生产路径中的 MistHandler::from_config 会构建 HttpMistClient，即基于 mecmcp-http 的具体 HTTPS 实现。

实验室部署已连接到真实 Mist 组织。2026-08-10，通过绑定到回环地址的端点和受授权范围限制的 bearer 令牌，get_mist_self（getSelf）、get_mist_org（getOrg）和 list_mist_sites（listOrgSites）均在 92–325 ms 内返回了租户数据，且 result: ok。这是 issue #11 的验收关卡，目前已通过。

以下事项尚未完成，不得描述为已完成：

• 这次运行不代表完整的打包验收。 测试仅限回环地址，未启用 TLS，且只涉及一个组织、一个令牌和三个读取工具。docs/PACKAGING_ACCEPTANCE.md 中的检查清单——TLS 主机名和证书链、拒绝匿名请求和无效 bearer 令牌、严格执行 Host/Origin——尚未完成。
• 启动时未执行 /api/v1/self 身份探测。 get_mist_self 工具可用于实时租户，但启动期间不会探测 /self，且 LIVE_MIST_BLOCKER 仍指出这一缺口。
• 仅针对第一批 WAN 边缘对象提供变更操作。 第一批支持为网络、服务、服务策略、网关模板和设备配置档创建和更新操作，且只能通过 plan → digest → approve → apply 生命周期执行。删除操作以及 mist_configured 设备配置档的分配/取消分配仍无法执行。尚未对实时租户执行 apply。

未配置凭据时构建的处理器会使用 BlockedMistClient，不会执行任何 I/O；它拒绝请求时返回的消息为 LIVE_MIST_BLOCKER。

站点发现

站点范围工具会拒绝处理处理程序尚不认识的站点（参见“API”）。服务器启动时，会为每个允许列表中的组织调用 listOrgSites，填充映射后才开始提供服务。--site-refresh-interval-secs（默认值为 300）用于控制后台任务的重复间隔，因此无需重启即可发现 Mist 端新增或移除的站点；设为 0 时会禁用后台任务，仅在启动时发现一次。

此刷新任务会针对运维人员配置的 Mist 源站进行空闲轮询——每隔 site-refresh-interval-secs 请求一次 listOrgSites，与工具流量无关，并使用其他读取操作共用的、经过目录验证的 MistClient。由于这是会更新服务器内部状态的读取操作，而非由客户端发起的调用，因此不会记录在单个工具的审计轨迹中。刷新期间，若某个组织的请求失败或达到已跟踪站点数上限，会保留该组织先前已知的站点，而不会将其清除；这不会影响其他组织的站点。

此处会复用共享的 TokenSecret、取消和变更集原语，而不是重新构建。Mist 标头名称、目录策略、请求／响应架构、终态、重试分类和部署仍保留在此代码库中。

预发布打包与部署边界

仓库中签入的 Docker、归档文件、systemd 和 LXC 资产仅用于预发布打包。基于这些资产构建的实验室 LXC 曾处理过实际的只读租户流量（issue #11），但这并不等同于通过打包验收：该次运行未使用 TLS，也未绑定到 loopback 以外的地址，因此 docs/PACKAGING_ACCEPTANCE.md 中关于 TLS、Host/Origin 和无效 bearer 的检查项仍未验证。/api/v1/self 启动探测尚未实现，且变更仅适用于受变更集生命周期管理的 batch-1 WAN 边缘对象；尚未对实际租户执行过应用操作。在该检查清单完成前，不得宣称已发布 v1。

OCI 镜像采用多阶段构建，使用固定摘要的 Rust 构建器和固定摘要的 distroless Debian 13 运行时。它仅以 UID/GID 65532 运行 /usr/local/bin/rustmistmcp；运行时镜像不含 shell、包管理器或运行时下载器。CA 数据来自 distroless 基础镜像。请使用不可变的镜像摘要，切勿使用可变标签。提供的 compose 示例为只读配置，会移除所有 capability、启用 no-new-privileges、限制 PID 和 /tmp，以只读方式挂载 /etc/rustmistmcp，并以读写方式挂载 /var/lib/rustmistmcp。请勿将 Mist 密钥或 bearer 密钥放入镜像层、compose 环境变量或命令参数中。

仓库中签入的服务和 OCI 命令采用共享 CLI 的精确 loopback HTTP 契约：/etc/rustmistmcp/mist.json、bearer 存储、端口 30030、使用 HMAC 脱敏的 JSON 审计，以及 systemd 的直接 journald 日志投递。OCI 审计日志输出为 JSON 格式的 stderr，且不会挂载主机的 journal 套接字。没有变更状态标志，也没有对实时 Mist 的就绪状态检查。mecmcp#159 已关闭，现在 --version 会报告该二进制文件的名称和版本，因此应通过 --version、--help、BUILD-INFO 以及制品和已部署版本的 SHA-256 值来验证发布身份。

compose 示例仅适用于 Linux：host 网络使容器的 127.0.0.1:30030 监听端口可从同一主机访问，而不会暴露到外部网络接口。启动前，请确保以绑定挂载方式提供的状态文件和密钥文件可由数字 UID/GID 65532 访问：

install -d -m 0750 packaging/container/runtime
install -d -m 0700 packaging/container/state
cp examples/mist.example.json packaging/container/runtime/mist.json
printf '%s\n' '{"version":1,"tokens":[]}' > packaging/container/state/tokens.json
install -m 0600 /dev/null packaging/container/runtime/mist-api-token
# Populate this before starting Compose; it is mounted at the path referenced
# by mist.json and must never be put in an environment variable or command.
read -sp 'Mist API token: ' token && printf '%s' "$token" > packaging/container/runtime/mist-api-token && unset token
# Mint the bearer token into the state mount before starting Compose. The
# secret is printed once; store it in the client that will call this server.
rustmistmcp token add --tokens-file packaging/container/state/tokens.json \
  --name my-client --devices '*' --tools '*' \
  -f packaging/container/runtime/mist.json
# Set modes before ownership so the files remain 0600 after chown.
chmod 0600 packaging/container/runtime/mist-api-token packaging/container/state/tokens.json
sudo chmod 0640 packaging/container/runtime/mist.json
sudo chown root:65532 packaging/container/runtime/mist.json
sudo chown 65532:65532 packaging/container/runtime/mist-api-token \
  packaging/container/state/tokens.json
sudo chown -R 65532:65532 packaging/container/state
sudo chown root:65532 packaging/container/runtime
RUSTMISTMCP_IMAGE='ghcr.io/mechubsec/rustmistmcp@sha256:<verified-64-hex-digest>' \
  docker compose -f packaging/container/compose.example.yaml up

在将所有权交给 UID/GID 65532 并运行 up 之前，先填入 Mist API token。所有权移交后，非特权操作员将无法再写入该文件，而且凭据加载器会在启动时拒绝空 token。请勿通过环境变量、命令参数、镜像层或 Compose 文件传递该值。

带授权的 MCP bearer token 添加、列出、撤销和轮换操作均由共享的 token_cmd::run_with_grant 执行。曾用于桥接这些操作的私有 Mist 类型适配器已删除。通过 token add 创建的新 token 不含授权；共享命令会保留现有且经过验证的 MistGrant 值。此 bearer token 存储与出站客户端使用的 Mist API token 相互独立。

Docker 容器指南

请参阅 docs/HOW-TO-SETUP-DOCKER.md，了解在 Docker 中运行 rustmistmcp 的分步说明，包括审计配置要求以及双人模式与实验室模式的设置。

LXC 操作员先决条件

请参阅 docs/HOW-TO-SETUP-LXC.md，了解分步构建指南。

安全审查文档

• docs/THREAT_MODEL.md — 信任边界、安全主体、令牌或 Agent 遭到入侵后对真实 Mist 组织造成的影响范围，以及已采取和计划实施的缓解措施。
• docs/TOKEN_ROLE_GUIDANCE.md — 说明为何出站 Mist API token 应使用专用、遵循最小权限原则的组织级 token，而非个人 token 或超级管理员 token。 仅部署在专用的 Debian 13 非特权 LXC（设置 nesting=1） 中。 目标 systemd 版本需要 nesting=1 才能报告挂载状态正常。 来宾系统无法证明主机端的非特权和嵌套设置。请在经授权的主机清单中核实这些设置，然后通过 RUSTMISTMCP_LXC_HOST_PROOF=unprivileged=1,nesting=1 向安装程序明确声明；安装程序也会拒绝非 Debian 13 和非 LXC 主机。 构建软件包时，不要联系 Proxmox 或 Mist 租户。如果另行授权了实验室验收门禁，必须先证明 VMID 613 及其地址未被占用，并且只能针对新配置的 613 LXC；绝不能操作 VMID 612，也不能对无关来宾系统创建快照。

归档安装程序会在进行任何更改前验证校验和及完整归档布局，拒绝覆盖现有配置、密钥、状态或自定义单元（除非设置了 RUSTMISTMCP_FORCE_UNIT=1），并且不会启用服务。无需 root 权限即可使用 packaging/lxc/install.sh --validate-only ARCHIVE ARCHIVE.sha256 进行不会产生更改的预检。 它会将非实时示例安装到 /etc/rustmistmcp/mist.example.json 和 /etc/rustmistmcp/tokens.example.json。请手动配置实时文件：

路径	所需所有权/模式	用途
/usr/local/bin/rustmistmcp	root:root，0755	发布二进制文件
/etc/rustmistmcp/mist.json	root:rustmistmcp，0640	服务可读取的 Mist 配置文件
/etc/rustmistmcp/mist-api-token	rustmistmcp:rustmistmcp，0600	v1 出站 Mist API 凭据
/var/lib/rustmistmcp/tokens.json	rustmistmcp:rustmistmcp，0600	Bearer 令牌存储
/etc/rustmistmcp/audit-hmac.key	rustmistmcp:rustmistmcp，0600	审计 HMAC 密钥
/var/lib/rustmistmcp/changeset-state.json	服务用户状态，父目录权限为 0700	持久化状态路径

持久化 journald 的容量上限为 512 MiB。在处理真实流量前，请配置远程日志/SIEM 转发。文件审计启动采用失败关闭策略（mecmcp#158）：无法打开 --audit-log-file 时会导致启动失败，而不会静默降级；journald 仍是基本日志交付方式。已接入 HTTP 优雅关闭（mecmcp#156）——SIGTERM 和 SIGINT 会取消监听器，监听器会等待最多 10 秒以处理完正在进行的请求——但这是已配置的行为，并非经过负载验证的排空机制。任何外部绑定都必须配置 TLS，并精确设置允许的 Host 和 Origin；默认部署方式仅绑定回环地址。

对于每个候选发布版本，都应从干净的工作树运行 scripts/build-release.sh 构建；该脚本会生成确定性的 rustmistmcp-v<VERSION>-<TARGET_TRIPLE>.tar.gz、随附的 SHA-256 校验和及 BUILD-INFO。部署前，请测量生成的二进制文件所需的最低 glibc 版本：

objdump -T bin/rustmistmcp | grep -oE 'GLIBC_[0-9]+\.[0-9]+' | sort -Vu | tail -1

发布 CI 会生成校验和、SBOM、来源证明、linux/amd64 OCI 镜像以及不可变的摘要记录。在 RC 阶段刷新上游参考资料/规范，重新生成目录并审查差异；任何单独的部署验收开始前，都必须确保不存在任何对等差异。

接下来按顺序执行：

1. 实现 /api/v1/self 启动身份探测。它所需的出站 HttpMistClient 已随 mecmcp#90 合入，而 get_mist_self 工具已证明该调用可在实时组织环境中正常工作。
2. 完成 docs/PACKAGING_ACCEPTANCE.md 的其余部分——TLS、非回环地址绑定时的 Host/Origin 强制校验，以及拒绝匿名请求和无效 Bearer 令牌；问题 #11 中的只读回环运行未测试这些内容。
3. 仅通过 mecmcp-changeset 添加变更，绝不能直接写入。该设计在问题 #14 中提出；execute 拆分已作为 execute_class.rs 合入。

设计承诺

• 精心策划，而非自动生成。 工具由人工挑选并编写文档。一千个自动注册的端点只会把搜索难题丢给模型，并不代表具备相应能力。
• 先读后写。 每个变更工具都只能通过“计划 → 摘要 → 批准 → 应用”的生命周期调用。任何工具都不会在未经确认的单次调用中写入组织。
• 令牌范围明确。 Bearer 令牌带有明确的工具、组织和站点范围；未限定范围的令牌属于配置错误，而非便利功能。
• 限制 I/O。 请求和响应大小均设有上限。云控制平面可能会轻易返回规模庞大的负载，但服务不会。
• 从设计上确保可审计。 调用方归属信息和脱敏由 mecmcp-audit 提供，因此每次调用都可追溯到调用方，且不会将凭据泄露到日志中。
• 仓库中不存放机密信息。 Mist API 令牌存储在由运维人员管理、位于版本控制之外的文件中。v1 不接受 OAuth 客户端密钥。
• 设备机密信息在模型看到之前进行脱敏。 Mist 返回的 WLAN PSK、RADIUS/SNMP 共享密钥以及 API 密钥/令牌，都会通过 mecmcp-redact 在每次面向模型的读取、变更集预览和计划响应中移除。这是对已知凭据特征字段进行的拒绝名单匹配，并非加密保证——对于拒绝名单尚未覆盖的字段形式，只能尽力防护；请勿将其视为可在自由格式字段中安全存储机密信息的地方。

WAN 边缘工具

服务器提供经过筛选的只读接口，涵盖组织、站点、设备、WLAN、客户端、SLE、事件和诊断。下面列出的 WAN 边缘子集面向 SRX/SSR 网关及其覆盖网络连接。完整工具注册表请参见 crates/rustmistmcp/src/server/mod.rs 中的 KNOWN_TOOLS。

工具	描述
apply_mist_change_set	将已批准的变更集应用到 Mist。验证审批、检查漂移、执行变更并验证结果。
approve_mist_change_set	为计划的变更集授予第二位负责人审批。审批人必须与所有者不同。
get_mist_change_set	检查暂存的变更集，并返回其状态、所有者、变更前后内容及审批状态。before/after 中包含密钥的字段（PSK、共享密钥、API 密钥/令牌）会被隐藏；结构字段和非机密元数据会保留。
get_mist_sle_impact	获取受某项站点 SLE 指标影响的网关、应用，或影响摘要。
get_mist_wan_config	按 ID 获取单个 WAN 边缘配置对象。包含密钥的字段（网关模板隧道 PSK、共享密钥、API 密钥/令牌）会被隐藏；结构字段和非机密元数据会保留。
get_mist_wan_edge_stats	获取站点的 WAN 边缘网关指标，或单个网关的洞察指标。
list_mist_applications	列出站点上检测到的应用、统计应用数量，或列出网关应用目录。
list_mist_wan_config	列出 WAN 边缘配置对象：网络、服务、服务策略、网关模板或设备配置文件。包含密钥的字段（网关模板隧道 PSK、共享密钥、API 密钥/令牌）会被隐藏；结构字段和非机密元数据会保留。
list_mist_wan_edges	列出组织或站点中的 WAN 边缘网关（SRX/SSR）。
plan_mist_change	为 WAN 边缘配置对象（网络、服务、服务策略、网关模板或设备配置文件）暂存变更集。返回一个绑定摘要的计划，可供审批。数组会整体替换；null 会删除字段。返回的 before/after 中包含密钥的字段会被隐藏（计划/应用生命周期本身使用未隐藏的值）。
search_mist_bgp_peers	搜索组织或站点中的 WAN 边缘 BGP 对等体统计信息，或统计其数量。
search_mist_peer_paths	搜索 SD-WAN 覆盖网络对等体路径统计信息，或按某个不同字段统计数量。
search_mist_service_path_events	搜索站点的 WAN 边缘服务路径事件，或统计其数量。
search_mist_tunnels	搜索 WAN 边缘 IPsec 隧道统计信息，或按某个不同字段统计数量。

将审计日志转发到事件存储

审计记录不会保留在此主机上。此服务器遵循该系列标准 — AUDIT-FORWARDING-STANDARD.md。

仅存在于生成审计记录的机器上的记录不构成审计追踪：它只是某台设备上的日志文件，而设备操作员正是记录所涉及的一方。

发出记录（当前生效）

--audit-format json \
--audit-log-file /var/lib/rustmistmcp/audit.jsonl

必须使用 JSON。text 格式供在终端中阅读，不可作为解析目标。该文件是面向操作员的产物，必须进行轮换 — 服务器绝不会截断该文件。

传输（已指定，尚未实现）

记录会根据 SSDF 合并后的证据约定，直接写入 SSDF 的 ssdf.audit，作为哈希链式行，因此删除或编辑行都可被检测到。追踪记录见 mecmcp#292。

我们曾设计一条成本更低的 syslog 路径，但最终否决了：它虽然可用，但记录没有链式关联，而这里的其他每个环节都在设计上具有防篡改能力——计划摘要绑定审批，审批记录明确标识不同的主体，token_verified_fields 则将有凭证支持的来源信息与声明信息区分开来。若最后一跳不采用链式关联，就会恰恰在审计人员最需要保障的地方丢掉这一保证。相关理由已记录在标准中。

读取结果

token_verified_fields 列出了由令牌提供凭证的来源字段。该组中的其余字段——client_name、model_id、session_id——由客户端声明，且没有任何认证依据。请勿将它们视为等同。

request_id 用于关联传输事件、处理程序事件，以及（在 Junos 上）设备提交注释。

许可证

根据 MIT 许可。

--lab-mode

--lab-mode 可免除第二个主体的要求，适用于单人操作的实验环境；在这种环境中，两人控制只是走过场，而非真正的控制。默认关闭，任何重要的环境中都应保持关闭。

其影响如下：

• 创建变更集时会自动应用豁免。没有豁免工具，流程仍为 prepare → apply，与生产环境相同。
• 规划、计划摘要、漂移检测和应用时重新验证仍会执行。实验室模式移除的是第二位审核者，而不是变更记录。
• **绝不会伪造审批者。**豁免的变更集会在审批记录中记录 approver: null，并同时记录 waived: { reason: "lab-mode" }。在加密层面，它与真正的双人审批可明确区分，且事后无法重新标记——如果日后有人需要证明哪些变更真正实现了职责分离，这一点至关重要。
• 启用后，服务启动时会发出醒目警告。

如果你想在不豁免控制要求的情况下独自测试写入操作，可以创建两个名称不同的令牌，一个用于准备，另一个用于审批：主体由令牌名称确定，并且系统会拒绝自我审批。这样一人即可完成整个生命周期，同时保留控制要求；只要审批流程仍有任何价值，这就是更好的选择。

启用方法

将标志添加到服务单元中。通过软件包安装时，请使用 drop-in 文件，而不要编辑随软件包提供的单元，以免升级时意外移除该标志：

sudo systemctl edit rustmistmcp

替换 ExecStart 意味着必须完整重述其内容，因此请复制随软件包提供的命令并追加该标志，不要改写成较短的命令：

[Service]
# Clear the shipped ExecStart before replacing it; systemd appends otherwise.
ExecStart=
ExecStart=/usr/local/bin/rustmistmcp \
    --device-mapping /path/to/mist-profile.json \
    --transport streamable-http \
    --host 127.0.0.1 \
    --port 30030 \
    --tokens-file /path/to/tokens.json \
    --lab-mode

sudo systemctl daemon-reload && sudo systemctl restart rustmistmcp

检查审计日志中的启动警告，确认该设置已生效：

sudo journalctl -u rustmistmcp --since "1 minute ago" | grep -i "lab mode"

你应看到：lab mode enabled: change sets are approved on creation with no second principal. Records carry approval_waiver=lab-mode. Do not run this against production devices.