VMware NSX Security

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.

VMware NSX DFW microsegmentation and security MCP skill — 22 tools for distributed firewall policies/rules, security groups, VM tags, the DFW exclusion list, Traceflow packet tracing, and IDPS.

Companion skills: vmware-nsx (networking), vmware-aiops (VM lifecycle), vmware-monitor (monitoring)

Quick Start

uv tool install vmware-nsx-security

mkdir -p ~/.vmware-nsx-security
cp config.example.yaml ~/.vmware-nsx-security/config.yaml
# Edit config.yaml with your NSX Manager host

echo "VMWARE_NSX_SECURITY_NSX_PROD_PASSWORD=your_password" > ~/.vmware-nsx-security/.env
chmod 600 ~/.vmware-nsx-security/.env

vmware-nsx-security doctor

Offline / Air-Gapped Install (from source)

This project uses the modern PEP 517 build system (hatchling), so there is no setup.py by design — that is expected, not a missing file. If you cloned the source and hit ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build, your pip is older than 21.3 and cannot do an editable (-e) install with a non-setuptools backend. Editable mode is a developer convenience, not needed to run the tool — do one of:

# From the source tree — a normal (non-editable) install builds a wheel:
pip install .              # NOT  pip install -e .

# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .

For a truly air-gapped host, build the wheels on a connected machine and copy them over — the target then needs no network:

# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)

# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-nsx-security

What It Does

Category	Tools
DFW Policy	list, get, create, update, delete, list rules
DFW Rules	create, update, delete, stats
Security Groups	list, get, create, delete
VM Tags	list tags, apply tag, remove tag
Traceflow	run trace, get result
IDPS	list profiles, signature status + settings
DFW Exclusions	list excluded members

Total: 22 MCP tools (11 read-only + 11 write)

DFW exclusion list

A VM on the NSX distributed-firewall exclusion list has no DFW in its datapath: the rules that name it exist and none of them applies. On a VCF estate the management VMs (vCenter, VCF Operations, NSX managers) are commonly on it — one real NSX 9.1 fabric had 10 of 12 VMs excluded. list_dfw_exclusions shows the list, and list_vm_tags / get_group / list_dfw_policies say when a member is excluded, so "protected by DFW policy" is never reported for a VM the DFW does not see. dfw_excluded: null means the list could not be read — which is not false.

MCP Server Setup

After uv tool install vmware-nsx-security, start the MCP server with one command (v1.5.15+):

# Recommended — single command, no network re-resolve
vmware-nsx-security mcp

# With a custom config path
VMWARE_NSX_SECURITY_CONFIG=/path/to/config.yaml vmware-nsx-security mcp

Add to ~/.claude.json:

{
  "mcpServers": {
    "vmware-nsx-security": {
      "command": "vmware-nsx-security",
      "args": ["mcp"],
      "env": {
        "VMWARE_NSX_SECURITY_CONFIG": "~/.vmware-nsx-security/config.yaml"
      }
    }
  }
}

Alternative: uvx (no install) or legacy entry point

# Run without installing (requires PyPI access each launch)
uvx --from vmware-nsx-security vmware-nsx-security mcp

# Legacy entry point (still works, kept for backward compatibility)
vmware-nsx-security-mcp

Behind a corporate TLS proxy? uvx may fail with invalid peer certificate: UnknownIssuer. Use the recommended vmware-nsx-security mcp form above (no network needed), or set UV_NATIVE_TLS=true.

Common Workflows

Microsegment an Application

# 1. Create groups by tag — via the create_group MCP tool
#    (tag_scope=tier, tag_value=web → matched as Condition value "tier|web";
#     multiple criteria types — tag/IP/segment — are ORed)

# 2. Create DFW policy
vmware-nsx-security policy create web-app-policy --name "Web to App" --category Application

Tag a VM

# Find VM and its external ID
vmware-nsx-security tag list my-vm-01

# Apply tag using the external ID
vmware-nsx-security tag apply <external-id> --scope tier --value web

Trace a Packet

vmware-nsx-security traceflow run <src-lport-id> \
  --src-ip 10.0.1.5 --dst-ip 10.0.2.10 --proto TCP --dst-port 443

Output reports operation_state (IN_PROGRESS/FINISHED/FAILED), hop-by-hop observations discriminated by resource_type (Dropped* entries carry reason + acl_rule_id), and a dfw_hits summary.

Safety

Dependency checks: Cannot delete a policy with active rules, or a group referenced by DFW or gateway-firewall rules/scopes or by a parent group; group deletion aborts if the reference scan fails
Audit logging: All write ops logged to ~/.vmware-nsx-security/audit.log
Input validation: IDs validated; all API text sanitized against prompt injection
Dry-run mode: All CLI write commands support --dry-run
MCP delete preview: delete_dfw_policy, delete_dfw_rule and delete_group preview by default — without confirm=True they return blast_radius (what would be removed, blockers, unmeasured) and delete nothing; confirm=True is refused while a blocker remains or a read failed
Credential safety: Passwords only from env vars, never in config files

Companion Skills

Skill	Scope	Tools	Install
vmware-aiops ⭐ entry point	VM lifecycle, deployment, guest ops, clusters	49	`uv tool install vmware-aiops`
vmware-monitor	Read-only monitoring, alarms, events, VM info	27	`uv tool install vmware-monitor`
vmware-nsx	NSX networking: segments, gateways, NAT, IPAM	33	`uv tool install vmware-nsx-mgmt`
vmware-storage	Datastores, iSCSI, vSAN	11	`uv tool install vmware-storage`
vmware-vks	Tanzu Namespaces, TKC cluster lifecycle	20	`uv tool install vmware-vks`
vmware-aria	Aria Ops metrics, alerts, capacity planning	28	`uv tool install vmware-aria`

Version Compatibility

NSX Version	Support	Notes
NSX 9.1 / VCF 9.1	✅ Full	DFW + Security Group + Traceflow + IDS/IPS via Policy API. VDS 7.0+ required (N-VDS removed in NSX 9).
NSX 9.0 / VCF 9.0	✅ Full	Same as 9.1. Bare-metal NSX agent removed.
NSX 4.x / VCF 5.x	✅ Full	All features supported.
NSX-T 3.2 / VCF 4.5	✅ Full	Policy API stable.

Official Broadcom References

SDKs: https://developer.broadcom.com/sdks — VMware NSX for Python SDK (future migration target)
REST APIs: https://developer.broadcom.com/xapis — NSX-T Data Center REST API
CLI Tools: https://developer.broadcom.com/tools — VCF PowerCLI 9.1

License

MIT

Development Status
- 4 - Beta
License
- OSI Approved :: MIT License
Programming Language
- Python :: 3
Topic
- Security
- System :: Networking

Metadata

Development Status
- 4 - Beta
License
- OSI Approved :: MIT License
Programming Language
- Python :: 3
Topic
- Security
- System :: Networking

Release files for vmware-nsx-security 1.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vmware-nsx-security 1.13.0
File	Size	Uploaded
vmware_nsx_security-1.13.0.tar.gz	332.8 kB	Sep 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vmware-nsx-security 1.13.0
File	Interpreter	ABI	Platform	Reset
vmware_nsx_security-1.13.0-py3-none-any.whl 94.9 kB Sep 20, 2026	Python 3	none	any	Details

Total release size: 427.7 kB

Release files / vmware_nsx_security-1.13.0.tar.gz

Download URL	vmware_nsx_security-1.13.0.tar.gz
Size	332.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`2c81f2b8e92980e75f5bae1795a716ab5ef75a0b85327677fbc86280b65939fe`
BLAKE2b-256 checksum How to use checksums	`6a611226c1c8ef0a5a6e6aaa47907407bb55975f32bfd22ebc9b424100eaf407`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.12`

Release files / vmware_nsx_security-1.13.0-py3-none-any.whl

Download URL	vmware_nsx_security-1.13.0-py3-none-any.whl
Size	94.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b0a0467749f89f00dc291ef4e786c1d743cf42b441715cc2c59ab60d6f8867ff`
BLAKE2b-256 checksum How to use checksums	`8d26ef8243ababc356b1aad6734c2c9d342a11a30c261d0994de5bdc7b55e8fb`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.12`