Rem: Reading Files’ and Folders’ Security Settings

Do you have a scripting-related question or problem? You can send your question or problem to [email protected].

I want to use Windows Management Instrumentation (WMI) to read the security settings on files and folders. I've seen numerous examples of such scripts, but they all fall short of displaying the permissions in a readable format. How can I use WMI to obtain and display individual permission settings?

You use the WMI Security Provider to dissect a file's or folder's security settings. Specifically, you use four classes defined in the WMI rootcimv2 namespace:

The process of unraveling an SD involves the following steps:

The script WMISecurity.vbs performs these four steps to read and display the security settings that have been applied to the C:windows folder on a computer named dell610. Listing 1 and Listing 2, page 6, show excerpts from this script. You can find the complete script in the Code Library on the Windows Scripting Solutions Web site (http://www.winscriptingsolutions.com). Although WMISecurity.vbs is long, the exercise of reading an SD is more tedious than difficult.

The first 82 lines in the script set up the script's variables. The four variables that warrant explanation are CONTROL_FLAGS, ACCESS_MASK, ACE_FLAGS, and ACE_TYPE. These Dictionary objects determine which bits are set in the SD's ControlFlags property and in each ACE's AccessMask, AceFlags, and AceType properties, respectively. As the excerpt in Listing 1 shows, the script defines these dictionary objects.

The Win32_SecurityDescriptor class's ControlFlags property and the Win32_ACE class's AccessMask, AceFlags, and AceType properties represent the gory details of an SD. All four properties are integer values, and each bit in each integer represents a unique setting. This type of integer is commonly called a bit field or bit flag. Because each bit represents a different setting, simply displaying the integer values of the four properties is of little use. You must examine each bit in each property to understand the SD's details. Dictionary objects provide an efficient structure to do so, as you'll soon see.

After the first 82 lines, WMISecurity.vbs starts to implement the four steps. Here's a detailed look at those steps:

Steps 1 and 2. To connect to the WMI Service on the target computer, the script uses a standard WMI connection string (i.e., a moniker). Immediately following the connection, the script fetches the target folder's security settings by using the Get method of the SWbemServices object (which the wmiServices variable represents). This method retrieves an instance of the class you specify as Get's first parameter. In this case, Get retrieves an instance of the Win32_LogicalFileSecuritySetting class, which represents the security settings for the target folder. Using the reference (i.e., wmiSecuritySettings) to the folder's Win32_LogicalFileSecuritySetting instance, the script displays the values of the six Win32_LogicalFileSecuritySetting class properties.

Note that ControlFlags is one of the six properties. ControlFlags provides important information about the SD, such as the SD's inheritance flags and whether it contains a DACL and SACL. At this point, the script could examine the bits in ControlFlags. However, the Win32_SecurityDescriptor provides an identical ControlFlags property that the script will later examine.

Step 3. The script calls the Win32_LogicalFileSecuritySetting class's GetSecurityDescriptor method, as the code at callout A in Listing 2 shows. GetSecurityDescriptor accepts one parameter: the variable to which you want to assign the folder's SD. This type of parameter passing is commonly called pass by reference. In this case, I've passed the wmiSecurityDescriptor variable to the GetSecurityDescriptor method. The method initializes this variable with an instance of Win32_SecurityDescriptor. The Win32_SecurityDescriptor instance provides five properties:

Because the SD's owner is an instance of the Win32_Trustee class, the script sets a reference (i.e., the wmiOwner variable) to that class's Owner property. The script then displays the SD owner's name, SID, and domain.

Step 4. The last step is to examine the five bit fields. As the code at callout B in Listing 2 shows, the script begins by examining the first bit field—the Win32_SecurityDescriptor's ControlFlags property. Recall that each bit in ControlFlags represents a unique setting. To examine each bit, the script uses the CONTROL_FLAGS Dictionary object.

A Dictionary object is simply a list of items. Each item consists of two parts: a key and a value. Table 1 lists the key-value pairs in the CONTROL_FLAGS Dictionary object. You use the Dictionary object's key to retrieve a specific value from the Dictionary object, much as you use a numeric index to retrieve an element in an array. However, unlike an array in which the index is a fixed number, the Dictionary object's keys can be numbers or strings. This feature makes Dictionary objects particularly well suited for reading files' and folders' security settings because you can store friendly names in addition to the values used to perform the bitwise comparisons. You use the friendly name to reference the bit value (i.e., position) you want to compare with the target bit field property and, if the bitwise comparison is true, display the friendly name. Let's look at this capability in action.

The code at callout B begins by setting the blnFirstValue variable to True. The script uses this value to help format output inside the For Each...Next statement. The For Each...Next loop uses the Dictionary object's Keys method to loop through all the keys in CONTROL_FLAGS. During each loop iteration, an If...Then...Else statement performs a bitwise comparison between the current CONTROL_FLAGS key's value and the ControlFlags property's value. If both identically positioned bits are set (i.e., have a value of 1), the If...Then...Else statement evaluates to True and the script displays the key's friendly name.

Next, the script uses ControlFlags a second time to test the SE_DACL_PRESENT bit, as the code at callout C in Listing 2 shows. If the SE_DACL_PRESENT bit is set, the SD contains a DACL, in which case the body of the If...Then...Else statement executes. The script initializes an array variable named arrDacl with the array of Win32_ACE objects that make up the folder's DACL. A For Each...Next statement iterates through the array. For each Win32_ACE in the arrDacl array, the following actions take place:

After the script examines and displays all the Win32_ACE objects in the folder's DACL, the script moves on to the SACL (not shown in Listing 2). The script performs the same actions on the SACL as it did on the DACL.