In some prior blogs, we demonstrated leveraging NSX REST API with Python. See prior blogs, Automating Security Group and Policy Creation with NSX REST API and Automating VMware NSX Security Rules Creation using Splunk and Some Code. In this blog, we demonstrate how NSX REST API can be used with the popular Perl programming language.

One of Perl’s key strengths is the vast amount of Perl modules/libraries available via the Comprehensive Perl Archive Network (CPAN). There is also a CPAN module included with Perl which is used to automatically download and install additional Perl modules from the CPAN repository. The example Perl code in this post demonstrates a simple program that uses a Perl REST client module/library with NSX REST API to retrieve NSX SpoofGuard information.

The program does a query to get Virtual NICs that have the SpoofGuard state of Active. SpoofGuard is a feature that can prevent the spoofing of IP addresses by trusting an IP address of a VM upon first use. In this state the IP address will be Active. If the IP address is later changed, communication will be blocked unless the IP address change is manually approved. Figure 1 below displays the NSX lab setup used in this post.

The complete Perl code is shown further below; the script runs against an environment where each VM has one vNIC with both an IPv4 and IPv6 address. The program returns all Active Virtual NICs and associated information in regards to where SpoofGuard is enabled. NSX 6.2.2 and Perl 5.24.0.1 were utilized in this example.

The REST:Client module/library is used to provide the REST Client capabilities to communicate with NSX Manager. The XML:Simple library is used to easily read the XML output returned from the NSX REST API calls.

First, the respective needed libraries are imported into the program, respective variables to connect to NSX Manager are initialized, and then the NSX REST API call is made to get Active Virtual NICs and associated information in regards to SpoofGuard. It’s important to note that the REST:Client module used in this example is not part of the Perl standard library and must be installed manually. The Perl CPAN module/command was used to install the REST:Client module from the cli with the following command: cpan install REST:Client. The Data::Validate::IP library, used to validate IPv4 and IPv6 addresses, is also not part of the Perl standard library and was also installed via CPAN.



Within the code, once the respective data is returned in XML format via the respective NSX REST API call, the XMLin method of the XML:Simple object is used to read and parse the data. The results are looped through, and, for each entry/record, Nic Name, approved MAC address, approved IPv4 address, and approved IPv6 address is output.

Before running the Perl script, we confirm via the NSX GUI for SpoofGuard what the Active Virtual NICs are. The Web Policy SpoofGuard policy in Figure 2 below is enabled on the web-teir shown as the Web logical switch in Figure 1 above. Further, it can be seen that there are two entries, one for the Web VM with IP address 172.100.10.1 and another for the Web 3 VM with IP address 172.100.10.2; this correlates with the lab diagram. Since the SpoofGuard operation mode is set to Trust On First Use, both these respective VMs’ IP addresses are automatically initially trusted/approved and considered Active.

The Perl script is executed from the cli with the perl spoofguard_active_ips.pl command. The full code is shown below. The script could be run in Unix/Linux or Windows as long as the Perl interpreter and respective REST:Client and Data::Validate::IP Perl modules are installed.

#Script: spoofguard_active_ips.pl # #Description: Script runs against an environment where each VM has a single vNIC with both an IPv4 #and IPv6 address. The program returns all "Active" Virtual NICs in relation to SpoofGuard and #respective Nic Name, approved MAC Address, approved IPv4 Address, and approved IPv6 Address, #are output. Used with NSX 6.2.2 and Perl 5.24.0.1. For additional information, see the following #article: http://blogs.vmware.com/networkvirtualization/2016/04/nsx-automating-security-group.html # #Copyright © 2016 VMware, Inc. All Rights Reserved. #This script is provided as-is under GPLv2 license and with no guarantee, warranty, or support. # #See the below posted applicable license and notice. #GPL Projects COPYING File (GPLv2): http://blogs.vmware.com/networkvirtualization/gpl-projects-copying-gplv2 ‎ #GPL Projects NOTICE (GPLv2): http://blogs.vmware.com/networkvirtualization/gpl-projects-notice-gplv2 use REST::Client; #REST Client library used to make REST API calls use MIME::Base64; #library used for base64 encoding use XML::Simple; #library used for ease of reading XML use Data::Validate::IP qw(is_ipv4 is_ipv6); #library used to validate IPv4 and IPv6 addresses #uncomment below line if getting SSL connectivity/certificate error #$ENV{"PERL_LWP_SSL_VERIFY_HOSTNAME"} = 0; #disable certificate check #function to draw separator between records sub drawSeparator { print "--------------------

"; return; } #function to print heading sub printHeader { print "SpoofGuard Active Virtual NICs:



"; return; } #function creates and returns REST Client object #takes NSX Manager URL with IP address as argument sub getRestClient { #create REST Client object my ($arg) = @_; my $restclient = REST::Client->new(host => $arg); return $restclient; } #function calls respective NSX REST API call and returns results #takes REST Client object, NSX REST API call, base64 encoded #username and password, and REST API 'content-type' header variable #as arguments sub getXMLData { my ($client, $nsx_rest_spoofguard_active_api, $encoded_auth, $nsx_content_type) = @_; #make NSX REST API call to get "Active" Virtual NICs and respective info for spoofguard $client->GET($nsx_rest_spoofguard_active_api, {"Authorization" => "Basic $encoded_auth", "Accept" => $nsx_content_type}); $xmlResponse = new XML::Simple; #create object for ease of reading XML #read in respective XML data from NSX API response using XMLin method $xmlData = $xmlResponse->XMLin($client->responseContent(), KeyAttr => ['spoofguard']); return $xmlData } #initialize variables for connecting to NSX Manager and calling NSX REST API my $nsx_manager = "https://10.10.10.72"; my $nsx_username = "admin"; my $nsx_password = "notMyPassword!"; my $nsx_rest_spoofguard_active_api = "/api/4.0/services/spoofguard/spoofguardpolicy-5?list=ACTIVE"; my $nsx_content_type = "application/xml"; #use Base64 ecoding for transmitting respective data my $encoded_auth = encode_base64("$nsx_username:$nsx_password"); my $client = getRestClient($nsx_manager); #get REST Client object #get NSX REST API call result data my $xmlData = getXMLData($client, $nsx_rest_spoofguard_active_api, $encoded_auth, $nsx_content_type); printHeader(); #loop through respective results and for each entry/record, print Nic Name, #approved MAC Address, approved IPv4 Address, and approved IPv6 Address foreach $xmlRecord (@{$xmlData->{'spoofguard'}}) { drawSeparator(); print "Nic Name: \t\t" . $xmlRecord->{'nicName'} . "

"; print "Approved Mac Address: \t" . $xmlRecord->{'approvedMacAddress'} . "

"; $ip_address_1 = $xmlRecord->{'approvedIpAddress'}->{'ipAddress'}->[0]; $ip_address_2 = $xmlRecord->{'approvedIpAddress'}->{'ipAddress'}->[1]; if(is_ipv4($ip_address_1)) { print "Approved IPv4 Address:\t" . $ip_address_1 . "

"; print "Approved IPv6 Address:\t" . $ip_address_2 . "

"; } else { print "Approved IPv4 Address:\t" . $ip_address_2 . "

"; print "Approved IPv6 Address:\t" . $ip_address_1 . "

"; } } drawSeparator(); #uncomment below lines to see response status and headers #print "Response status: " . $client->responseCode() . "

"; #foreach ($client->responseHeaders()) #{ # print $_ . "=" . $client->responseHeader($_) . "

"; #} 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 #Script: spoofguard_active_ips.pl # #Description: Script runs against an environment where each VM has a single vNIC with both an IPv4 #and IPv6 address. The program returns all "Active" Virtual NICs in relation to SpoofGuard and #respective Nic Name, approved MAC Address, approved IPv4 Address, and approved IPv6 Address, #are output. Used with NSX 6.2.2 and Perl 5.24.0.1. For additional information, see the following #article: http://blogs.vmware.com/networkvirtualization/2016/04/nsx-automating-security-group.html # #Copyright © 2016 VMware, Inc. All Rights Reserved. #This script is provided as-is under GPLv2 license and with no guarantee, warranty, or support. # #See the below posted applicable license and notice. #GPL Projects COPYING File (GPLv2): http://blogs.vmware.com/networkvirtualization/gpl-projects-copying-gplv2 ‎ #GPL Projects NOTICE (GPLv2): http://blogs.vmware.com/networkvirtualization/gpl-projects-notice-gplv2 use REST : : Client ; #REST Client library used to make REST API calls use MIME : : Base64 ; #library used for base64 encoding use XML : : Simple ; #library used for ease of reading XML use Data : : Validate : : IP qw ( is_ipv4 is_ipv6 ) ; #library used to validate IPv4 and IPv6 addresses #uncomment below line if getting SSL connectivity/certificate error #$ENV{"PERL_LWP_SSL_VERIFY_HOSTNAME"} = 0; #disable certificate check #function to draw separator between records sub drawSeparator { print "--------------------

" ; return ; } #function to print heading sub printHeader { print "SpoofGuard Active Virtual NICs:



" ; return ; } #function creates and returns REST Client object #takes NSX Manager URL with IP address as argument sub getRestClient { #create REST Client object my ( $ arg ) = @ _ ; my $ restclient = REST : : Client - > new ( host = > $ arg ) ; return $ restclient ; } #function calls respective NSX REST API call and returns results #takes REST Client object, NSX REST API call, base64 encoded #username and password, and REST API 'content-type' header variable #as arguments sub getXMLData { my ( $ client , $ nsx_rest_spoofguard_active_api , $ encoded_auth , $ nsx_content_type ) = @ _ ; #make NSX REST API call to get "Active" Virtual NICs and respective info for spoofguard $ client - > GET ( $ nsx_rest_spoofguard_active_api , { "Authorization" = > "Basic $encoded_auth" , "Accept" = > $ nsx_content_type } ) ; $ xmlResponse = new XML : : Simple ; #create object for ease of reading XML #read in respective XML data from NSX API response using XMLin method $ xmlData = $ xmlResponse - > XMLin ( $ client - > responseContent ( ) , KeyAttr = > [ 'spoofguard' ] ) ; return $ xmlData } #initialize variables for connecting to NSX Manager and calling NSX REST API my $ nsx_manager = "https://10.10.10.72" ; my $ nsx_username = "admin" ; my $ nsx_password = "notMyPassword!" ; my $ nsx_rest_spoofguard_active_api = "/api/4.0/services/spoofguard/spoofguardpolicy-5?list=ACTIVE" ; my $ nsx_content_type = "application/xml" ; #use Base64 ecoding for transmitting respective data my $ encoded_auth = encode_base64 ( "$nsx_username:$nsx_password" ) ; my $ client = getRestClient ( $ nsx_manager ) ; #get REST Client object #get NSX REST API call result data my $ xmlData = getXMLData ( $ client , $ nsx_rest_spoofguard_active_api , $ encoded_auth , $ nsx_content_type ) ; printHeader ( ) ; #loop through respective results and for each entry/record, print Nic Name, #approved MAC Address, approved IPv4 Address, and approved IPv6 Address foreach $ xmlRecord ( @ { $ xmlData - > { 'spoofguard' } } ) { drawSeparator ( ) ; print "Nic Name: \t\t" . $ xmlRecord - > { 'nicName' } . "

" ; print "Approved Mac Address: \t" . $ xmlRecord - > { 'approvedMacAddress' } . "

" ; $ ip_address_1 = $ xmlRecord - > { 'approvedIpAddress' } - > { 'ipAddress' } - > [ 0 ] ; $ ip_address_2 = $ xmlRecord - > { 'approvedIpAddress' } - > { 'ipAddress' } - > [ 1 ] ; if ( is_ipv4 ( $ ip_address_1 ) ) { print "Approved IPv4 Address:\t" . $ ip_address_1 . "

" ; print "Approved IPv6 Address:\t" . $ ip_address_2 . "

" ; } else { print "Approved IPv4 Address:\t" . $ ip_address_2 . "

" ; print "Approved IPv6 Address:\t" . $ ip_address_1 . "

" ; } } drawSeparator ( ) ; #uncomment below lines to see response status and headers #print "Response status: " . $client->responseCode() . "

"; #foreach ($client->responseHeaders()) #{ # print $_ . "=" . $client->responseHeader($_) . "

"; #}

Once the above script completes running, the below output is generated on the console/terminal. As you can see, the results match what is displayed in the GUI in Figure 2.

In this example, entries with SpoofGuard state of ACTIVE are shown. To see entries with other SpoofGuard states, we can simply modify the key value pair at the end of the query. For example, to see entries with REVIEW_PENDING state, the list=ACTIVE key value pair at the end of the NSX REST API call can be changed to list=REVIEW_PENDING. In the code above, the $nsx_rest_spoofguard_active_api variable can be changed to /api/4.0/services/spoofguard/spoofguardpolicy-5?list=REVIEW_PENDING. Note, for purposes of calling the NSX REST API, the default policy ID is always spoofguardpolicy-1. If custom policies have been created, the policy ID can be retrieved via REST API Get call with the following URL: https://[NSX Manager IP Address]/api/4.0/services/spoofguard/policies/.



In Figure 2, it can be seen there are no entries that need review as shown by the 0 under the Need Review column. For demonstration, the IP address of the Web VM with IP address 172.100.10.1 is changed to 172.100.10.3 and the IP address of Web 3 VM with IP address 172.100.10.2 is changed to 172.100.10.4. These IP address changes are detected by SpoofGuard. As shown in Figure 4 below, before the VMs are allowed to communicate using the new respective IP addresses, the changes must be approved. The column Need Review has also changed to 2 as expected. Selecting the Virtual Nics IP Required Approval option from the drop down box, displays the entries needing review/approval. Note, the Approved IPv4 Address and Detected IPv4 Address for each of the two entries respectively is different.

If in the Perl code, the $nsx_rest_spoofguard_active_api variable is changed to /api/4.0/services/spoofguard/spoofguardpolicy-1?list=REVIEW_PENDING, information can be displayed about IP Addresses that SpoofGuard has blocked and need review/approval. As can be seen in Figure 5 below, the correct results are displayed, matching the results shown by the GUI in Figure 3. Note, additional fields and respective code was added to show the corresponding detected MAC and IP Addresses. These new fields correspond to the detectedMacAddress and detectedIPAddress data fields that can be obtained from the $xmlRecord variable within the script. The respective title/header for results was also updated.

In this blog we demonstrated a simple example of using Perl with NSX REST API to retrieve and display information about SpoofGuard. However, larger monitoring or management systems/applications can be built leveraging the NSX REST API with any programming language capable of interacting with a REST API service.; many REST API Client libraries exist for popular languages such as Python, Perl, PowerShell, and Java. For additional information on NSX 6.2 API, see the NSX 6.2 REST API Guide.