vmware-debug 2.2.0__tar.gz → 2.3.1__tar.gz

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-debug",
   "displayName": "VMware Debug",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "VMware incident timeline, root-cause routing, local case ledger; no vSphere access. 14 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-debug==2.2.0",
+        "vmware-debug==2.3.1",
         "vmware-debug-mcp"
       ]
     }

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: vmware-debug
-Version: 2.2.0
+Version: 2.3.1
 Summary: VMware diagnostic brain — offline incident triage, log/event correlation, and root-cause routing across the VMware skill family
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Debug
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Debug
 Project-URL: Issues, https://github.com/vmware-skills/VMware-Debug/issues
 Project-URL: Changelog, https://github.com/vmware-skills/VMware-Debug/blob/main/RELEASE_NOTES.md
-Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
+Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT
 Keywords: ai-ops,debug,diagnostics,mcp,rca,troubleshooting,vmware,vsphere
 Classifier: Development Status :: 4 - Beta
@@ -14,7 +14,8 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: System :: Monitoring
 Requires-Python: >=3.10
-Requires-Dist: mcp[cli]<2.0,>=1.28
+Requires-Dist: certifi>=2026.10.19
+Requires-Dist: mcp[cli]<2.0,>=1.30
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: rich<15.0,>=13.0
 Requires-Dist: typer<1.0,>=0.12
@@ -25,6 +26,8 @@ Description-Content-Type: text/markdown
 
 # VMware Debug
 
+For a read-only check of this skill with your model and agent host, use the shared [model-fit self-test](https://github.com/vmware-skills/marketplace/blob/main/MODEL_FIT_SELF_TEST.md) in the marketplace root.
+
 > **Disclaimer**: Community-maintained open-source project, **not affiliated with,
 > endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and
 > "vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT
@@ -105,6 +108,8 @@ event actually is.
 
 ## Security
 
+CLI policy refusals print the reason and rule, exit with code 1, and retain one `denied` audit row.
+
 Offline and credential-free by construction: it connects to no vCenter/NSX/Aria, has no destructive surface on
 VMware, and holds no secret to leak. The only writes are the local case ledger: evidence, gaps, hypotheses and
 grade history are append-only; `timeline.md` is regenerated from the evidence, and `case.json` holds the current
@@ -145,6 +150,71 @@ pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this packa
 pip install --no-index --find-links dist vmware-debug
 ```
 
+<!-- usage: remote-and-exposure -->
+## Remote access (HTTPS) and limiting tools
+
+By default `vmware-debug mcp` speaks stdio to one local client and offers every tool. Two options change that
+(vmware-policy ≥ 1.21.0).
+
+**Serve over HTTPS** so clients on other machines can connect. Every caller needs a bearer token:
+
+```bash
+vmware-audit token create alice          # prints the token once; give it to alice
+vmware-audit token list                  # names only
+vmware-audit token revoke alice          # refused from its next request, no restart
+vmware-debug mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):
+
+```bash
+claude mcp add --transport http vmware-debug https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+```
+
+```json
+{
+  "mcpServers": {
+    "vmware-debug": {
+      "type": "http",
+      "url": "https://mcp.example.com:8443/mcp",
+      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
+- The server will not start without a token, refuses Host/Origin values outside `--public-name`, and checks
+  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 naming different targets run in parallel; calls that
+  name no target run one at a time, so name the target when several people share a server.
+- **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:**
+
+```bash
+vmware-debug mcp --expose read --allow-write close_case
+# or: VMWARE_DEBUG_MCP_EXPOSE=read VMWARE_DEBUG_MCP_ALLOW_WRITE=close_case vmware-debug mcp
+```
+
+Tools not offered do not appear in the client's tool list. A bad value or an unknown write tool stops the server
+(exit 2). This limits what clients are offered; it is not authorization, so the account itself should be
+least-privilege.
+
+Details: `skills/vmware-debug/references/setup-guide.md` ("Serving MCP over HTTPS", "Limiting which tools are offered").
+
 ## License
 
 MIT.

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/README-CN.md

@@ -2,6 +2,8 @@
 
 # VMware Debug（中文）
 
+要用自己的模型和 Agent 平台进行只读自测，请看 marketplace 根目录的[共享模型适配自测任务](https://github.com/vmware-skills/marketplace/blob/main/MODEL_FIT_SELF_TEST.md)。
+
 > **声明**：本项目为社区维护的开源项目，**与 VMware, Inc. 或 Broadcom Inc. 无任何隶属、
 > 背书或赞助关系。** "VMware"、"vSphere" 为 Broadcom 商标。源码以 MIT 许可证公开可审计。
 
@@ -68,6 +70,8 @@ debug；debug 因此与其它包零运行时依赖。**请把每条事件的 `ev
 
 ## 安全
 
+CLI 被策略拒绝时会显示原因和规则，以退出码 1 结束，并保留一条 `denied` 审计记录。
+
 结构上离线、无凭据：不连任何 vCenter/NSX/Aria，对 VMware 没有可破坏面，也没有秘密可泄露。
 唯一的写入是本地案卷：证据、缺口、假设和等级历史只增不改；`timeline.md` 由证据重新生成，
 `case.json` 保存当前等级和状态。多个写入者同样成立：每次写案卷都要先拿该案卷的锁文件（`.ledger.lock`，
@@ -102,6 +106,69 @@ pip wheel . -w dist        # → dist/*.whl   （或：uv build，只构建本
 pip install --no-index --find-links dist vmware-debug
 ```
 
+<!-- usage: remote-and-exposure -->
+## 远程访问（HTTPS）与限制工具
+
+默认情况下 `vmware-debug mcp` 通过 stdio 服务一个本地客户端，并提供全部工具。以下两个选项可以改变这一点
+（需 vmware-policy ≥ 1.21.0）。
+
+**通过 HTTPS 提供服务**，让其他机器上的客户端连接。每个调用者都需要一个 bearer token：
+
+```bash
+vmware-audit token create alice          # 只显示一次，交给 alice
+vmware-audit token list                  # 只列名字
+vmware-audit token revoke alice          # 下一个请求起即拒绝，无需重启
+vmware-debug mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+连接客户端（以 Claude Code 为例；任何支持 streamable HTTP 和自定义请求头的 MCP 客户端都可以）：
+
+```bash
+claude mcp add --transport http vmware-debug https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+```
+
+```json
+{
+  "mcpServers": {
+    "vmware-debug": {
+      "type": "http",
+      "url": "https://mcp.example.com:8443/mcp",
+      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
+- 没有 token 时服务不会启动；`--public-name` 之外的 Host/Origin 一律拒绝；绑定端口前会自检，确认未认证请求得到 401。
+  证书要用客户端信任、且覆盖这些名字的证书。
+- 在同一台机器上由反向代理终结 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 的调用逐个执行，
+  所以多人共用一个 server 时请写明 target。
+- **能连到这个端点的人，都以该 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 的「网络调用者的角色」一节。
+
+**只提供读工具，加上你选定的写工具：**
+
+```bash
+vmware-debug mcp --expose read --allow-write close_case
+# 或：VMWARE_DEBUG_MCP_EXPOSE=read VMWARE_DEBUG_MCP_ALLOW_WRITE=close_case vmware-debug mcp
+```
+
+未提供的工具不会出现在客户端的工具列表里。取值错误或写工具名不存在时服务直接退出（exit 2）。
+这只限制提供给客户端的工具，不是授权；账号本身仍应遵循最小权限。
+
+详见 `skills/vmware-debug/references/setup-guide.md`（"Serving MCP over HTTPS"、"Limiting which tools are offered"）。
+
 ## 许可证
 
 MIT。

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/README.md

@@ -2,6 +2,8 @@
 
 # VMware Debug
 
+For a read-only check of this skill with your model and agent host, use the shared [model-fit self-test](https://github.com/vmware-skills/marketplace/blob/main/MODEL_FIT_SELF_TEST.md) in the marketplace root.
+
 > **Disclaimer**: Community-maintained open-source project, **not affiliated with,
 > endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and
 > "vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT
@@ -82,6 +84,8 @@ event actually is.
 
 ## Security
 
+CLI policy refusals print the reason and rule, exit with code 1, and retain one `denied` audit row.
+
 Offline and credential-free by construction: it connects to no vCenter/NSX/Aria, has no destructive surface on
 VMware, and holds no secret to leak. The only writes are the local case ledger: evidence, gaps, hypotheses and
 grade history are append-only; `timeline.md` is regenerated from the evidence, and `case.json` holds the current
@@ -122,6 +126,71 @@ pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this packa
 pip install --no-index --find-links dist vmware-debug
 ```
 
+<!-- usage: remote-and-exposure -->
+## Remote access (HTTPS) and limiting tools
+
+By default `vmware-debug mcp` speaks stdio to one local client and offers every tool. Two options change that
+(vmware-policy ≥ 1.21.0).
+
+**Serve over HTTPS** so clients on other machines can connect. Every caller needs a bearer token:
+
+```bash
+vmware-audit token create alice          # prints the token once; give it to alice
+vmware-audit token list                  # names only
+vmware-audit token revoke alice          # refused from its next request, no restart
+vmware-debug mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):
+
+```bash
+claude mcp add --transport http vmware-debug https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+```
+
+```json
+{
+  "mcpServers": {
+    "vmware-debug": {
+      "type": "http",
+      "url": "https://mcp.example.com:8443/mcp",
+      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
+- The server will not start without a token, refuses Host/Origin values outside `--public-name`, and checks
+  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 naming different targets run in parallel; calls that
+  name no target run one at a time, so name the target when several people share a server.
+- **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:**
+
+```bash
+vmware-debug mcp --expose read --allow-write close_case
+# or: VMWARE_DEBUG_MCP_EXPOSE=read VMWARE_DEBUG_MCP_ALLOW_WRITE=close_case vmware-debug mcp
+```
+
+Tools not offered do not appear in the client's tool list. A bad value or an unknown write tool stops the server
+(exit 2). This limits what clients are offered; it is not authorization, so the account itself should be
+least-privilege.
+
+Details: `skills/vmware-debug/references/setup-guide.md` ("Serving MCP over HTTPS", "Limiting which tools are offered").
+
 ## License
 
 MIT.

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/RELEASE_NOTES.md

@@ -1,3 +1,20 @@
+## v2.3.1 — readable Policy refusals and dependency security (2026-11-08)
+
+* Update public author/project contact metadata to `zhouwei008@gmail.com`.
+
+### dependency security and sandbox test stability
+* Require certifi 2026.10.19 or later for MCP's HTTP/TLS dependencies (GHSA-6q48-6c7w-9gw2); the lock resolves 2026.10.23.
+* The audit-isolation regression still proves its write reached only the sandbox DB; it skips the production-DB comparison when the host sandbox denies even read-only access to that DB.
+* CLI policy refusals now print their reason and rule without a traceback. The audited wrapper still records exactly one `denied` row before the CLI exits with code 1.
+
+## v2.3.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): that no tool takes a target. 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".
+* README and setup guide: one endpoint for several people or roles.
+
 ## v2.2.0 — serve MCP over HTTPS
 
 `vmware-debug mcp` can now serve the network as well as stdio (HLD §16, via vmware-policy 1.21.0):
@@ -8,6 +25,15 @@ vmware-debug mcp --transport https --host 0.0.0.0 --port 8443 \
     --cert server.pem --key server-key.pem --public-name mcp.example.com
 ```
 
+Connect a client and manage callers (Claude Code shown; any MCP client with streamable HTTP and custom headers works):
+
+```bash
+claude mcp add --transport http vmware-debug https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+vmware-audit token list                  # names only
+vmware-audit token revoke alice          # refused from its next request, no restart
+```
+
 * Every request needs `Authorization: Bearer <token>`; the server will not start without a token, refuses Host or
   Origin values outside `--public-name`, and checks itself (unauthenticated requests must get 401) before it
   binds. `--transport http` binds loopback only, for a TLS-terminating reverse proxy.
@@ -881,4 +907,4 @@ executes fixes (advisor/executor split, mirroring vmware-harden → vmware-pilot
 ### Notes
 - Read-only by construction; remediation is routed, never executed.
 - `parse_timestamp` rejects implausible/garbage timestamps loudly rather than
-  silently landing at the epoch.
+  silently landing at the epoch.

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-debug==2.2.0",
+        "vmware-debug==2.3.1",
         "vmware-debug-mcp"
       ]
     }

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-debug",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "VMware incident timeline, root-cause routing, local case ledger; no vSphere access. 14 MCP tools.",
   "private": true,
   "license": "MIT",

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-debug"
-version = "2.2.0"
+version = "2.3.1"
 description = "VMware diagnostic brain — offline incident triage, log/event correlation, and root-cause routing across the VMware skill family"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
-authors = [{ name = "Wei Zhou", email = "wei-wz.zhou@broadcom.com" }]
+authors = [{ name = "Wei Zhou", email = "zhouwei008@gmail.com" }]
 keywords = ["vmware", "vsphere", "debug", "troubleshooting", "diagnostics", "rca", "mcp", "ai-ops"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -20,7 +20,8 @@ classifiers = [
 dependencies = [
     "typer>=0.12,<1.0",
     "rich>=13.0,<15.0",
-    "mcp[cli]>=1.28,<2.0",
+    "mcp[cli]>=1.30,<2.0",
+    "certifi>=2026.10.19",  # GHSA-6q48-6c7w-9gw2 via MCP/httpx
     "vmware-policy>=1.21.0,<2.0",
     # Imported directly by ops/cases/grading.py for the rules file. It has
     # always arrived transitively via vmware-policy; a package should

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-Debug",
     "source": "github"
   },
-  "version": "2.2.0",
+  "version": "2.3.1",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-debug",
-      "version": "2.2.0",
+      "version": "2.3.1",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/skills/vmware-debug/SKILL.md

@@ -25,6 +25,8 @@ metadata: {"openclaw":{"requires":{"anyBins":["vmware-debug","uvx"]},"optional":
 
 # VMware Debug
 
+> Self-test: [guide](https://github.com/vmware-skills/marketplace/blob/main/MODEL_FIT_SELF_TEST.md).
+
 > **Disclaimer**: Community-maintained open-source project, **not affiliated with,
 > endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and "vSphere"
 > are trademarks of Broadcom. Source is publicly auditable under the MIT license.
@@ -51,7 +53,7 @@ write tools touch only the local case ledger.
 ## Quick Install
 
 ```bash
-uv tool install vmware-debug==2.2.0
+uv tool install vmware-debug==2.3.1
 vmware-debug categories          # see what it can diagnose
 ```
 

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/skills/vmware-debug/references/setup-guide.md

@@ -6,7 +6,7 @@ is a pure, offline correlation engine. There is no `config.yaml` and no `.env`.
 ## Install
 
 ```bash
-uv tool install vmware-debug==2.2.0
+uv tool install vmware-debug==2.3.1
 vmware-debug categories      # verify it runs
 ```
 
@@ -15,7 +15,7 @@ vmware-debug categories      # verify it runs
 ```json
 {
   "command": "uvx",
-  "args": ["--from", "vmware-debug==2.2.0", "vmware-debug-mcp"]
+  "args": ["--from", "vmware-debug==2.3.1", "vmware-debug-mcp"]
 }
 ```
 
@@ -51,6 +51,42 @@ vmware-debug mcp --expose read --allow-write close_case
 - This limits what clients are offered. It is **not** authorization. This server's write tools change case records on this machine;
   deny rules in `~/.vmware/rules.yaml` still apply to every exposed tool.
 
+## Serving MCP over HTTPS
+
+By default the MCP server speaks stdio to one local client. To let clients on other machines reach it, serve it over
+HTTPS. Every caller then needs a bearer token.
+
+```bash
+vmware-audit token create alice                      # prints the token once; give it to alice
+vmware-debug mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+- Clients connect to `https://mcp.example.com:8443/mcp` and send `Authorization: Bearer <token>`.
+- `--public-name` lists every host name clients use (comma-separated); requests for any other Host or Origin are
+  refused. Use a certificate your clients trust for those names.
+- 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
+  are refused.
+- Each audit row records the caller as `token:<name>`. Calls naming different targets run in parallel; calls that
+  name no target run one at a time, so name the target when several people use one server.
+- **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".
+
 ## Security
 
 > **Disclaimer**: Community-maintained open-source project, **not affiliated with,

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/tests/eval/regression/test_audit_isolation.py

@@ -62,6 +62,11 @@ def test_an_audited_write_lands_in_the_sandbox_and_not_in_the_real_db() -> None:
     real_db = REAL_HOME / ".vmware" / "audit.db"
     if not real_db.exists():
         pytest.skip("no production audit database on this machine to check against")
-    with sqlite3.connect(f"file:{real_db}?mode=ro", uri=True) as con:
-        leaked = con.execute("SELECT count(*) FROM audit_log WHERE tool = ?", (marker,)).fetchone()[0]
+    try:
+        with sqlite3.connect(f"file:{real_db}?mode=ro", uri=True) as con:
+            leaked = con.execute("SELECT count(*) FROM audit_log WHERE tool = ?", (marker,)).fetchone()[0]
+    except sqlite3.OperationalError as exc:
+        if "unable to open database file" not in str(exc):
+            raise
+        pytest.skip("production audit DB is inaccessible from this sandbox")
     assert leaked == 0, f"{leaked} row(s) from this test reached {real_db}"

vmware_debug-2.3.1/tests/eval/regression/test_cli_policy_denial.py

@@ -0,0 +1,23 @@
+"""CLI policy denial must remain a denial in audit and be readable by an operator."""
+
+import pytest
+from typer.testing import CliRunner
+
+from vmware_debug.cli import app
+from vmware_policy import cli_guard
+from vmware_policy.policy import PolicyDenied, PolicyResult
+
+
+@pytest.mark.parametrize("args", [["categories"], ["triage"]])
+def test_denied_cli_command_prints_reason_and_records_one_denial(monkeypatch, args):
+    rows = []
+    def deny(*args, **kwargs):
+        raise PolicyDenied(PolicyResult(allowed=False, rule="ops-review", reason="offline checks denied"))
+    monkeypatch.setattr(cli_guard, "guard", deny)
+    monkeypatch.setattr(cli_guard, "audit_call", lambda *a, **kw: rows.append(kw))
+    result = CliRunner().invoke(app, args, input="[]")
+    assert result.exit_code == 1
+    assert "Denied by policy" in result.output
+    assert "offline checks denied" in result.output and "ops-review" in result.output
+    assert "Traceback" not in result.output
+    assert len(rows) == 1 and rows[0]["status"] == "denied"

vmware_debug-2.3.1/tests/test_policy_roles.py

@@ -0,0 +1,32 @@
+"""HLD §18: the role metadata this skill declares matches its real tools."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from vmware_debug import policy_roles
+
+
+def _registry() -> set[str]:
+    from vmware_debug.mcp_server.server import build_server
+
+    return {t.name for t in asyncio.run(build_server().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_debug.mcp_server.server  # noqa: F401  (registers the metadata on import)
+
+    meta = roles.metadata("debug")
+    assert meta is not None and meta.version == 1
+    assert meta.escapes == policy_roles.ESCAPES
+    assert (meta.resolver is not None) is False

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/uv.lock

@@ -1,12 +1,12 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version >= '3.14' and sys_platform == 'win32'",
     "python_full_version >= '3.14' and sys_platform != 'win32'",
     "python_full_version >= '3.11' and python_full_version < '3.14' and sys_platform == 'win32'",
-    "python_full_version < '3.11' and sys_platform == 'win32'",
     "python_full_version >= '3.11' and python_full_version < '3.14' and sys_platform != 'win32'",
+    "python_full_version < '3.11' and sys_platform == 'win32'",
     "python_full_version < '3.11' and sys_platform != 'win32'",
 ]
 
@@ -53,11 +53,11 @@ wheels = [
 
 [[package]]
 name = "certifi"
-version = "2026.6.17"
+version = "2026.10.23"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c9/c7/424b75da314c1045981bd9777432fad05a9e0c69daa4ed7e308bbaffe405/certifi-2026.6.17.tar.gz", hash = "sha256:024c88eeec92ca068db80f02b8b07c9cef7b9fe261d1d535abfd5abd6f6af432", size = 134594, upload-time = "2026-06-17T10:31:07.894Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/fd/11/b524cbd9bbdaca58608e4cf4053fd463417549e1959fa8d3aa18319f9555/certifi-2026.10.23.tar.gz", hash = "sha256:a9895e6e2758b371e0545e321a3a8fd1fcfd9829ada8824a936dfb16aaaf36cd", size = 136225, upload-time = "2026-10-23T11:36:16.478Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ef/2f/c5464532e965badff2f4c4c1a3a83f5697f0d7c407ed0cda44aaa99bb451/certifi-2026.6.17-py3-none-any.whl", hash = "sha256:2227dcbaafe0d2f59279d1762ddddc37783ed4354594f194ffc31d20f41fc3db", size = 133289, upload-time = "2026-06-17T10:31:06.348Z" },
+    { url = "https://files.pythonhosted.org/packages/32/d1/a3652fe2c19134d0d15922177821d863cbd7e842d53a21bbe7e8e3a1b5ac/certifi-2026.10.23-py3-none-any.whl", hash = "sha256:e9b54de76e530bb6cf0ccd036787103acb58fd42ba930ea8bf948ddbaa2f61d1", size = 135082, upload-time = "2026-10-23T11:36:14.763Z" },
 ]
 
 [[package]]
@@ -356,7 +356,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -469,7 +469,7 @@ wheels = [
 
 [[package]]
 name = "mcp"
-version = "1.28.1"
+version = "1.30.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
@@ -487,9 +487,9 @@ dependencies = [
     { name = "typing-inspection" },
     { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/6e/77/9450b8f251a13affb6281997d0523c4615f8a8b35d0b21ff30db3a5aac9d/mcp-1.28.1.tar.gz", hash = "sha256:d51e36a5f5644faea4f85ea649bfffa6bc6c26770d42798ad6a3de3d2ba69683", size = 638501, upload-time = "2026-06-26T12:57:29.093Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/ba/93/0142dc84a666daf8ad51a34268f34c12fd6fda4f3810c4be2504eecc8212/mcp-1.30.0.tar.gz", hash = "sha256:445414625fce5c295faa505bb11bacece661ab6f4028d57c935db57820b7a3e4", size = 680511, upload-time = "2026-09-07T14:34:15.845Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e2/5e/d118fce19f87a2e7d8101c35c8ae0ec289098a4df0ff244cec23e415aca0/mcp-1.28.1-py3-none-any.whl", hash = "sha256:2726bca5e7193f61c5dde8b12500a6de2d9acf6d1a1c0be9e8c2e706437991df", size = 222620, upload-time = "2026-06-26T12:57:27.218Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/f4/e58bc33317c92a0203664daaf00bf6f41166cc0149e5d6870a03f7cd004a/mcp-1.30.0-py3-none-any.whl", hash = "sha256:666edb5009503e1047c9d60346a756f94b261f05cc2625f23d41c728ffc484d0", size = 234581, upload-time = "2026-09-07T14:34:14.266Z" },
 ]
 
 [package.optional-dependencies]
@@ -1293,9 +1293,10 @@ wheels = [
 
 [[package]]
 name = "vmware-debug"
-version = "2.2.0"
+version = "2.3.1"
 source = { editable = "." }
 dependencies = [
+    { name = "certifi" },
     { name = "mcp", extra = ["cli"] },
     { name = "pyyaml" },
     { name = "rich" },
@@ -1312,7 +1313,8 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "mcp", extras = ["cli"], specifier = ">=1.28,<2.0" },
+    { name = "certifi", specifier = ">=2026.10.19" },
+    { name = "mcp", extras = ["cli"], specifier = ">=1.30,<2.0" },
     { name = "pyyaml", specifier = ">=6.0,<7.0" },
     { name = "rich", specifier = ">=13.0,<15.0" },
     { name = "typer", specifier = ">=0.12,<1.0" },
@@ -1328,14 +1330,14 @@ dev = [
 
 [[package]]
 name = "vmware-policy"
-version = "1.21.0"
+version = "1.24.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pyyaml" },
     { name = "rich" },
     { name = "typer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/87/5d/4221ea4a344ec33d6b54903682ce8ae2013bb0a2d6137c94ac769690ea8b/vmware_policy-1.21.0.tar.gz", hash = "sha256:f42b794ea69e52e1fa13aff8b5bc07631d82683b1c12872f2f2ec744e3853549", size = 303862, upload-time = "2026-10-15T10:13:33.719Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/15/8d/b9867ea1c0112caa481841c290c3fe718c0dbd738757db7877836f46267a/vmware_policy-1.24.2.tar.gz", hash = "sha256:6c816174fcd0b490bcd1f9ebaaa18b80fcb26b0eccb614e938938bb2e8452a40", size = 369315, upload-time = "2026-10-18T03:43:52.753Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/b4/feb7015ae5f7870e8058ad713050f7fe3ddefa57aa7bdd4a83f2e3b9abb4/vmware_policy-1.21.0-py3-none-any.whl", hash = "sha256:a10c26816be09f9a2823cc58bc4eacb9b5eff8b6df49dfc5b504b3d76cb3b7ec", size = 99818, upload-time = "2026-10-15T10:13:31.67Z" },
+    { url = "https://files.pythonhosted.org/packages/20/01/bc5f984a420d22514d8c3a627f332891f2008213d455c2f682f311e355f1/vmware_policy-1.24.2-py3-none-any.whl", hash = "sha256:2734ab49a76474fd74beb221a2d6535caab1f91a477668484c145dc2802ae072", size = 134565, upload-time = "2026-10-18T03:43:50.856Z" },
 ]

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/vmware_debug/__init__.py

@@ -6,4 +6,4 @@ remediation to vmware-aiops / vmware-pilot. Never writes to any VMware system
 and never executes fixes; its only writes go to the local case ledger.
 """
 
-__version__ = "2.2.0"
+__version__ = "2.3.1"

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/vmware_debug/cli.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import json
 import sys
+from functools import wraps
 from pathlib import Path
 from typing import Optional
 
@@ -20,7 +21,7 @@ from rich.table import Table
 
 from vmware_debug import __version__
 from vmware_debug.mcp.tools import build_incident_timeline, list_symptom_categories
-from vmware_policy import audited, cli_local
+from vmware_policy import PolicyDenied, audited, cli_local, sanitize
 
 
 def _harden_console_encoding() -> None:
@@ -53,6 +54,19 @@ app = typer.Typer(
 console = Console()
 
 
+def handle_cli_errors(func):
+    """Render policy refusals after the audited wrapper has recorded the denial."""
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except PolicyDenied as exc:
+            rule = f" (rule: {sanitize(exc.result.rule, 100)})" if exc.result.rule else ""
+            typer.echo(f"Denied by policy: {sanitize(exc.result.reason, 500)}{rule}", err=True)
+            raise typer.Exit(1) from None
+    return wrapper
+
+
 @app.command()
 @cli_local("prints the installed version")
 def version() -> None:
@@ -61,6 +75,7 @@ def version() -> None:
 
 
 @app.command()
+@handle_cli_errors
 @audited(tool="list_symptom_categories")
 def categories() -> None:
     """List the symptom categories debug recognises and what to check for each."""
@@ -74,6 +89,7 @@ def categories() -> None:
 
 
 @app.command()
+@handle_cli_errors
 @audited(tool="build_incident_timeline")
 def triage(
     events_file: Optional[Path] = typer.Option(

{vmware_debug-2.2.0 → vmware_debug-2.3.1}/vmware_debug/mcp_server/server.py

@@ -898,5 +898,8 @@ def main(
     )
 
 
+# Role metadata for network callers (HLD §18).
+import vmware_debug.policy_roles  # noqa: F401
+
 if __name__ == "__main__":
     main()

vmware_debug-2.3.1/vmware_debug/policy_roles.py

@@ -0,0 +1,27 @@
+"""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 the MCP server (roles apply only to a network
+MCP server). With a vmware-policy that has no roles module (< 1.24) nothing is
+declared.
+"""
+
+from __future__ import annotations
+
+from vmware_policy import skill_name
+
+#: Tools that give their holder more than a role. Host-path tools are added by
+#: policy while a file root is set.
+ESCAPES = frozenset()
+
+
+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,
+    )