Earlier this week I was helping someone out on a problem working with the local administrators group. There are a variety of ways to enumerate the members of a local group. The code he was using involved WMI. I hadn't really worked with the WMI approach in any great detail so I thought I'd see how this might work in PowerShell. I ended up with a function to enumerate members of the local administrators group on a computer, as well as test if an account belongs to the group.<\/p>\n
The first function, Get-LocalAdministrators, will connect to a remote computer (it defaults to the local) and returns an object for each member like this:<\/p>\n
[cc lang=\"DOS\"]
\nName : LocalAdmins
\nFullname :
\nCaption : JDHLAB\\LocalAdmins
\nDescription :
\nDomain : JDHLAB
\nSID : S-1-5-21-3957442467-353870018-3926547339-1148
\nLocalAccount : False
\nDisabled :
\nComputer : CLIENT1
\n[\/cc]<\/p>\n
If I simply wanted a name, that would be pretty easy and I'd use a different approach. But I wanted richer information so that I could sort out what accounts were local, or disabled. I worked under the assumption that I would query a group of machines and save the data to a CSV file so I could later slice and dice the data. Or work with it further in PowerShell. Here's the function.<\/p>\n
[cc lang=\"PowerShell\"]
\nFunction Get-LocalAdministrators {<\/p>\n
[cmdletbinding()]<\/p>\n
Param(
\n[Parameter(Position=0,ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True)]
\n[ValidateNotNullorEmpty()]
\n[string[]]$Computername=$env:computername,
\n[switch]$AsJob)<\/p>\n
Begin {<\/p>\n
Set-StrictMode -Version latest
\n Write-Verbose \"Starting $($myinvocation.mycommand)\"<\/p>\n
#define an new array for computernames if this is run as a job
\n $computers=@()
\n}<\/p>\n
Process {
\n foreach ($computer in $computername) {
\n $computers+=$Computer
\n $sb={Param([string]$computer=$env:computername)
\n Try {
\n Write-Verbose \"Querying $computer\"
\n $AdminsGroup=Get-WmiObject -Class Win32_Group -computername $Computer -Filter \"SID='S-1-5-32-544' AND LocalAccount='True'\" -errorAction \"Stop\"
\n Write-Verbose \"Getting members from $($AdminsGroup.Caption)\" <\/p>\n
$AdminsGroup.GetRelated() | Where {$_.__CLASS -match \"Win32_UserAccount|Win32_Group\"} |
\n Select Name,Fullname,Caption,Description,Domain,SID,LocalAccount,Disabled,
\n @{Name=\"Computer\";Expression={$Computer.ToUpper()}}
\n }
\n Catch {
\n Write-Warning \"Failed to get administrators group from $computer\"
\n Write-Error $_
\n }
\n } #end scriptblock
\n if (!$AsJob) {
\n Invoke-Command -ScriptBlock $sb -ArgumentList $computer
\n }
\n } #foreach computer
\n} #process <\/p>\n
End {
\n #create a job is specified
\n if ($AsJob) {
\n Write-Verbose \"Creating remote job\"
\n #create a single job targeted against all the computers. This will execute on each
\n #computer remotely
\n Invoke-Command -ScriptBlock $sb -ComputerName $computers -asJob
\n }<\/p>\n
Write-Verbose \"Ending $($myinvocation.mycommand)\"
\n}
\n} #end function
\n[\/cc]<\/p>\n
The main part of the function uses WMI to query the Win32_Group class. Because the group may have been renamed, the filter searches for it by well-known SID.<\/p>\n
[cc lang=\"PowerShell\"]
\n$AdminsGroup=Get-WmiObject -Class Win32_Group -computername $Computer -Filter \"SID='S-1-5-32-544' AND LocalAccount='True'\" -errorAction \"Stop\"\"
\n[\/cc]<\/p>\n
Once the group is found, you could use an Associators Of query to find all the related objects, whcih would include the group members. But Associators Of queries are not easy to construct, assuming you even knew about them. Instead, in PowerShell the WMI object has a method called GetRelated(). This method in essence runs an Associators Of query for you. But obviously this is much easier.<\/p>\n
[cc lang=\"PowerShell\"]
\n$AdminsGroup.GetRelated() | Where {$_.__CLASS -match \"Win32_UserAccount|Win32_Group\"} |
\n Select Name,Fullname,Caption,Description,Domain,SID,LocalAccount,Disabled,
\n @{Name=\"Computer\";Expression={$Computer.ToUpper()}}
\n[\/cc]<\/p>\n
The method allows you to specify a resultant class as a parameter, but it doesn't speed up the process. It only filters the output. So I didn't bother and instead piped the results to Where-Object to get user and group accounts. I also select a few key properties to write to the pipeline. This query takes a little time to run and there isn't any way to speed it up. Although I have something to alleviate the pain.<\/p>\n
I decided this would be a good reason to use a background job. So I included a function parameter to run the entire command as a job. You'll notice that in the process block I'm creating a script block.<\/p>\n
[cc lang=\"PowerShell\"]
\nProcess {
\n foreach ($computer in $computername) {
\n $computers+=$Computer
\n $sb={Param([string]$computer=$env:computername)
\n Try {
\n[\/cc]<\/p>\n
The script block takes a computername as a parameter. If I'm running the command normally (ie no job), then the script block executes for each computer passed as a parameter or piped in.<\/p>\n
[cc lang=\"PowerShell\"]
\nif (!$AsJob) {
\n Invoke-Command -ScriptBlock $sb -ArgumentList $computer
\n }
\n[\/cc]<\/p>\n
The command runs locally and queries the remote computer. But if I decide to run this as a job, I wait until the End scriptblock since I wanted to create one job. In order for this to work, I need to keep track of all the pipelined computer names so I keep adding them to $computers in the Process script block. After I've built the list, I again use Invoke-Command, but this time I also specify that the command runs ON the remote machines.<\/p>\n
[cc lang=\"PowerShell\"]
\nif ($AsJob) {
\n Write-Verbose \"Creating remote job\"
\n #create a single job targeted against all the computers. This will execute on each
\n #computer remotely
\n Invoke-Command -ScriptBlock $sb -ComputerName $computers -asJob
\n }
\n[\/cc]<\/p>\n
The end result is a job created locally with child jobs that run on all the computers specified. This allows me to keep working in PowerShell, and get the results when I want. Because the command is executing simultaneously it runs a little faster overall. I realize the WMI queries aren't the speediest, but I end up with valuable information.<\/p>\n
The other function is a simple test: does this account belong to the administrators group?<\/p>\n
[cc lang=\"PowerShell\"]
\nFunction Test-IsLocalAdministrator {<\/p>\n
[cmdletbinding()]<\/p>\n
Param(
\n[Parameter(Position=0,HelpMessage=\"Enter a user or group name in the domain\\username format\")]
\n[ValidatePattern(\"\\w+\\\\\\w+\")]
\n[string]$Name=\"$env:userdomain\\$env:username\",
\n[Parameter(Position=1)]
\n[ValidateNotNullorEmpty()]
\n[string]$Computername=$env:computername
\n)<\/p>\n
Set-StrictMode -Version latest<\/p>\n
Write-Verbose \"Starting $($myinvocation.mycommand)\"
\n#Split Name into domain and name parts
\n$Domain=$Name.Split(\"\\\")[0]
\n$Member=$Name.Split(\"\\\")[1]<\/p>\n
Try {
\n Write-Verbose \"Querying $computername\"<\/p>\n
$AdminsGroup=Get-WmiObject -Class Win32_Group -computername $Computername -Filter \"SID='S-1-5-32-544' AND LocalAccount='True'\" -errorAction \"Stop\"
\n Write-Verbose \"Getting members from $($AdminsGroup.Caption)\"
\n Write-Verbose \"Testing $($name.ToUpper())\"
\n $Found=$AdminsGroup.GetRelationships(\"Win32_GroupUser\") | Where {$_.PartComponent -match \"Domain=\"\"$Domain\"\",Name=\"\"$Member\"\"\"}<\/p>\n
If ($found) {
\n Write $True
\n }
\n else {
\n Write $False
\n }
\n}
\nCatch {
\n Write-Warning \"Failed to get administrators group from $computername\"
\n Write-Error $_
\n }<\/p>\n
Finally {
\n Write-Verbose \"Ending $($myinvocation.mycommand)\"
\n}<\/p>\n
} #end function
\n[\/cc]<\/p>\n
Here I took a slightly different approach. I still get the admins group with the same WMI query. But this time I use the GetRelationships() method which is a .NET equivalent of a References WMI query.<\/p>\n
[cc lang=\"PowerShell\"]
\n $Found=$AdminsGroup.GetRelationships(\"Win32_GroupUser\") | Where {$_.PartComponent -match \"Domain=\"\"$Domain\"\",Name=\"\"$Member\"\"\"}
\n[\/cc]<\/p>\n
This type of query is quick, at least for groups and returns WMI paths of related objects. All I have to do is parse the PartComponent property and use a regular expression match to see if the domain and account name match. You have to specify the name in domain\\name format. If $found exists, the function writes $True. I think Test functions should be simple, quick and concise.<\/p>\n
These functions have limited error handling and don't support alternate credentials, although you could certainly add that. I'll be the first to admit that these may not be the best ways to achieve these results, but they are viable options and I am happy with the way I incorporated support for background jobs in the function.<\/p>\n