Managing IP Routes Through WMI

Managing the IP routes that direct computers and users to your network resources is an important aspect of Windows management, especially on systems that function as RAS or VPN servers and act as gateways for mobile users. And as rare as IP route­configuration changes are in many enterprises, monitoring them is important from a security standpoint because some intruders attempt to modify or add routes to gain access to your enterprise resources. You can use the route.exe utility to add, view, and delete IP routes, but route.exe has limitations--primarily, its inability to manage IP routes remotely. Fortunately, if your systems run Windows Server 2003 or Windows XP, you can use Windows Management Instrumentation (WMI) and two WMI IP Route provider instances--RouteEventProvider and RouteProvider--to overcome that limitation and examine, modify, and monitor the IP version 4 (IPv4) routing table from any Windows 2003 or XP system. RouteEventProvider is an event provider that can trigger WMI events to notify you of additions, modifications, or deletions to the routing table. RouteProvider is an instance provider that provides access to routing table information. These providers are available in the rootcimv2 namespace and support the classes listed in Web Table 1.

Catching Changes

Before digging into the code that you can use to manage the IP routing table, let's look at how to monitor changes to the table. I've created a script, GenericEventAsyncConsumer.wsf, that submits WMI Query Language (WQL) event queries to get notifications about routing-table modifications. You can download the script, which is included in the 43024.zip file.

To receive notification that a change has been made to the routing table, use the following command, which references the Win32_IP4RouteTableEvent class, to launch the script on the local system. (Although some of the commands I mention in this article are printed on multiple lines, you should enter all commands on one line.)

GenericEventAsyncConsumer.wsf   "Select * From   Win32_IP4RouteTableEvent"

When you run this query on a system, the script will output information similar to the text that Web Figure 1 shows whenever the IP routing table on that system is modified.

As you can see in Web Figure 1, the Win32_IP4RouteTableEvent class provides only timestamp information specifying when the change occurred. If you want to determine what was added to or deleted from the table, you must use a query that leverages the capabilities of the RouteProvider instance provider. To detect an addition to the routing table, use the following command:

Select * From  __InstanceCreationEvent   Within 10  Where TargetInstance ISA   "Win32_IP4RouteTable"

To track a deletion from the routing table, use the command

Select * From   __InstanceDeletionEvent   Within 10  Where TargetInstance ISA   "Win32_IP4RouteTable"

These two queries ask WMI to poll the routing table every 10 seconds to determine whether a route has been added or deleted. By exploiting the TargetInstance object in the returned WMI event, the script can determine which route was added or deleted.

Note that I don't provide a command that uses the __InstanceModificationEvent class to tell GenericEventAsyncConsumer.wsf to detect routing table modifications. Because the system constantly refreshes the routing table, which in turn constantly uses the __InstanceModificationEvent class to generate event-modification notifications for subscribers, doing so would require the script to use the Win32_IP4RouteTableEvent class to retrieve notifications about any changes in the routing table, then compare the new state of the table with its original state. This requirement supposes that the script logic reads the table's content at start-up to determine the table's original state, but GenericEventAsyncConsumer.wsf is a generic script that doesn't implement that logic. I'll show you later in the article how to retrieve and display the routing table information.

Also, note the difference in behavior between the first query, which exploits RouteEventProvider and doesn't wait to notify the WMI event consumer (which can be an application or a script), and the latter two queries, which exploit RouteProvider and poll the table every 10 seconds. The first query illustrates how event providers notify subscribing WMI consumers as soon as an event occurs.

Managing the IP Routing Table from a WMI Script

I've written another WMI script, WMIIP4Route.wsf (included in the 43024.zip file, along with two VBScript files that contain helper functions), that provides all functions to manage the content of the routing table from the command line. To do so, the script uses the Win32_IP4RouteTable, Win32_IP4PersistedRouteTable, and Win32_ActiveRoute classes. The script also uses the Windows Script Host (WSH) 5.6 XML command-line parsing technique that I discuss in "Secure Script Execution with WSH 5.6," August 2002, InstantDoc ID 25644.

WMIIP4Route.wsf uses parameters similar to those that route.exe uses. For example, you can retrieve the routing table's content by using the PRINT parameter, which produces output similar to the route.exe PRINT command. (For a list of all supported route.exe parameters and options, run route.exe, without parameters, from the command line.) So, what's the added value of WMIIP4Route.wsf over route.exe if both tools provide the same parameters and level of functionality? Because WMIIP4Route.wsf is based on WMI, which in turn is based on COM and Distributed COM (DCOM), the script can leverage WMI's DCOM capabilities to let you remotely manage IP routes. WMIIP4Route.wsf supports /machine, /user, and /password switches that let you remotely access a system and add or delete an IP route. (The /user and /password switches are optional if you already have Administrator privileges on the remote system, but you must always be an Administrator or equivalent to locally or remotely manage the IP routing table.) Let's look at how you can use WMIIP4Route.wsf to view the information in the routing table, add a route to the table, and delete a route from the table.

Viewing the Routing Table

To display the information in the IPv4 routing table, run WMIIP4Route.wsf with the PRINT parameter. The routing table is a collection of instances from the Win32_IP4RouteTable class. Because some properties of this class contain numbers that have a specific meaning, the script includes the DecodeIPRouteFunction.vbs helper file at the beginning of the WSH code. This file contains several functions to decode property values exposed by the Win32_IP4RouteTable class.

After the script's initialization phase, the code at callout A in Listing 1 retrieves all available instances from the Win32_IP4RouteTable class. Next, the script enumerates, in a loop, all available instances. The code at callout B determines whether an association exists between each retrieved instance of the Win32_IP4RouteTable class and an instance of the Win32_IP4Persisted-RouteTable class. If such an association exists, the examined IP route instance is a persistent route (i.e., an entry that's permanently inserted into the routing table and that persists even after a reboot). The Win32_ActiveRoute association class links the Win32_IP4RouteTable and Win32_IP4PersistedRouteTable classes, and the script uses the Win32_ActiveRoute class to determine whether routes are persistent (as well as to create persistent routes, as I show you later in the article). The code at callout C then displays the properties of each IP route instance. Web Figure 2 shows the resulting output.

Adding a Route

To add a new route, run WMIIP4Route.wsf with the ADD, MASK, METRIC, and IF parameters. The ADD parameter specifies the new network IP number, the MASK parameter specifies the IP mask to use, the METRIC parameter specifies the destination's IP cost, and the IF parameter specifies the network interface number. Immediately after the MASK parameter value and before the METRIC parameter, you must specify the gateway IP address route to the new network IP number. For example, the command

WMIIP4Route.wsf ADD 192.10.10.0  MASK 255.255.255.0  192.10.10.1 METRIC 2 IF 1

adds a route to 192.10.10.0 (using the IP mask 255.255.255.0 and the gateway route 192.10.10.1) with a metric cost of 2 through network interface 1.

To make the route persistent, you must use the /persistent+ switch, which is equivalent to the route.exe
-p parameter:

WMIIP4Route.wsf ADD 192.10.10.0  MASK 255.255.255.0  192.10.10.1 METRIC 2 IF 1  /persistent+

To add a route remotely, add the /machine, /user, and /password switches:

WMIIP4Route.wsf ADD 192.10.10.0  MASK 255.255.255.0 192.10.10.1 METRIC 2 IF 1  /persistent+  /machine:MyRemoteSystem    .lissware.net  /user:Administrator  /password:Password1 

Listing 2 shows the code that WMIIP4Route.wsf uses to add an IP route. The Win32_IP4RouteTable class doesn't expose any method to add a route, so the code at callout A in Listing 2 spawns a Win32_IP4RouteTable instance--if an instance of the specified route doesn't already exist. To determine whether an instance exists, the script first tries to retrieve an existing instance of the IP route. If the route exists, the script updates the route with the new parameters. If the route doesn't exist, the script creates it. Note that the script doesn't expose a CHANGE parameter, as the route.exe command does. Rather, if the specified route already exists, the script's ADD command implements the same function as the CHANGE parameter.

Next, the code at callout B sets the route parameters. The code at callout C then uses the Put_ method of the SWbemObject object that represents the IP route instance to commit the route parameters.

If you specified the /persistent+ switch, the script next creates the WMI association to make the new route persistent. In such cases, the script creates two instances in addition to the Win32_IP4RouteTable instance. The first instance, which the code at callout D shows, is from the Win32_IP4PersistedRouteTable class. The creation of this instance follows a logic similar to the Win32_IP4RouteTable instance creation: The script first tries to retrieve the instance to determine whether it already exists, creates an instance if necessary, then sets the instance properties and saves the information in the Common Information Model (CIM) repository. The second instance, which the code at callout E shows, is from the Win32_ActiveRoute class. The script determines whether a Win32_ActiveRoute instance exists and, if not, creates the instance. To create or update the Win32_ActiveRoute instance, the script reuses the WMI path of the two previously created instances (i.e., the Win32_IP4RouteTable path instance and the Win32_IP4PersistedRouteTable path instance), then saves the information in the CIM repository.

Deleting a Route

To delete an existing route, run WMIIP4Route.wsf with the DELETE and MASK parameters, followed by the specified gateway route:

WMIIP4Route.wsf   DELETE 192.10.10.0  MASK 255.255.255.0  192.10.10.1

Listing 3 shows the code to delete a route from the routing table. This code also deletes the corresponding Win32_IP4RouteTable instance.

First, the code at callout A in Listing 3 retrieves the Win32_IP4RouteTable instance to be deleted. Before the script executes the deletion of the retrieved instance, the code at callout B determines whether an association exists between the instance and a Win32_IP4PersistedRouteTable instance. If the script finds an association, the code at callout C retrieves and deletes the associated Win32_IP4PersistedRouteTable instance. Deleting the associated instance is important because if the specified Win32_IP4RouteTable instance is recreated, the existence of a matching Win32_IP4PersistedRouteTable instance will automatically make the route persistent even if the /persistent+ switch isn't used during the recreation. After the script has retrieved all associated instances, the code at callout D deletes each instance. To delete a route remotely, add the /machine, /user, and /password switches, as you would when adding a route remotely.

On the Right Route

Computer security and management are hot topics, and the ability to monitor IP routes (for security reasons) and to manage routes remotely (as a great timesaver) are both important assets. If you deploy Windows 2003 or XP RAS or VPN servers, don't wait to leverage WMI's capability to improve your Windows management experience. Doing so can make life easier and give you another way to keep an eye on your network's security.