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

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"
      }
    }
  }
}

# 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

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

Version Compatibility

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