IN THIS CHAPTER
Windows permissions can be complex and simple depending on what is needed because, at its core, the security model around Windows permissions was created to be as flexible as possible. For example, you can set permissions for files, directories, registry keys, processes and threads, services, printers, network shares, directory objects, named and anonymous pipes, and kernel objects. However, when combined with its flexibility and core concepts such as ACLs, ACEs, DACLs, SACLs, SIDs, and inheritance, trying to manage Windows permissions using scripting can be a daunting challenge.
In this chapter, the primary goal is to gain a better understanding around how PowerShell handles the management of Windows permissions. To reach that goal, you first review how permissions were managed using Windows Script Host (WSH). Next, you review how PowerShell is used to manage Windows permissions and the slight improvement it provides over past scripting methods. Finally, while reviewing both the WSH and PowerShell methods, you are introduced to set of custom script functions that can be used to manage permissions. These functions serve as examples to show how difficult automating permission changes can be while giving you insight as to how to tackle Windows permission management.
Working with permissions in WSH has limitations. For example, there’s no straightforward method for changing permissions on an object. Instead, scripters must choose between using an external utility, such as cacls, xcacls, dsacls.exe, xcalcs.vbs, SubInACL, or using automation interfaces such ADsSecurity.dll or the WMI Win32_LogicalFileSecuritySetting class. In either case, none of the listed methods offers a complete or standard solution for working with permissions.
Given these limitations, the SubInACL utility is one of the many tools that is often used for managing permissions on an object or group of objects. This tool isn’t perfect, but if you script around its shortcomings, it’s usually more than satisfactory for making permission changes when compared to what is available via WSH. In addition, SubInACL supports files, directories, file shares, printer shares, the registry, system services, and the Internet Information Services (IIS) metabase.
NOTE
You can download SubInACL from
www.microsoft.com/downloads/details.aspx?FamilyId=E8BA3E56-D8FE-4A91-93CFED6985E3927B&displaylang=en.
The syntax for SubInACL consists of [/Option ] /object_type object_name [[/ Action [= Parameter ]..]. This syntax seems simple enough, however, SubInACL is a complex permission Swiss army knife that can handle a variety of situations. But, in most cases, you will use SubInACL to only complete the following permission changes:
• Take ownership
• Dump permissions
• Add permissions
• Remove permissions
This list isn’t exhaustive, but it does give you a foundation for developing functions that can be frequently reused. Developing reusable functions is a recommended best practice. They can be used in many scripts and reduce the time needed to develop a script. For permission changes, developing reusable functions makes even more sense because working with the supported interfaces in WSH or existing tools can be time consuming. To better illustrate this practice, the next section contains several SubInACL functions that have been created to manage folder and file permissions.
In this section, four SubInACL functions are discussed: SetOwner, DumpPerm, AddPerm, and RemovePerm. Each function takes arguments and builds a command string for the SubInACL utility. Then, using a WshShell object, the SubInACL utility is executed using the constructed command string. Next, output in the log.temp file from SubInACL is read for errors by using the ParseTempFile function. Based on the error information derived from log.temp, a success or failure status is then written to the console.
This function is used to set the owner for a folder and its subfolders. To use this function, provide the path for the folder you want to define ownership for and the name of the account or group that is to be the owner. The source code for this function is as follows:
This function is used to clear permission from a folder and its subfolders. To use this function, provide the path for the folder you want to clear permissions from. The source code for this function is as follows:
This function is used to grant a user or group permission to a folder and its subfolders. To use this function, provide the path for the folder you want to add rights to, the name of the account or group to grant rights to, and the type of access being granted. The source code for this function is as follows:
This function is used to remove rights from a user or group to a folder and its subfolders. To use this function, provide the path for the folder you want to add rights to, the name of the account or group to grant rights to, and the type of access being revoked. The source code for this function is as follows:
One of the greater hopes for PowerShell was that it would have soothed the rough edges associated with attempting to manage Windows permissions (via the command line or through a script). After all, as shown and explained in this chapter’s previous sections, the lack of interfaces in WSH and the required use of external utilities left a lot to be desired. In fact, one might say that the lack of a standardized management interface within the realm of “Windows Scripting” is frustrating.
In reality, however, working with Windows permissions is a difficult task even when you are full-fledge developer. So, unless there is an interface that acts as an adapter and provides you with a simple set of methods for reading and modifying permissions, your ability as scripter to manage permissions will also be severely handicapped. Unfortunately, although the PowerShell team attempted to improve things, PowerShell’s “permissions adapter” has positives and negatives.
Because PowerShell is based on the .NET Framework, it is resigned to using a set of core classes for both representing and working with Windows permissions. Although the classes themselves are powerful and can provide a “developer” with the needed tools to correctly manage or report on permissions, directly working with these classes can be a challenging endeavor, even for a developer.
To remove some of the challenges associated with these classes, the PowerShell team included two cmdlets named Get-ACL and Set-ACL. As you might expect, Get-ACL cmdlet is used to retrieve the security descriptor for a resource, such as a file or registry key, while the Set-ACL cmdlet is used to modify the security descriptor of a resource.
Thanks to the Get-ACL and Set-ACL cmdlets, you might think managing Windows permissions is easier in PowerShell. However, the Set-ACL cmdlet still requires a security descriptor object defined by the System.Security.AccessControl.ObjectSecurity class. Constructing a security descriptor isn’t difficult, but managing permissions isn’t as straightforward to script as you might have hoped. When faced with terms such as security descriptors and access control rules (ACL), you might be tempted to stick with more familiar tools, such as SubInACL. If you sit down and go through the process step by step, however, it’s not as complex as it seems at first glance. It consists of these basic steps:
1. Get the security descriptor (ACL) for an object by using Get-ACL.
2. Build the ACL with access control entries (ACE).
3. Add the ACL to the security descriptor.
4. Bind the new security descriptor to the object by using Set-ACL.
The following code is an example of using these steps:
The hardest step to understand in this example is building the access rule. An access rule consists of three parameters to define user or group, access right, and access control type. The first parameter, Identity, is easy to define because you know the user or group to be added to an access rule. The second parameter, FileSystemRights, is more difficult because it requires understanding file system rights to define the access. However, you can use the following command to produce a list of supported rights:
From this list, you can define a single right, such as Modify, or string rights together into a list, such as Read, Write, and Delete. The third parameter, AccessControlType, is easy to define because it can be only Allow or Deny.
As with the SubInACL utility, a set of reusable permission management functions can be developed for use in your scripts. Examples of such functions follow.
The Clear-Inherit function is used to clear inherited permissions from a folder. However, Clear-Inherit is probably the wrong name for this function because in addition to preventing inherited permissions from being applied from the parent object and clearing inherited permissions from the root object and sub-objects, it clears explicitly defined permissions on sub-objects. Therefore, before using the Clear-Inherit function, it’s a good practice to take ownership of the object or make sure you have explicitly defined rights for yourself on the root file system object. If you don’t ensure that you have access to file system objects, you might see “access denied” messages after clearing inherited rights. The source code for this function is as follows:
The Clear-SD function is used to clear the security descriptor for a file system object. Although the Clear-SD function is used in the file system management script later in this chapter, it’s a good illustration of how you can set a security descriptor with Security Descriptor Definition Language (SDDL). SDDL is used to describe a security descriptor as a text string. If the Clear-SD function is used, an object’s security descriptor is cleared and then set to FullControl for the Everyone group by using the string "D:PAI(A;OICI;FA;;;WD)".
NOTE
For more information on constructing a security descriptor with the Security Descriptor String Format, refer to http://msdn.microsoft.com/library/default.asp?url=/library/en-us/secauthz/security/security_descriptor_string_format.asp.
The following code box contains the source for the Clear-SD function:
Add-ACE is used to grant rights to a file system object for a user or group. This function, although similar to the example at the beginning of this section, also shows how to control inheritance settings for a new access control entry (ACE) with System.Security.AccessControl.PropagationFlags and System.Security.AccessControl.InheritanceFlags enumerations.
Don’t let the name of these flags confuse you, as they control how an ACE is applied to an object and all objects under that object. In the Add-ACE function, the flags are set so that an ACE is applied to file system objects as “This folder, subfolders, and files.” This means that the ACE will be applied to the object being modified and propagated to all objects under that object. Propagating the ACE as defined in the Add-ACE function should be sufficient for most file system management tasks. If not, you can modify the function so that it accepts inheritance settings as an argument.
After reading this chapter, you should understand how difficult Windows permissions automation can be. Although the security model is powerful, there isn’t a good interface or method to easily manage permissions on objects. As you have seen, WSH provided no built-in interface and solely relied on external utilities or assemblies. PowerShell, on the other hand, provided a set of cmdlets. Even with this minor improvement, managing permissions still tends to be an intimidating task.
As shown in this chapter, if you take the time to figure out a set of reusable script functions, you can attempt to make up for the shortcomings for both WSH and PowerShell.