VMware NSX Security

[WRITE] Apply an NSX tag to a virtual machine. Returns {"status": "applied", "vm_id", "scope", "tag"} — not the VM's tag list. Use list_vm_tags first for the vm_id, and again after to see the result. Additive, so existing tags survive, but note that tag-based group membership shifts as NSX re-evaluates: check with get_group.

[WRITE] Create a new DFW security policy. Returns the created policy dict (id, path, category, ...), else {"error", "hint"}. The policy is an empty container — rules must be added afterwards with create_dfw_rule.

[WRITE] Create a firewall rule under an existing DFW security policy. Returns the created rule dict (id, path, action, ...), else {"error", "hint"}; a bad action/direction/ip_protocol lists the valid values. PUT semantics: reusing a rule_id overwrites that rule, enforced immediately unless disabled=True. Pick policy_id with list_dfw_policies first; prefer update_dfw_rule to edit one and delete_dfw_rule to remove one.

[WRITE] Create an NSX security group with optional membership criteria. Returns the created group dict (id, path, expression, ...). Criteria are ORed — NSX only permits AND between same-member-type Conditions: tag_scope/tag_value matches VMs carrying that tag, ip_addresses matches IPs or CIDRs, segment_paths every VM on those segments. Use it before create_dfw_rule, which references the group path; confirm members with get_group.

[WRITE] Delete a DFW security policy; refuses while it still holds rules. Without confirm=True this only previews: it returns blast_radius (the policy's name, category, sequence_number, rule_count and rule_ids, blockers, unmeasured) and deletes nothing. Show that to the user and get their decision. Do not set confirm=True on your own because the user asked to delete earlier: they have not seen the blast radius yet. confirm=True refuses, deleting nothing, while the policy still holds rules — list them with list_dfw_rules and clear each with delete_dfw_rule first — or when its rules could not be read. Returns {"action": "preview" | "deleted", "blast_radius": ...}, else {"error", "hint", "blast_radius"?}.

[WRITE] Permanently delete one DFW rule from its parent security policy. Irreversible and immediate: traffic it matched falls through to lower-priority rules or the policy default. Without confirm=True this only previews: it returns blast_radius (the parent policy, the rule's action, sources, destinations, services, scope, direction, disabled flag, blockers, unmeasured) and deletes nothing. Show that to the user and get their decision. Do not set confirm=True on your own because the user asked to delete earlier: they have not seen the blast radius yet. Check recent hits with get_dfw_rule_stats first; prefer update_dfw_rule with disabled=True when you may need the rule back. A rule_id not in the policy is an error, and confirm=True refuses when the rules could not be read. To remove a whole policy use delete_dfw_policy — it refuses while rules remain. Returns {"action": "preview" | "deleted", "blast_radius": ...}, else {"error", "hint", "blast_radius"?}.

[WRITE] Delete an NSX security group; refuses while anything references it. Use it once get_group shows the group is unwanted. Without confirm=True this only previews: it returns blast_radius (the group's name, path, expression_count, reference_count and references, blockers, unmeasured) and deletes nothing. Show that to the user and get their decision. Do not set confirm=True on your own because the user asked to delete earlier: they have not seen the blast radius yet. confirm=True refuses if anything still references the group (parent groups from NSX's group-associations API; DFW and gateway-firewall rules and policy applied-to, by walking the rules), and refuses if that check itself fails (fail-safe). When the refusal names a DFW rule, retarget it with update_dfw_rule or drop it with delete_dfw_rule first. Returns {"action": "preview" | "deleted", "blast_radius": ...}, else {"error", "hint", "blast_radius"?}.

[READ] Get full details of a single DFW security policy. Returns one policy object, not an envelope: category, sequence_number, stateful, scope and rule count. Use it once list_dfw_policies has narrowed to one id — never a display name. Then call list_dfw_rules for the rules inside.

[READ] Get packet/byte hit-count statistics for a DFW rule. Returns one flat stats object, not an envelope: packet_count, byte_count, session_count, hit_count, popularity_index. Use it before update_dfw_rule or delete_dfw_rule to see if a rule still matches traffic; counters are cumulative and may read zero on a new rule. Ids come from list_dfw_rules.

[READ] Get details of a security group including membership criteria and effective members. Returns one group object: its expression rules, member_count (the group's real size), and members — an envelope holding at most the first 50 effective VirtualMachine members, whose truncated flag says whether more were withheld. Report member_count as the size; counting members.items reports the sample instead. Use it once list_groups has narrowed to one id; membership is evaluated by NSX, so a tag written with apply_vm_tag may take seconds to appear.

[READ] Get IDPS signature status and global IDS settings. Returns one bundle, not an envelope: 'signature_status' (scalar fields of the signature bundle status, e.g. version/update state — names vary by NSX release) and 'settings' (auto_update, ids_events_to_syslog). Use it first to confirm IDS is on and current, then list_idps_profiles for the profiles. No per-signature or per-event detail, and 'signature_status' may be empty where IDS was never enabled.

[READ] Get the current state and observations of an existing Traceflow. Use this to check a previously initiated traceflow without waiting. Returns operation_state (IN_PROGRESS / FINISHED / FAILED) and observations typed by resource_type; Dropped* ones carry reason and acl_rule_id. Only a traceflow run_traceflow left IN_PROGRESS at its timeout is still on the manager — a completed one is deleted server-side and its id 404s here.

[READ] List the DFW exclusion list — the members no distributed-firewall rule reaches. Read this before answering any question about a VM being micro-segmented or protected by DFW policy. A VM on this list has no DFW in its datapath: rules that name it, groups that contain it and policies scoped to it all still exist and none of them apply. On a VCF estate the management VMs (vCenter, VCF Operations, NSX managers) are commonly on it. Returns the list envelope. 'items' holds one row per excluded member: the group 'path', its 'id' and 'display_name', the 'virtual_machines' in it and 'vm_count'. A row with 'members_error' is a group whose members could not be read — that is not an empty group, so do not read it as one. 'scope' says which list answered: "system_and_user" includes NSX's own system-owned exclusions, "user" means this manager refused that variant and system exclusions are NOT in the answer. An empty list under "user" is not proof that nothing is excluded. Page with 'next_offset': pass the value back as 'offset' and stop when it is null. The list holds at most 100 groups, so one page is normally all of it.

[READ] List DFW security policies in the default domain. Start here. Returns the list envelope: 'items' holds each policy's id, display_name, category, sequence_number, stateful flag and rule count; 'returned'/'limit'/'total'/'truncated'/'hint' say whether the page is the whole answer — never read a full page as complete, narrow with name_filter or page with offset. Then get_dfw_policy for one policy's detail, or list_dfw_rules for the rules inside. Page with 'next_offset': pass the value back as 'offset' and stop when it is null. Do not loop on 'truncated' — that says this page is not the whole collection, which stays true on the last page of a walk. 'rule_count' is null when NSX did not report one — that means "not retrieved", NOT "no rules", so do not conclude a null policy enforces nothing; call list_dfw_rules on it. Passing name_filter makes every count null (it is resolved via the Policy Search API, which carries no rule counts). A null anywhere adds 'rule_count_note' to the envelope.

[READ] List rules in a DFW security policy. Returns the list envelope: 'items' holds each rule's id, display_name, action, sources, destinations, services, direction, disabled flag and sequence number; 'returned'/'limit'/'truncated'/'hint' say whether the page is complete. 'total' is always null here — a full page reports truncated=true and must be paged with offset; one Application policy can hold thousands of rules. Get policy_id from list_dfw_policies; then get_dfw_rule_stats for a rule's hit counts. Page with 'next_offset': pass the value back as 'offset' and stop when it is null. Do not loop on 'truncated' — that says this page is not the whole collection, which stays true on the last page of a walk.

[READ] List NSX security groups in the default domain. Returns the list envelope: 'items' holds each group's id, display_name, description and expression count; 'returned'/'limit'/'total'/ 'truncated'/'hint' say whether the page is the whole answer — never read a full page as complete, narrow with name_filter or page with offset. Then get_group for one group's criteria and effective members. Page with 'next_offset': pass the value back as 'offset' and stop when it is null. Do not loop on 'truncated' — that says this page is not the whole collection, which stays true on the last page of a walk.

[READ] List IDPS profiles configured in NSX. Returns the list envelope: 'items' holds each profile's id, display_name, profile_severity (comma-joined), criteria (filter_name/filter_value pairs, e.g. ATTACK_TYPE or CVSS) and overridden signature count; 'returned'/'limit'/'total'/'truncated'/ 'hint' say whether the page is the whole answer — never read a full page as complete, narrow with name_filter or page with offset. Then get_idps_status for the signature-bundle version and IDS settings. Page with 'next_offset': pass the value back as 'offset' and stop when it is null. Do not loop on 'truncated' — that says this page is not the whole collection, which stays true on the last page of a walk.

[READ] List all NSX tags applied to a virtual machine. Returns the list envelope: 'items' holds the VM's scope/tag pairs and 'vm_id' the fabric UUID apply_vm_tag and remove_vm_tag require — call this first to get it. Tags always arrive in one response, so 'truncated' is always false and empty 'items' means the VM really has no tags. 'tags' is a deprecated pre-1.8.0 alias of 'items', removed in 2.0 — read 'items'. Returns {"error", "hint"} if no VM matches, or several do.

[WRITE] Remove an NSX tag from a virtual machine. Returns {"status": "removed", "vm_id", "scope", "tag"}, not the VM's remaining tags. Only the exact scope/value pair is removed — other tags survive. Removing a tag changes dynamic group membership immediately — groups with tag Conditions stop matching the VM — so re-check with get_group. Use list_vm_tags first to confirm the pair.

[WRITE] Run a Traceflow to trace a packet's path through the NSX overlay. Injects a synthetic probe from the source port. Returns traceflow_id, operation_state (IN_PROGRESS / FINISHED / FAILED) and hop-by-hop observations typed by resource_type; Dropped* ones carry reason and acl_rule_id. Use it to find which DFW rule drops a flow, then get_dfw_rule_stats on that rule. A FINISHED traceflow is deleted server-side and its id 404s; only one still IN_PROGRESS at timeout_seconds survives for get_traceflow_result to poll.

[WRITE] Partially update a DFW security policy (PATCH — only provided fields change). Returns the updated policy dict; omitted arguments keep their values, so read them with get_dfw_policy first. Use it to rename or re-prioritise the policy itself — to change a rule inside use update_dfw_rule.

[WRITE] Partially update a DFW rule (PATCH — only provided fields change). Returns the updated rule dict; omitted arguments keep their values, so read them with list_dfw_rules first. Use it to retarget, re-prioritise or disable a rule — to add one use create_dfw_rule, to remove one delete_dfw_rule.