zw008/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
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:
For a **truly air-gapped host**, build the wheels on a connected machine and copy
them over — the target then needs no network:
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+):
Add to ~/.claude.json:
Alternative: uvx (no install) or legacy entry point
> **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
Tag a VM
Trace a Packet
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