Enumerating Group Membership

In the Windows NT 4.0 world, group memberships were fairly simple to enumerate because only users or global groups could be members of local groups. Thus, the deepest possible nesting of permissions was having users in a global group and having that global group in a local group. This shallow nesting made it pretty simple to see which users had permissions to a particular resource.

Enter Windows 2000. In addition to letting you nest a global group in a local group, Win2K lets you nest local groups in other local groups. This ability makes identifying which users have permission to a resource much tougher. Although the Microsoft Management Console (MMC) Active Directory Users and Computers snap-in lets you drill down through the groups and visually see which users have permission, you can't see all this information in one display or output the results to a report.

Traditionally, the best command-shell utilities to use for enumerating group memberships have been the Local and Global utilities. Although these utilities do a great job of listing the members of local and global groups, respectively, they don't list the members of any groups that are nested in a local or global group. For quite some time, I had been struggling to write a script that enumerated the members of both first-level and nested groups. After some experimenting, I finally discovered that, by focusing on failures, I could use the Local and Global utilities to drill down through a group and enumerate the members of first-level and nested groups. After further experimenting, I was able to output this information to a comma-separated value (CSV) or tab-separated value (TSV) file for easy viewing in Microsoft Excel.

Script Counts on Command's Failures
By default, scriptwriters typically try to successfully execute commands and successfully capture those commands' output. Failure output is usually less important unless it affects a script's operation. However, in the EnumGroups.bat script, I depend on the Local and Global commands' failures to enumerate the members of first-level and nested groups.

Let's look at some sample failure output from the Local and Global commands. If you run the Local command against a known user account with a command such as

Local Fred domain1

you'll receive the failure message GetUsers - Unknown Error: 1376. If you run the Local command against a known global group with a command such as

Local AcctGG domain1

you'll receive the failure message GetUsers - Unknown Error: 1376. Notice that the failure messages are the same for both wrong inputs.

Now, let's run the Global command against a known user account with the command

Global Fred domain1

In this case, the failure message is 'Fred' group not found. If you run the Global command against a known local group with a command such as

Global SalesLG domain1

the failure message is 'SalesLG' group not found. Notice again that the failure messages are similar.

As an administrator, you can look at a named object and tell whether it's a user account or a group account because of your familiarity with your user and group naming conventions. However, in command-shell scripting, you don't have an easy way to determine whether an object is a user account, local group account, or global group account if your naming convention is domainnameusername and domainnamegroupname. So, you need to do some creative scripting.

You can determine what the named object is by initially assuming that every object you test is a local group. If you run the Local command against the item and that command succeeds, your assumption is correct and you have a local group. If the Local command fails and displays the error message GetUsers - Unknown Error: 1376, you know that you've eliminated the local group possibility, which means the object is either a global group or a user. At this point, you can run the Global command. If the Global command succeeds, you have a global group. If the command fails and displays an error message such as 'Fred' group not found, you know that the object is a user. Through this simple process of elimination, you can determine whether an object is a local group, global group, or user.

EnumGroups.bat uses this process of elimination to drill down through nested groups. For example, suppose the script uses the process of elimination and discovers that the first-level object is a local group. The script then uses the process of elimination to determine whether each object in that local group is a user or a nested group. If the script finds a nested group account at the second level, the script again uses the process of elimination to determine whether each object in the second-level group is a user or group. This process continues until either the specified maximum number of levels is reached or until the script runs out of objects to check. At this point, the script's flow returns to the point where it started the enumeration, and the script proceeds with the next object.

EnumGroups.bat is currently configured to retrieve groups and users down through eight levels. This number of levels will likely be sufficient for most environments. If you're unsure whether you need additional levels of enumeration, you can run the script as is. It will notify you when you've reached the eighth level and warn you that some groups might be listed but not enumerated.

Adding another level to the script is easy. You just copy the next-to-last module (level 7) and paste it in the location that the script specifies. I've added comments to the script to show exactly what code to copy and where to paste it. In the code you copy, you need to increment each numbered variable by one. For example, the %Group7% and %Dom7% variables need to become %Group8% and %Dom8%, respectively.

At the top of the script, you need to add several lines of code to the :CSVcode and :TSVcode sections. These sections specify the separators that the script uses to line up entries in the spreadsheet. For example, in the :CSVcode section, which Listing 1 shows, you'd add the line

Set Separator9=,,,,,,,,,

after the line that callout A in Listing 1 highlights. In the header line, you'd add ,Level 9 immediately after Level 8.

How to Launch the Script
You must launch EnumGroups.bat in a command-shell window. The script will ask you to specify three items. When you enter these items, don't enclose them in quotation marks, even if the item contains spaces. The three items are:

You can provide input to scripts in many ways. Commonly used approaches include using script arguments that you specify at runtime, manually editing variables in the script on each run, and using an input file. The lesser-known approaches include using the Choice command, which works well when users need to choose an option from a small static set of options, and using the Set /p command, which lets users enter any information they want.

For EnumGroups.bat, I used the Choice command to handle the input for the file types. The Choice command was ideal because this set of options consists of only three static items. The Choice command accepts only those options you specify; any other option will cause the script to stop. The script won't continue until the user enters a valid choice.

Although the Choice command is a good fit for capturing the file type, it wouldn't work for capturing the group name or domain name because many possible names exist and they can change frequently. The Set /p command works well for these two inputs. However, the Set /p command doesn't test whether the user's input is valid, so EnumGroups.bat contains some error-handling code to intercept bad input.

Sometimes you might need to change users' input to all uppercase or lowercase characters. I uppercased the domain group names that the Set /p command captures, so if a user enters sales for the domain name, the script changes that string to SALES. Having all uppercase letters isn't necessary to have EnumGroups.bat work properly, nor is it a formatting requirement for the script's output report. I just wanted to use this capability to demonstrate how you can change the case of strings because, although this procedure is obscure, it can be quite useful.

Listing 2 shows the code that uppercases the domain names. EnumGroups.bat uses the Setlocal Enabledelayedexpansion command, so this code expands the Dom variable while performing the character replacement. Typically, the character replacement syntax is

Set %Var:oldchar=newchar%

where oldchar is the character you want to replace and newchar is the replacement character. If you want to use variables to represent oldchar and newchar, the command would look like

Set%Var:%Oldchar%=%Newchar%%

However, this command would fail at runtime because of the nested percent signs. An alternative is to use exclamation points instead of percent signs as variable symbols so that the command would look like

Set !Var%Oldchar%=%Newchar%!

This command lets you accomplish the character replacement without any errors.

Customize the Script
I tested EnumGroups.bat on machines running Win2K Professional Service Pack 3 (SP3) and Windows XP and was able to query group members in both Win2K and NT 4.0 domains. To get the script working in your environment, follow these steps:

Now Give It a Try
After you have customized EnumGroups.bat, give the script an initial test. Enter the group name of a moderately complicated group that has several levels of nesting. If the script passes that test, try running it against your toughest group structures. Keep in mind that if you have a complicated structure, the script will take a while to run.