vmware-aria 2.3.0__tar.gz → 2.4.0__tar.gz

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-aria",
   "displayName": "VMware Aria",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 46 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-aria==2.3.0",
+        "vmware-aria==2.4.0",
         "vmware-aria-mcp"
       ]
     }

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-aria
-Version: 2.3.0
+Version: 2.4.0
 Summary: VMware Aria Operations (vRealize Operations) monitoring, alerting, and capacity planning
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Aria
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Aria
@@ -289,11 +289,18 @@ claude mcp add --transport http vmware-aria https://mcp.example.com:8443/mcp \
   before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
 - Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
   --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
 - The audit log records each caller as `token:<name>`. Calls run side by side: each holds its own session to a
   target, up to `VMWARE_MCP_POOL_SIZE` (default 2) sessions per target. Each session is a login on the target; a
   call waits at most 300 s for a free one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level.
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
 
 **Offer only read tools, plus the writes you choose:**
 

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/README-CN.md

@@ -243,10 +243,16 @@ claude mcp add --transport http vmware-aria https://mcp.example.com:8443/mcp \
   证书要用客户端信任、且覆盖这些名字的证书。
 - 在同一台机器上由反向代理终结 TLS 时，用 `--transport http --host 127.0.0.1 --public-name mcp.example.com`，
   并让代理透传 `Authorization` 头。
+- 负载均衡或网关在另一台机器上时，保持 `--transport https`（自签证书也可以），在 `--public-name` 里写上负载均衡
+  转发时带的 `Host` 名，并让它透传 `Authorization`。健康检查可以用 `GET /healthz`：不需要 token，只返回
+  `{"status": "ok"}`（需 vmware-policy ≥ 1.23.0）。
+- 每个请求带上 `traceparent` 或 `X-Request-ID`，它会记进审计记录；用 `vmware-audit log --correlation-id ID`
+  就能查到平台上某一次请求对应的调用。
 - 审计日志把每个调用者记为 `token:<名字>`。调用并行执行：每个调用独占一个到 target 的会话，每个 target 最多
   `VMWARE_MCP_POOL_SIZE`（默认 2）个会话。每个会话都是在 target 上的一次登录；调用最多等待 300 秒拿到空闲会话。
 - **能连到这个端点的人，都以该 server 配置的账号操作。** token 只用来识别调用者，不在平台上授予任何权限。
   每个权限级别单独起一个端点。
+- **一个端点给多人或多种角色用：** 先运行一次 `vmware-audit roles enable`，再给每个 token 指定角色（`vmware-audit token create 名字 --role reader`，或在 `roles.yaml` 里定义可用的工具和 target；需 vmware-policy ≥ 1.24.0）。角色只能限定这个 token 在本端点上能调用什么，不能超出账号本身的权限。详见 vmware-policy README 的「网络调用者的角色」一节。
 
 **只提供读工具，加上你选定的写工具：**
 

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/README.md

@@ -264,11 +264,18 @@ claude mcp add --transport http vmware-aria https://mcp.example.com:8443/mcp \
   before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
 - Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
   --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
 - The audit log records each caller as `token:<name>`. Calls run side by side: each holds its own session to a
   target, up to `VMWARE_MCP_POOL_SIZE` (default 2) sessions per target. Each session is a login on the target; a
   call waits at most 300 s for a free one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level.
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
 
 **Offer only read tools, plus the writes you choose:**
 

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/RELEASE_NOTES.md

@@ -1,3 +1,12 @@
+## v2.4.0 — roles for network callers (HLD §18)
+
+* Declares the role metadata vmware-policy ≥ 1.24.0 needs to apply **roles** to this server over HTTPS
+  (HLD §18): how a missing target resolves, and that `get_api_path` escapes a role (it reads any indexed API path, account and credential listings included). With an older vmware-policy nothing changes. Once an operator runs
+  `vmware-audit roles enable`, a token's role decides which tools and targets it may use here; a refused call is
+  audited as `denied`. See vmware-policy's README, "Roles for network callers".
+* A target-limited role is checked against the same config the connection uses: the copy the server's connection manager loaded on its first connection. Edit `config.yaml` and restart for both to see the change.
+* README and setup guide: one endpoint for several people or roles.
+
 ## v2.3.0 — calls run side by side; read-only raw API escape hatch
 
 **Calls no longer wait for each other** (HLD §16 D-13(2), via vmware-policy 1.22.0). When one server serves several

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-aria==2.3.0",
+        "vmware-aria==2.4.0",
         "vmware-aria-mcp"
       ]
     }

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-aria",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "VMware Aria Operations: metrics, alerts, capacity, anomaly detection — 46 MCP tools.",
   "private": true,
   "license": "MIT",

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-aria"
-version = "2.3.0"
+version = "2.4.0"
 description = "VMware Aria Operations (vRealize Operations) monitoring, alerting, and capacity planning"
 readme = "README.md"
 license = "MIT"

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-Aria",
     "source": "github"
   },
-  "version": "2.3.0",
+  "version": "2.4.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-aria",
-      "version": "2.3.0",
+      "version": "2.4.0",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/skills/vmware-aria/SKILL.md

@@ -49,7 +49,7 @@ VMware Aria Operations (vRealize Operations 8.x, VCF Operations 9.x) AI-assisted
 ## Quick Install
 
 ```bash
-uv tool install vmware-aria==2.3.0
+uv tool install vmware-aria==2.4.0
 vmware-aria init      # guided setup: writes config + .env (chmod 600, password grep-safe), then verifies
 vmware-aria doctor
 ```
@@ -306,7 +306,7 @@ Set `VMWARE_ARIA_<TARGET_NAME_UPPER>_PASSWORD` (hyphens become underscores; targ
 
 ### `invalid peer certificate: UnknownIssuer` when running uvx (corporate TLS proxy)
 
-`uvx` re-resolves from PyPI on every launch, and a TLS-intercepting proxy breaks that. Run `vmware-aria mcp` after `uv tool install vmware-aria==2.3.0` (no network on launch), or set `UV_NATIVE_TLS=true` to use the system cert store.
+`uvx` re-resolves from PyPI on every launch, and a TLS-intercepting proxy breaks that. Run `vmware-aria mcp` after `uv tool install vmware-aria==2.4.0` (no network on launch), or set `UV_NATIVE_TLS=true` to use the system cert store.
 
 ## Audit & Safety
 

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/skills/vmware-aria/references/setup-guide.md

@@ -16,19 +16,19 @@ Complete setup and security guide for `vmware-aria`.
 ### Via uv (recommended)
 
 ```bash
-uv tool install vmware-aria==2.3.0
+uv tool install vmware-aria==2.4.0
 ```
 
 ### Via pip
 
 ```bash
-pip install vmware-aria==2.3.0
+pip install vmware-aria==2.4.0
 ```
 
 ### From source
 
 ```bash
-git clone --branch v2.3.0 https://github.com/vmware-skills/VMware-Aria.git
+git clone --branch v2.4.0 https://github.com/vmware-skills/VMware-Aria.git
 cd VMware-Aria
 pip install -e .
 ```
@@ -194,7 +194,7 @@ Add to `~/.claude.json` (or use `claude mcp add`):
 
 > v1.5.15+ recommends `vmware-aria mcp`. Pre-1.5.15 used the legacy
 > `vmware-aria-mcp` console script (still kept for backward compatibility).
-> If using `uvx --from vmware-aria==2.3.0 vmware-aria mcp` and you hit
+> If using `uvx --from vmware-aria==2.4.0 vmware-aria mcp` and you hit
 > `invalid peer certificate: UnknownIssuer` behind a corporate TLS proxy,
 > set `UV_NATIVE_TLS=true` or use the recommended form above.
 
@@ -253,6 +253,13 @@ vmware-aria mcp --transport https --host 0.0.0.0 --port 8443 \
 - Behind a reverse proxy that terminates TLS (Nginx, HAProxy) on the same machine, use
   `--transport http --host 127.0.0.1 --public-name mcp.example.com` (the names the proxy forwards in `Host`), and
   have the proxy pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine: the balancer is the client that has to trust it), list in `--public-name` the host name the balancer sends
+  as `Host`, and have it forward `Authorization`. Point its health probe at `GET /healthz`: it needs no token, returns
+  only `{"status": "ok"}` and accepts any `Host` (vmware-policy ≥ 1.23.0). Every other path still needs the token.
+- Correlation: each audit row stores the caller's `traceparent` trace-id, else its `X-Request-ID` /
+  `X-Correlation-ID`. Have the agent platform send one, and `vmware-audit log --correlation-id ID` lists the calls
+  behind one platform request.
 - `vmware-audit token list` / `token revoke NAME` manage callers; a revoked token is refused from its next request.
   Replace a leaked token under a new name.
 - The server will not start without at least one token, and checks before it binds that unauthenticated requests
@@ -263,6 +270,7 @@ vmware-aria mcp --transport https --host 0.0.0.0 --port 8443 \
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level (for example a read-only account behind
   `--expose read`, and a separate endpoint for operators).
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
 
 ## Docker Deployment
 

vmware_aria-2.4.0/tests/test_policy_roles.py

@@ -0,0 +1,55 @@
+"""HLD §18: the role metadata this skill declares matches its real tools."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from vmware_aria import policy_roles
+
+
+def _registry() -> set[str]:
+    from vmware_aria.mcp_server.server import mcp
+
+    return {t.name for t in asyncio.run(mcp.list_tools())}
+
+
+@pytest.mark.unit
+def test_every_declared_name_is_a_real_tool():
+    named = set(policy_roles.ESCAPES) | set(getattr(policy_roles, "AKO_TOOLS", ()))
+    assert named - _registry() == set(), sorted(named - _registry())
+
+
+@pytest.mark.unit
+def test_metadata_is_declared_when_policy_has_roles():
+    roles = pytest.importorskip("vmware_policy.roles")
+    import vmware_aria.mcp_server.server  # noqa: F401  (registers the metadata on import)
+
+    meta = roles.metadata("aria")
+    assert meta is not None and meta.version == 1
+    assert meta.escapes == policy_roles.ESCAPES
+    assert (meta.resolver is not None) is True
+
+
+@pytest.mark.unit
+def test_the_resolver_uses_the_config_the_connection_manager_holds(monkeypatch):
+    """Review H1/H-1: once the server's connection manager exists, a config edit must
+    not move the role check off the config it connects with; before, read the file."""
+    import importlib
+    import types
+
+    from vmware_aria import policy_roles as pr
+
+    server = importlib.import_module("vmware_aria.mcp_server._shared")
+    assert hasattr(server, "_conn_mgr"), "policy_roles looks up a global the server does not have"
+    edited, loads = object(), []
+    monkeypatch.setattr(pr, "load_config", lambda: loads.append(1) or edited)
+
+    monkeypatch.setattr(server, "_conn_mgr", None)
+    assert pr._connection_config() is edited and pr._connection_config() is edited
+    assert len(loads) == 2  # no manager yet: the file as it is now, every time
+
+    held = object()
+    monkeypatch.setattr(server, "_conn_mgr", types.SimpleNamespace(_config=held))
+    assert pr._connection_config() is held  # the manager's copy, not the edited file

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/uv.lock

@@ -1142,7 +1142,7 @@ wheels = [
 
 [[package]]
 name = "vmware-aria"
-version = "2.3.0"
+version = "2.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
@@ -1181,14 +1181,14 @@ dev = [
 
 [[package]]
 name = "vmware-policy"
-version = "1.22.0"
+version = "1.24.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pyyaml" },
     { name = "rich" },
     { name = "typer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/d7/52/405a9d5e88d79649f4d7bddade8248f38ab6a508007a7500a3cdcf81897a/vmware_policy-1.22.0.tar.gz", hash = "sha256:e1a96b44ddf3c4d00fb8bdcaae4e1a059b03f343a84df9de23f865122d3dc280", size = 319890, upload-time = "2026-10-15T14:39:45.757Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/4a/62/3a3cb83af77e3dd3c8fc92cb3b7968bfda04a2f71bf0d6f9b72ee3198441/vmware_policy-1.24.0.tar.gz", hash = "sha256:fba12732ccbd4371232c15d9fd014f9f5d697497210aedff2515d1d205ed3577", size = 361302, upload-time = "2026-10-16T07:18:28.317Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/73/b5/2536cc8750c3ecb0a57c573def664989642ccae1a4f4a8b4283e34877721/vmware_policy-1.22.0-py3-none-any.whl", hash = "sha256:ca8afc5731e926b5eb1b93e26e14763b477bd45c33d3808138fb72903e2af664", size = 108585, upload-time = "2026-10-15T14:39:43.888Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/f2/fe3d9d384712023916e2cacddc385f14b095509c5e00aea417d1a9550e98/vmware_policy-1.24.0-py3-none-any.whl", hash = "sha256:cf615d0256134f01fb84c39b083649281a66d2c064c2eaa28786a0fa95ec6e58", size = 131460, upload-time = "2026-10-16T07:18:26.907Z" },
 ]

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/vmware_aria/__init__.py

@@ -1,3 +1,3 @@
 """VMware Aria Operations (vRealize Operations) monitoring and capacity planning."""
 
-__version__ = "2.3.0"
+__version__ = "2.4.0"

{vmware_aria-2.3.0 → vmware_aria-2.4.0}/vmware_aria/policy_environment.py

@@ -38,3 +38,7 @@ def _environment_for(target: str | None) -> str:
 # to ALLOW. Keyed, a resolver only ever answers for its own skill, so
 # registering at import time is safe again.
 set_environment_resolver(_environment_for, skill=skill_name(__name__))
+
+
+# Role metadata (HLD §18) is declared beside the environment resolver, on every surface.
+import vmware_aria.policy_roles  # noqa: F401

vmware_aria-2.4.0/vmware_aria/policy_roles.py

@@ -0,0 +1,57 @@
+"""What vmware-policy needs to apply roles to this skill (HLD §18 D-21/D-22).
+
+Policy cannot see which tools escape a role or how a missing target resolves; this
+module declares them. Imported by ``policy_environment``, so the MCP server and
+the CLI both register it. With a vmware-policy that has no roles module (< 1.24)
+nothing is declared.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from vmware_policy import skill_name
+
+from vmware_aria.config import load_config
+
+#: Tools that give their holder more than a role. get_api_path reads any indexed API
+#: path, including account and credential listings. Host-path tools are added by policy
+#: while a file root is set.
+ESCAPES = frozenset(
+    {
+        "get_api_path",
+    }
+)
+
+
+def _connection_config():
+    """The config the connection layer uses for this call (review H1, then H-1).
+
+    The server's connection manager loads the config once, on its first connection,
+    and keeps it. Once it exists, the role is checked against that same object, so
+    an edit to config.yaml cannot move the check off the target the call connects
+    to. Before it exists, the file as it is now is what the manager is about to load.
+    Looked up in ``sys.modules`` so the CLI never imports the MCP server.
+    """
+    server = sys.modules.get("vmware_aria.mcp_server._shared")
+    manager = getattr(server, "_conn_mgr", None) if server is not None else None
+    return manager._config if manager is not None else load_config()
+
+
+def _target_name(target: str | None) -> str:
+    """The target the connection layer would use for ``target`` (or the default)."""
+    config = _connection_config()
+    return config.get_target_strict(target or config.default_target or "").name
+
+
+try:
+    from vmware_policy.roles import declare_role_metadata
+except ImportError:  # vmware-policy without roles: nothing to declare
+    declare_role_metadata = None
+
+if declare_role_metadata is not None:
+    declare_role_metadata(
+        skill_name(__name__),
+        escapes=ESCAPES,
+        resolver=_target_name,
+    )