vmware-aiops 2.3.0__tar.gz → 2.3.2__tar.gz

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-aiops",
   "displayName": "VMware AIops",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "AI-powered VMware vCenter/ESXi VM lifecycle and deployment with 61 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/.mcp.json

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

vmware_aiops-2.3.0/README.md → vmware_aiops-2.3.2/PKG-INFO

@@ -1,3 +1,27 @@
+Metadata-Version: 2.5
+Name: vmware-aiops
+Version: 2.3.2
+Summary: VMware vCenter/ESXi AI-powered VM lifecycle and deployment tool
+Project-URL: Homepage, https://github.com/vmware-skills/VMware-AIops
+Project-URL: Repository, https://github.com/vmware-skills/VMware-AIops
+Project-URL: Issues, https://github.com/vmware-skills/VMware-AIops/issues
+Project-URL: Changelog, https://github.com/vmware-skills/VMware-AIops/blob/main/RELEASE_NOTES.md
+Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: apscheduler<4.0,>=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.28
+Requires-Dist: pyaml<27.0,>=24.0
+Requires-Dist: python-dotenv<2.0,>=1.0
+Requires-Dist: pyvmomi<10.0,>=8.0.3.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: vmware-monitor<3.0,>=2.3.1
+Requires-Dist: vmware-policy<2.0,>=1.23.1
+Description-Content-Type: text/markdown
+
 <!-- mcp-name: io.github.vmware-skills/vmware-aiops -->
 # VMware AIops
 
@@ -436,6 +460,9 @@ Run `vmware-aiops plan list` to see failed plan status. Ask user if they want to
 1. Verify target is reachable: `vmware-aiops doctor`
 2. For self-signed certs: set `verify_ssl: false` in config.yaml (lab environments only)
 
+### `doctor` reports "no vSphere role", or every command fails with "session is not authenticated"
+The account logs in but has no vSphere role, so vCenter gives it no session (AIops#47). Assign it a role (Read-Only or higher) on the vCenter root folder: Administration > Access Control > Global Permissions. Changing the password will not help. `vmware-aiops doctor` reports this case by name, and `attention` counts such a target as unread (overall at least WARN).
+
 ---
 
 ## Supported AI Platforms
@@ -1164,6 +1191,15 @@ claude mcp add --transport http vmware-aiops 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.
+- Tools that read or write files on this server (here: guest file upload/download, OVA and deployment-spec files) never touch its configuration, tokens, audit log or
+  TLS key, and over the network they are off unless `VMWARE_MCP_FILE_ROOT` names a directory for them
+  (vmware-policy ≥ 1.23.1).
 - The audit log records each caller as `token:<name>`. Calls run side by side, with up to `VMWARE_MCP_POOL_SIZE`
   (default 2) sessions per target; each session is a login on the target, and a call waits at most 300 s for one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/README-CN.md

@@ -379,6 +379,9 @@ vSphere 中 VM 名称区分大小写。请使用 `vmware-monitor inventory vms`
 1. 验证目标可达：`vmware-aiops doctor`
 2. 自签名证书：在 config.yaml 中设置 `verify_ssl: false`（仅限实验环境）
 
+### `doctor` 报 "no vSphere role"，或所有命令都报 "session is not authenticated"
+账号能登录，但没有任何 vSphere 角色，所以 vCenter 不给它会话（AIops#47）。在 vCenter 根文件夹上给它分配角色（Read-Only 或更高）：Administration > Access Control > Global Permissions。改密码没有用。`vmware-aiops doctor` 会直接报出这种情况，`attention` 也会把这样的目标算作未读取（总体状态至少为 WARN）。
+
 ---
 
 ## 支持的 AI 平台
@@ -829,6 +832,13 @@ claude mcp add --transport http vmware-aiops 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`
+  就能查到平台上某一次请求对应的调用。
+- 会读写本机文件的工具（这里是：虚拟机文件上传/下载、OVA 和部署 spec 文件）永远碰不到本机的配置、token、审计日志和 TLS 私钥；通过网络访问时，
+  除非用 `VMWARE_MCP_FILE_ROOT` 指定一个目录，否则这些工具不能访问本机文件（需 vmware-policy ≥ 1.23.1）。
 - 审计日志把每个调用者记为 `token:<名字>`。调用并行执行，每个 target 最多 `VMWARE_MCP_POOL_SIZE`（默认 2）
   个会话；每个会话都是在该 target 上的一次登录，一个调用最多等待 300 秒拿到会话。
 - **能连到这个端点的人，都以该 server 配置的账号操作。** token 只用来识别调用者，不在平台上授予任何权限。

vmware_aiops-2.3.0/PKG-INFO → vmware_aiops-2.3.2/README.md

@@ -1,27 +1,3 @@
-Metadata-Version: 2.5
-Name: vmware-aiops
-Version: 2.3.0
-Summary: VMware vCenter/ESXi AI-powered VM lifecycle and deployment tool
-Project-URL: Homepage, https://github.com/vmware-skills/VMware-AIops
-Project-URL: Repository, https://github.com/vmware-skills/VMware-AIops
-Project-URL: Issues, https://github.com/vmware-skills/VMware-AIops/issues
-Project-URL: Changelog, https://github.com/vmware-skills/VMware-AIops/blob/main/RELEASE_NOTES.md
-Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: apscheduler<4.0,>=3.10
-Requires-Dist: httpx<1.0,>=0.27
-Requires-Dist: mcp[cli]<2.0,>=1.28
-Requires-Dist: pyaml<27.0,>=24.0
-Requires-Dist: python-dotenv<2.0,>=1.0
-Requires-Dist: pyvmomi<10.0,>=8.0.3.0
-Requires-Dist: rich<16.0,>=13.0
-Requires-Dist: typer<1.0,>=0.12
-Requires-Dist: vmware-monitor<3.0,>=2.0.0
-Requires-Dist: vmware-policy<2.0,>=1.22.0
-Description-Content-Type: text/markdown
-
 <!-- mcp-name: io.github.vmware-skills/vmware-aiops -->
 # VMware AIops
 
@@ -460,6 +436,9 @@ Run `vmware-aiops plan list` to see failed plan status. Ask user if they want to
 1. Verify target is reachable: `vmware-aiops doctor`
 2. For self-signed certs: set `verify_ssl: false` in config.yaml (lab environments only)
 
+### `doctor` reports "no vSphere role", or every command fails with "session is not authenticated"
+The account logs in but has no vSphere role, so vCenter gives it no session (AIops#47). Assign it a role (Read-Only or higher) on the vCenter root folder: Administration > Access Control > Global Permissions. Changing the password will not help. `vmware-aiops doctor` reports this case by name, and `attention` counts such a target as unread (overall at least WARN).
+
 ---
 
 ## Supported AI Platforms
@@ -1188,6 +1167,15 @@ claude mcp add --transport http vmware-aiops 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.
+- Tools that read or write files on this server (here: guest file upload/download, OVA and deployment-spec files) never touch its configuration, tokens, audit log or
+  TLS key, and over the network they are off unless `VMWARE_MCP_FILE_ROOT` names a directory for them
+  (vmware-policy ≥ 1.23.1).
 - The audit log records each caller as `token:<name>`. Calls run side by side, with up to `VMWARE_MCP_POOL_SIZE`
   (default 2) sessions per target; each session is a login on the target, and a call waits at most 300 s for one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/RELEASE_NOTES.md

@@ -1,3 +1,47 @@
+## v2.3.2 — tools may not touch this server's own control files
+
+* **Security fix (HLD §18 step 0).** guest file download/upload, OVA and deployment-spec paths could name this server's own files, so over HTTPS a token holder could
+  overwrite `$OPS_HOME/mcp-tokens` or `rules.yaml`, or read a skill's `.env`. A path that resolves into `$OPS_HOME`,
+  a `~/.vmware-*` directory, a `VMWARE_*_CONFIG` directory, or the server's token file or TLS key/certificate is now
+  refused before anything is read or written. Over a network transport these tools read and write host files only
+  inside `VMWARE_MCP_FILE_ROOT` (unset: refused). Needs vmware-policy 1.23.1.
+* `download_vm_guest_file` writes without following a link swapped in during the transfer (`O_NOFOLLOW`, a
+  re-check after the transfer) and refuses a hard-linked destination; the `provision_vm_guest` preview no longer
+  reports the size of a file the run would refuse. Uploads read the source the same way, and a FIFO no longer
+  blocks either direction.
+* **`plan_id` can no longer name a path.** `apply_vm_plan` / `rollback_vm_plan` / `list`/`delete` built the plan file
+  name from the caller's `plan_id`, and saving used the id stored in the file, so a crafted plan could be written to
+  any `*.json` on the host. Plan ids are now `plan-` plus letters, digits and hyphens, and a plan file whose stored id
+  differs from its name is refused.
+
+## v2.3.1 — an account with no vSphere role is named, not passed (AIops#47)
+
+Needs vmware-policy 1.23.0, and the vmware-monitor release with the same fix for the `attention` part.
+
+* **A login with no vSphere role fails at connect time with the reason.** vCenter accepts the login but shows no
+  session for it, and every call then fails with `NotAuthenticated`. The connection is now closed at once and
+  `doctor`, the CLI and MCP tools say the account most likely has no vSphere role and to assign one (Read-Only or
+  higher). Reported on vCenter 8.0.3; not yet reproduced on our own hardware.
+* Refused only when two signals agree: no session, **and** vCenter refuses a view of the root folder
+  (`NotAuthenticated` / `NoPermission`). An account scoped to one folder can also show no session, and still
+  connects; anything the check cannot read lets the login through.
+* **`NotAuthenticated` later on names both causes**: the session expired (retry), or the account's role was
+  removed. It no longer says "verify connectivity and credentials".
+* **Every CLI command prints one line for a vSphere fault.** `summary` (and any other command) printed a raw
+  traceback for faults other than a failed login; they now print the fault's message and what to check.
+* **`attention` never reports OK for targets it could not read** (computed by vmware-monitor): any unread target
+  makes the overall status at least WARN, none read makes it CRITICAL, and the console and HTML say how many were
+  not read. A role-less target is listed as unreachable with reason `NoVSphereRoleError`.
+
+## Unreleased — OVA deploy honours `network_name`
+
+* **`deploy_vm_from_ova` / `deploy ova --network` now attach the NICs to the network you name.** The import spec
+  carried no network mapping, so the argument had no effect and each NIC landed on whatever network the OVF
+  descriptor named. Every network the OVF declares is now mapped to the named port group (standard or distributed).
+  A name that matches no network, or more than one (a standard and a distributed port group can share a name), is
+  refused before anything is imported, with the available names in the error. An OVF descriptor the server cannot
+  parse is refused the same way. Found in the 2026-10-16 pre-release review.
+
 ## v2.3.0 — calls on one target run side by side; `get_access_info`
 
 Needs vmware-policy 1.22.0.

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/openclaw.plugin.json

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

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-aiops",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "AI-powered VMware vCenter/ESXi VM lifecycle and deployment with 61 MCP tools.",
   "private": true,
   "license": "MIT",

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-aiops"
-version = "2.3.0"
+version = "2.3.2"
 description = "VMware vCenter/ESXi AI-powered VM lifecycle and deployment tool"
 readme = "README.md"
 license = "MIT"
@@ -19,11 +19,11 @@ dependencies = [
     "httpx>=0.27,<1.0",
     "python-dotenv>=1.0,<2.0",
     "mcp[cli]>=1.28,<2.0",
-    "vmware-policy>=1.22.0,<2.0",
+    "vmware-policy>=1.23.1,<2.0",
     # Read-only cluster-health triage (summary + HTML snapshot) is owned by
     # vmware-monitor; AIops delegates to it so a conversation with the AIops
     # entry point can produce the same report without duplicating the code.
-    "vmware-monitor>=2.0.0,<3.0",
+    "vmware-monitor>=2.3.1,<3.0",  # attention status floor + role-less login (AIops#47)
 ]
 
 

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/server.json

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

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/skills/vmware-aiops/SKILL.md

@@ -63,7 +63,7 @@ Read before connecting an agent. Per-tool inventory: `references/capabilities.md
 ## Quick Install
 
 ```bash
-uv tool install vmware-aiops==2.3.0
+uv tool install vmware-aiops==2.3.2
 vmware-aiops doctor
 vmware-aiops hub status   # see which family members are installed
 ```
@@ -285,11 +285,10 @@ Use `run_vm_guest_command_with_output` instead of `run_vm_guest_command` — it
 Large OVA files (>10GB) may exceed the default 120s timeout. The upload happens via HTTP NFC lease — ensure network between the machine running vmware-aiops and ESXi is stable.
 
 ### Snapshot delete is slow / "still running after Ns"
-Deleting an old or large snapshot consolidates its delta disk into the parent — the slowest write
-operation, often several minutes. `vm snapshot-delete` waits up to 30 min by default; if it still
-returns a "still running, NOT failed" message with a task id, the delete did **not** fail — poll it with
-`vm task-status <task-id>`. Do not re-issue the delete or hand-roll polling. For very large snapshots,
-prefer `vm snapshot-delete <name> --name <snap> --no-wait` to get the task id immediately and poll.
+Deleting a large snapshot consolidates its delta disk, often for minutes. `vm snapshot-delete` waits
+up to 30 min; a "still running, NOT failed" message with a task id means the delete did **not** fail —
+poll `vm task-status <task-id>`; do not re-issue it. For large ones, use
+`vm snapshot-delete <name> --name <snap> --no-wait` and poll.
 
 ### Plan apply fails mid-way
 Run `vmware-aiops plan list` to see failed plan status. Ask user if they want to rollback with `rollback_vm_plan`. Irreversible steps (delete_vm) are skipped during rollback.
@@ -298,10 +297,13 @@ Run `vmware-aiops plan list` to see failed plan status. Ask user if they want to
 1. Verify target is reachable: `vmware-aiops doctor`
 2. For self-signed certs: set `verify_ssl: false` in config.yaml (lab environments only)
 
+### Every command fails with "session is not authenticated"
+The account has no vSphere role. Assign one (Read-Only or higher) on the vCenter root folder; `vmware-aiops doctor` reports this case by name.
+
 ## Setup
 
 ```bash
-uv tool install vmware-aiops==2.3.0
+uv tool install vmware-aiops==2.3.2
 mkdir -p ~/.vmware-aiops
 vmware-aiops init  # generates config.yaml and .env templates
 chmod 600 ~/.vmware-aiops/.env

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/skills/vmware-aiops/references/setup-guide.md

@@ -6,13 +6,13 @@ All install methods fetch from the same source: [github.com/vmware-skills/VMware
 
 ```bash
 # Via PyPI (recommended for version pinning)
-uv tool install vmware-aiops==2.3.0
+uv tool install vmware-aiops==2.3.2
 
 # Via Skills.sh (fetches from GitHub)
-npx skills add vmware-skills/VMware-AIops#v2.3.0
+npx skills add vmware-skills/VMware-AIops#v2.3.2
 
 # Via ClawHub (fetches from ClawHub registry snapshot of GitHub)
-clawhub install @zw008/vmware-aiops --version 2.3.0
+clawhub install @zw008/vmware-aiops --version 2.3.2
 ```
 
 ### Claude Code
@@ -35,7 +35,7 @@ claude mcp add vmware-aiops -- vmware-aiops mcp
 
 ```bash
 # 1. Install from PyPI (source: github.com/vmware-skills/VMware-AIops)
-uv tool install vmware-aiops==2.3.0
+uv tool install vmware-aiops==2.3.2
 
 # 2. Verify installation source
 vmware-aiops --version  # confirms installed version
@@ -73,7 +73,7 @@ The `vmware-aiops` package installs a Python CLI binary and its dependencies (py
 ## Development Install
 
 ```bash
-git clone --branch v2.3.0 https://github.com/vmware-skills/VMware-AIops.git
+git clone --branch v2.3.2 https://github.com/vmware-skills/VMware-AIops.git
 cd VMware-AIops
 uv venv && source .venv/bin/activate
 # --no-sources: pyproject's [tool.uv.sources] points vmware-monitor at a sibling
@@ -226,6 +226,16 @@ vmware-aiops 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.
+- Tools that read or write files on this server (here: guest file upload/download, OVA and deployment-spec files) never touch its configuration, tokens, audit log or
+  TLS key, and over the network they are off unless `VMWARE_MCP_FILE_ROOT` names a directory for them
+  (vmware-policy ≥ 1.23.1).
 - `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

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/tests/eval/regression/test_atexit_handlers_do_not_accumulate.py

@@ -20,8 +20,9 @@ that registered its own handler would pass with the production one deleted.
 from __future__ import annotations
 
 import gc
+import itertools
 import weakref
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock, PropertyMock, patch
 
 import pytest
 
@@ -44,9 +45,13 @@ def _target(name: str = "vcenter-prod") -> TargetConfig:
 
 
 def _dead_si(*_a, **_kw):
-    """An SI whose liveness probe says dead, so the next connect() evicts it."""
+    """An SI that is alive at login and dead from then on, so the next connect()
+    evicts it. Dead from the start would be refused at login as a role-less
+    account (AIops#47), which is a different path."""
     si = MagicMock()
-    si.content.sessionManager.currentSession = None
+    type(si.content.sessionManager).currentSession = PropertyMock(
+        side_effect=itertools.chain([object()], itertools.repeat(None))
+    )
     return si
 
 

{vmware_aiops-2.3.0 → vmware_aiops-2.3.2}/tests/eval/regression/test_deploy_correctness.py

@@ -235,6 +235,11 @@ def test_deploy_ova_maps_device_urls_by_importkey_out_of_order() -> None:
 
     content = MagicMock()
     content.ovfManager.CreateImportSpec.return_value = import_spec_result
+    # A descriptor that parses cleanly and declares no networks (mapping is
+    # covered in test_ova_network_mapping.py).
+    content.ovfManager.ParseDescriptor.return_value = SimpleNamespace(
+        error=None, warning=None, network=[]
+    )
     si = MagicMock()
     si.RetrieveContent.return_value = content
 

vmware_aiops-2.3.2/tests/eval/regression/test_host_paths_protected.py

@@ -0,0 +1,239 @@
+"""Regression: tools could read or write this server's own control files (HLD §18 step 0).
+
+Over HTTPS any token holder could call ``download_vm_guest_file(local_path=
+"~/.vmware/mcp-tokens", overwrite=True)`` and replace the token file, or upload
+a skill's ``.env`` into a VM. Every place that opens a caller-supplied host path
+now refuses one that resolves into ``$OPS_HOME`` or a ``~/.vmware-*`` directory,
+before anything is read, written or transferred.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from vmware_policy.hostpaths import HostPathRefusedError
+
+from vmware_aiops.ops import guest_ops, ova_deploy, vm_deploy
+
+
+@pytest.fixture
+def ops_home() -> Path:
+    home = Path(os.environ["OPS_HOME"])  # the sandbox conftest set
+    home.mkdir(parents=True, exist_ok=True)
+    tokens = home / "mcp-tokens"
+    tokens.write_text("alice:abc\n", encoding="utf-8")
+    return home
+
+
+def test_download_cannot_overwrite_the_token_file(ops_home):
+    si = MagicMock()
+    with pytest.raises(HostPathRefusedError):
+        guest_ops.guest_download(
+            si, "vm1", "/etc/hosts", str(ops_home / "mcp-tokens"), "u", "p", overwrite=True
+        )
+    assert (ops_home / "mcp-tokens").read_text(encoding="utf-8") == "alice:abc\n"
+    si.RetrieveContent.assert_not_called()
+
+
+def test_upload_cannot_send_a_control_file_into_a_vm(ops_home):
+    si = MagicMock()
+    with patch.object(guest_ops, "_require_vm_with_tools", return_value=MagicMock()), \
+         patch("urllib.request.urlopen") as urlopen:
+        with pytest.raises(HostPathRefusedError):
+            guest_ops.guest_upload(
+                si, "vm1", str(ops_home / "mcp-tokens"), "/tmp/x", "u", "p"
+            )
+        urlopen.assert_not_called()
+    fm = si.RetrieveContent.return_value.guestOperationsManager.fileManager
+    fm.InitiateFileTransferToGuest.assert_not_called()
+
+
+def test_a_deploy_spec_inside_ops_home_is_not_read(ops_home):
+    with pytest.raises(HostPathRefusedError):
+        vm_deploy.load_deploy_spec(str(ops_home / "rules.yaml"))
+
+
+def test_an_ova_inside_ops_home_is_not_read(ops_home):
+    with pytest.raises(HostPathRefusedError):
+        ova_deploy._read_ovf_from_ova(str(ops_home / "audit.db"))
+
+
+def test_the_mcp_tool_refuses_before_running(ops_home):
+    from vmware_aiops.mcp_server.tools import guest as guest_tools
+
+    with patch.object(guest_tools, "_get_connection") as connect:
+        with pytest.raises(HostPathRefusedError):
+            guest_tools.download_vm_guest_file(
+                vm_name="vm1",
+                guest_path="/etc/hosts",
+                local_path=str(ops_home / "mcp-tokens"),
+                username="u",
+                password="p",
+                overwrite=True,
+            )
+        connect.assert_not_called()
+
+
+def test_ordinary_paths_still_work(tmp_path):
+    spec = tmp_path / "spec.yaml"
+    spec.write_text("vms: []\n", encoding="utf-8")
+    assert vm_deploy.load_deploy_spec(str(spec)) is not None
+
+
+# ── review 2026-10-16: hard links, symlink swapped in after the check, preview ──
+
+
+def _download_with_fake_transfer(local: str, overwrite: bool, before_write=None):
+    """Run guest_download with the guest transfer faked; call before_write after the check."""
+    si = MagicMock()
+    vm = MagicMock()
+    resp = MagicMock()
+    resp.__enter__.return_value.read.return_value = b"payload"
+
+    def urlopen(*a, **k):
+        if before_write:
+            before_write()
+        return resp
+
+    with patch.object(guest_ops, "_require_vm_with_tools", return_value=vm), \
+         patch("urllib.request.urlopen", side_effect=urlopen), \
+         patch.object(guest_ops, "get_verify_ssl", return_value=True):
+        return guest_ops.guest_download(
+            si, "vm1", "/etc/motd", local, "u", "p", overwrite=overwrite
+        )
+
+
+def test_a_hard_link_to_a_protected_file_is_not_written_through(ops_home, tmp_path):
+    outside = tmp_path / "innocent.txt"
+    os.link(ops_home / "mcp-tokens", outside)
+    with pytest.raises(ValueError, match="hard link"):
+        _download_with_fake_transfer(str(outside), overwrite=True)
+    assert (ops_home / "mcp-tokens").read_text(encoding="utf-8") == "alice:abc\n"
+
+
+def test_a_symlink_swapped_in_during_the_transfer_is_not_followed(ops_home, tmp_path):
+    dest = tmp_path / "out.txt"
+
+    def swap():
+        dest.symlink_to(ops_home / "mcp-tokens")
+
+    with pytest.raises((HostPathRefusedError, OSError)):
+        _download_with_fake_transfer(str(dest), overwrite=True, before_write=swap)
+    assert (ops_home / "mcp-tokens").read_text(encoding="utf-8") == "alice:abc\n"
+
+
+def test_an_ordinary_download_is_written(tmp_path):
+    dest = tmp_path / "out.txt"
+    _download_with_fake_transfer(str(dest), overwrite=False)
+    assert dest.read_bytes() == b"payload"
+
+
+def test_the_provision_preview_does_not_reveal_a_protected_file(ops_home):
+    from vmware_aiops.ops import guest_gate
+
+    info, blocker = guest_gate._local_file(str(ops_home / "mcp-tokens"))
+    assert info["local_size_bytes"] is None
+    assert blocker and "configuration, tokens and audit log" in blocker
+
+
+def test_a_parent_dir_swapped_for_a_link_during_the_transfer_is_caught(ops_home, tmp_path):
+    # O_NOFOLLOW guards only the last component; the re-check after the transfer
+    # catches a parent directory replaced by a link into OPS_HOME.
+    sub = tmp_path / "sub"
+    sub.mkdir()
+
+    def swap():
+        sub.rmdir()
+        sub.symlink_to(ops_home, target_is_directory=True)
+
+    with pytest.raises(HostPathRefusedError):
+        _download_with_fake_transfer(str(sub / "rules.yaml"), overwrite=False, before_write=swap)
+    assert not (ops_home / "rules.yaml").exists()
+
+
+# ── second review 2026-10-16: plan_id was an unchecked host path ──────────────
+
+
+@pytest.mark.parametrize(
+    "bad",
+    ["/tmp/evil", "../../.cursor/mcp", "plan-x/../../evil", "plan-..", "", "plan-a.b", "x" * 300],
+)
+def test_a_plan_id_cannot_name_a_path(bad, tmp_path, monkeypatch):
+    from vmware_aiops.ops import planner
+
+    monkeypatch.setattr(planner, "_PLANS_DIR", tmp_path / "plans")
+    with pytest.raises(ValueError, match="plan id"):
+        planner.load_plan(bad)
+    with pytest.raises(ValueError, match="plan id"):
+        planner.delete_plan(bad)
+    with pytest.raises(ValueError, match="plan id"):
+        planner.save_plan({"plan_id": bad, "steps": []})
+
+
+def test_a_plan_file_naming_another_plan_id_is_refused(tmp_path, monkeypatch):
+    import json
+
+    from vmware_aiops.ops import planner
+
+    plans = tmp_path / "plans"
+    plans.mkdir()
+    monkeypatch.setattr(planner, "_PLANS_DIR", plans)
+    (plans / "plan-20261016-000000-abcd.json").write_text(
+        json.dumps({"plan_id": "../../.cursor/mcp", "steps": []}), encoding="utf-8"
+    )
+    with pytest.raises(ValueError, match="plan id"):
+        planner.load_plan("plan-20261016-000000-abcd")
+
+
+def test_a_generated_plan_id_round_trips(tmp_path, monkeypatch):
+    from vmware_aiops.ops import planner
+
+    monkeypatch.setattr(planner, "_PLANS_DIR", tmp_path / "plans")
+    (tmp_path / "plans").mkdir()
+    pid = planner._generate_plan_id()
+    planner.save_plan({"plan_id": pid, "steps": []})
+    assert planner.load_plan(pid)["plan_id"] == pid
+    planner.delete_plan(pid)
+    assert planner.load_plan(pid) is None
+
+
+def test_download_onto_a_fifo_does_not_hang(tmp_path):
+    fifo = tmp_path / "pipe"
+    os.mkfifo(fifo)
+    with pytest.raises((ValueError, OSError)):
+        _download_with_fake_transfer(str(fifo), overwrite=True)
+
+
+def test_upload_reads_a_regular_file_without_following_a_swapped_link(ops_home, tmp_path):
+    src = tmp_path / "src.txt"
+    src.write_text("data", encoding="utf-8")
+    assert guest_ops._read_upload_source(src) == b"data"
+    link = tmp_path / "link.txt"
+    link.symlink_to(ops_home / "mcp-tokens")
+    with pytest.raises(OSError):
+        guest_ops._read_upload_source(link)
+
+
+def test_upload_source_swapped_for_a_fifo_is_refused_not_hung(tmp_path):
+    fifo = tmp_path / "pipe"
+    os.mkfifo(fifo)
+    with pytest.raises(ValueError, match="regular file"):
+        guest_ops._read_upload_source(fifo)
+
+
+def test_a_plan_id_with_a_trailing_newline_is_refused(tmp_path, monkeypatch):
+    from vmware_aiops.ops import planner
+
+    monkeypatch.setattr(planner, "_PLANS_DIR", tmp_path / "plans")
+    with pytest.raises(ValueError, match="plan id"):
+        planner.load_plan("plan-abc\n")
+
+
+def test_an_upload_source_that_is_a_hard_link_is_refused(ops_home, tmp_path):
+    link = tmp_path / "innocent.txt"
+    os.link(ops_home / "mcp-tokens", link)
+    with pytest.raises(ValueError, match="hard link"):
+        guest_ops._read_upload_source(link)