VMware Policy

Author: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com This is a community-driven project by a VMware engineer, not an official VMware product. For official VMware developer tools see developer.broadcom.com.

Unified audit logging, policy enforcement, and sanitization for the VMware MCP skill family.

Install

pip install vmware-policy

Usage

from vmware_policy import vmware_tool

@vmware_tool(risk_level="high", sensitive_params=["password"])
def delete_segment(name: str, env: str = "") -> dict:
    ...

Reporting a failure the tool returns

Most tools signal failure by raising, and @vmware_tool records that. A tool that instead catches the exception and returns an error payload looks identical to a successful call — and for a long time was recorded as one, which also meant undo tokens were written for changes that never happened and the circuit breaker never saw a failure.

Dict-shaped payloads are now detected automatically. Nothing to do if a tool returns the family shape:

return {"error": msg, "hint": "Run 'vmware-nsx doctor'."}   # audited as a failure

A tool whose return type cannot carry that marker — one handing back console text, say — must say so explicitly:

from vmware_policy import report_tool_failure

except Exception as exc:
    report_tool_failure(str(exc))
    return f"Error: {msg}"

Strings are deliberately not sniffed: skills that return console output can emit text beginning with "Error:" as data, and marking those calls failed would be the same misreport in the opposite direction.

CLI

vmware-audit log --last 20
vmware-audit log --status denied --since 2026-03-28
vmware-audit stats --days 7
vmware-audit policy          # which rules are in force

Components

Architecture

AI Agent -> vmware-pilot (optional orchestration) -> @vmware_tool pre-check -> skill operation -> audit row -> ~/.vmware/audit.db

vmware-policy is a mandatory dependency of every VMware skill. It provides:

• Audit logging: calls to MCP tools wrapped by @vmware_tool are recorded in the unified database ~/.vmware/audit.db
• Policy engine: deny rules and maintenance window, hot-reloaded without a restart (change limits are a reserved field and not enforced)
• Input sanitization: all text from the vSphere/NSX/Aria APIs passes through sanitize()
• AI agent detection: records the caller from its environment: claude, codex, deerflow, local (an Ollama host) or unknown

Policy rules

Read/write authorization belongs to the vCenter/NSX account's RBAC. The policy engine only adds the operator's own deny rules and maintenance window, from ~/.vmware/rules.yaml ($OPS_HOME/rules.yaml if set). vmware-audit policy reports which source is in force:

PyYAML is a declared dependency; if it is missing, decorated tool calls fail rather than run. Rules hot-reload on file change.

VMWARE_POLICY_DISABLED=1 is an operator escape hatch: in the process that has it set (the MCP host, or a CLI shell) every policy check is skipped, including the unreadable-rules denial. Auditing continues -- each bypassed check logs a warning, and rows from both surfaces -- @vmware_tool MCP calls and @guarded CLI commands -- are recorded with a _bypassed status suffix (ok_bypassed, error_bypassed). Restrict who can set the MCP host's environment.

Copy the default rules to ~/.vmware/rules.yaml and customize them:

# Deny rules -- block specific operations
deny:
  - name: no-delete-in-prod
    operations: ["delete_*", "remove_cluster_host"]
    environments: ["production"]
    reason: "Destructive operations are not allowed in production"

# Maintenance window -- high/critical operations allowed only inside the window
maintenance_window:
  start: "22:00"
  end: "06:00"

# Change limits -- reserved field, not enforced today (the engine has no prior
# state to compute a delta from; configuring it only logs a "not enforced" warning)
change_limits:
  max_cpu_change_pct: 20
  max_memory_change_pct: 50

Rule changes hot-reload; no service needs a restart.

Tool exposure

Every skill's MCP server can offer a subset of its tools. <cli> mcp --expose read (or VMWARE_<SKILL>_MCP_EXPOSE=read) keeps only tools annotated readOnlyHint: true; --allow-write a,b (or VMWARE_<SKILL>_MCP_ALLOW_WRITE) keeps chosen write tools on top. A tool without the annotation counts as a write. An unknown value, or a name that is not a write tool of that server, stops the server before it serves (exit 2). Pre-2.0 tool names are accepted.

A launcher that imports a server object directly can use the same code instead of the SDK's private registry:

from vmware_policy.exposure import restrict_tools

restrict_tools(mcp, skill="storage", expose="read", allow_write=["enable_iscsi"])
mcp.run(transport="streamable-http")

Inside a running event loop use await arestrict_tools(...). The server object only needs the SDK's public list_tools() and remove_tool(). restrict_tools does not read the environment; to honour VMWARE_<SKILL>_MCP_* the way <cli> mcp does, pass *settings("storage") (or call apply_or_exit). If either flag is given, the environment is ignored for both, so the two sources never mix.

A tool that runs other steps (a plan, workflow or batch tool) carries every write it can execute, including writes the exposure hides.

This limits what clients are offered. It is not authorization: the account's permissions decide what a call may change, and deny rules still apply to every exposed tool.

Serving MCP over HTTPS

vmware_policy.serve runs a skill's MCP server on stdio (default), on HTTPS, or on loopback HTTP behind a TLS-terminating reverse proxy. Both network transports require bearer tokens; nothing binds without one.

vmware-audit token create alice      # prints the token once; only its sha256 is stored (0600)
vmware-audit token list
vmware-audit token revoke alice      # running servers refuse it from the next request

• Tokens live in $OPS_HOME/mcp-tokens (default ~/.vmware). Clients send Authorization: Bearer <token>.
• https needs --cert/--key (PEM) and --public-name for every host name clients use; requests for any other Host or Origin are refused (DNS-rebinding protection). http binds 127.0.0.1/::1/localhost only.
• Each audit row records the caller as token:<name> and the surface (mcp-https, mcp-http-loopback).
• Calls naming the same target run one at a time; calls naming different targets run in parallel; a call that names no target (the skill's default target, or a tool without a target parameter) runs alone. Waiting calls are served first come, first served, so neither kind can starve the other; to get parallelism, name the target. The runaway breaker is per caller. Skills that keep a session pool (below) lift these limits.
• A session can only be used by the token name that created it (the SDK enforces this). Revoking a token and creating a new one under the same name lets the new token continue the old sessions, so use a new name when a token leaks. Idle sessions expire after 30 minutes.
• Deny rules can name callers: clients: ["intern-*"] in $OPS_HOME/rules.yaml matches those token names only (stdio and CLI calls are not matched by such a rule).
• Before it binds, the server sends itself unauthenticated POST/GET/DELETE requests and refuses to start unless all three get 401.
• Every caller of an endpoint acts with that server's account. Tokens identify callers; they authorize nothing at the platform. Run one endpoint per privilege level and per group of people who may see each other's work.

Session pools

A skill that connects to a platform can keep a small pool of sessions per target (vmware_policy.pool.SessionPool, VMWARE_MCP_POOL_SIZE, default 2) and start its server with run_server(..., pooled=True). Over a network transport each call then holds its own session per target for its whole body (tools return plain data, so nothing is read from the session after it), so calls on one target run side by side up to the pool size and calls that name no target are not serialized. A call that already holds a session never waits for another target; if that target's pool is busy it gets a temporary extra session, so multi-target calls cannot deadlock. A call that waits longer than 300 s for a session gets an error naming the target. Each session is a login on the target. stdio and the CLI keep one cached session per target, separate from the pooled ones.

Access self-diagnosis

vmware_policy.access.vsphere_access_info(si, target=, requirements=, tool=) backs each vSphere skill's get_access_info tool: the account the target uses, the privileges each tool needs (from the skill's requirements table) and whether the current session holds them on the root folder (AuthorizationManager.HasPrivilegeOnEntities, which needs only System.View). "Not granted at the root" is not "no access": permissions on specific objects are not covered. A lookup that fails is undetermined, never granted.

Risk levels

The level a tool declares is recorded in the audit row, can be matched by a deny rule's min_risk_level, and decides whether a configured maintenance window applies. It does not by itself gate execution.

VMware Skill Family

Security

• The audit database (~/.vmware/audit.db, local only, 0700 directory / 0600 files) records tool parameters, results, status, OS user and inferred agent -- treat it and its archives as sensitive.
• Parameters named in sensitive_params are stored as ***; results from tools declaring sensitive_result=True are replaced; credential-named keys (password, token, kubeconfig, ...) in parameters and results, and credential-shaped text in error messages, are redacted on both the MCP and CLI surfaces. A credential under a key name not on that list must be declared in sensitive_params.
• sanitize() guards against prompt injection through API response text.
• Policy bypass (VMWARE_POLICY_DISABLED=1) skips policy checks, not auditing.

Development

git clone https://github.com/vmware-skills/VMware-Policy.git
cd VMware-Policy
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest --cov=vmware_policy

License

MIT