PowerShell Audit Reports – Turning Great Scripts Into a Module

I just read a neat blog post entitled PowerShelling Audit Reports over on the TenBrink Tech blog. This blog post sets out three scripts: GetRecursiveGroupMembership.ps1, Audit-QuickGroup.ps1, and Audit-MultipleGroups.ps1. The second and third make use of the first. They make use of Quests’s AD tools to create CSV file(s) containing details of members in an AD Group.

Scripts to Modules

Dillon (the post’s author) has implemented all three of these as separate PS1 files. Which is so Version 1. :-)!!  As I read through his scripts, I could not escape the felling that a much better approach would be to implement them as a single module with PowerShell V2. So I did! It took a bit more time than I’d hoped, but it helped me to learn a bit more about modules in PowerShell V2.

Creating a Module

I first created a module file (audit.psm1) which contained the three functions Dillon created. These were slightly modified to be functions rather than script files, but the resulting module is essentially identical to the original. I also created a module manifest, which describes the module, and indicates the functions the module should expose to the user once the module is imported. I felt the first function was a helper function so the module only exports two functions not all three.Of course, I could be wrong, but it did make an interesting challenge – just exporting two of the three functions using a manifest.

Here’s the PSM1 Module itself:

1. # 
2. Write-Host "Importing Module Audit.psm1" 
3. function Get-RecursiveGroupMembership { 
4. <# 
5. .SYNOPSIS 
6.     Gets membership of a group.   
7. .DESCRIPTION 
8.     Uses recursion to handle nested groups 
9. .NOTES 
10.     File Name  : Audit.psm1 
11.     Author     : Dillon (@tealshark on Twitter) 
12.     Updated by : Thomas Lee tfl@psp.co.uk 
13.     Requires   : PowerShell V2 CTP3 
14.     This is a helper function and not exported by the module. 
15. .LINK 
16.     http://www.pshscripts.blogspot.com 
17.     http://tenbrink.us/index.php/2009/01/03/powershelling-audit-reports/ 
18. .PARAMETER DistinguishedName 
19.     This paramater is the DN of the group you want to expand 
20. .PARAMETER AddOtherTypes 
21.     This parameter adds other types to the search 
22. #> 
23.  
24. param ( 
25. [Parameter(Position=0, Mandatory=$TRUE, ValueFromPipeline=$TRUE)]   
26. [string] $distinguishedname, 
27. [Parameter(Position=1, Mandatory=$FALSE, ValueFromPipeline=$FALSE)]     
28. [bool] $addOtherTypes = $false 
29. ) 
30.  
31. # Start of function 
32.  $members = @() 
33.  
34.  $this = (Get-QADGroup $distinguishedname).member | Get-QADObject 
35.  $this | foreach { 
36.       if ($_.type -eq ‘user’) { 
37.           $members += $_ 
38.       } 
39.       elseif ($_.type -eq ‘group’) { 
40.           Write-Host "Adding sub group $_" 
41.           $members += Get-RecursiveGroupMembership $_.dn $addOtherTypes 
42.       } 
43.       else { 
44.           if ($addOtherTypes -eq $true) { 
45.               $members += $_ 
46.            } 
47.            else { 
48.               Write-Host "Non user/group member detected. Not added. Use -addOtherTypes flag to add." 
49.            } 
50.        } 
51.     } 
52.     return $members 
53. } 
54.  
55. function Audit-QuickGroup { 
56. <# 
57. .SYNOPSIS 
58.     This function takes the distinguishedName of a group in any domain and writes 
59.     the results of that group membership to a csv file of the same name. 
60. .DESCRIPTION 
61.     This script uses get-recursivegroupmembership function to get the group membership 
62. .NOTES 
63.     File Name  : audit.psm1 
64.     Author     : Dillon (@tealshark on Twitter) 
65.     Updated by : Thomas Lee tfl@psp.co.uk 
66.     Requires   : PowerShell V2 CTP3 
67.     This function is exported 
68. .LINK 
69.     http://www.pshscripts.blogspot.com 
70.     http://tenbrink.us/index.php/2009/01/03/powershelling-audit-reports/ 
71. .EXAMPLE 
72. .PARAMETER Name 
73.     Disginguished name of a group whose membership the script will ascertain. 
74. #> 
75.  
76. param ( 
77. [Parameter(Position=0, Mandatory=$TRUE, ValueFromPipeline=$TRUE)]   
78. [string] $Name 
79. ) 
80.  
81. # Start of Function 
82. $Csvdata = Get-RecursiveGroupMembership $name | select name,type,dn,title,office,description | convertto-csv -NoTypeInformation 
83. $Filename = $Name + ".csv" 
84. [String]$Reportdate = "Report Generated: " + [datetime]::Now 
85. $f = new-item -itemtype file $filename 
86. add-content $f "Audit Report - Active Directory Group - $name" 
87. add-content $f $reportdate 
88. add-content $f $csvdata 
89. } 
90.  
91.  
92. function Audit-MultipleGroups { 
93. <# 
94. .SYNOPSIS 
95.     Gets membership of multiple groups 
96. .DESCRIPTION 
97.     This function uses the filtering abilities of the Quest Get-QADGroup cmdlet to  
98.     get the membership of multiple groups. These are then written to multiple files. 
99. .NOTES 
100.     File Name  : get-autohelp.ps1 
101.     Author     : Dillon (@tealshark on Twitter),  
102.     Updated by : Thomas Lee tfl@psp.co.uk 
103.     Requires   : PowerShell V2 CTP3 
104.     This function is exported 
105. .LINK 
106.     http://www.pshscripts.blogspot.com 
107. .EXAMPLE 
108.     Left as an exercise for the reader 
109. .PARAMETER GroupInput 
110.     The groups you want to audit. 
111. #> 
112.  
113. param ( 
114. [Parameter(Position=0, Mandatory=$TRUE, ValueFromPipeline=$TRUE)]   
115. [string] $GroupInput 
116. ) 
117.  
118. # Start of function 
119. # First get groups 
120. $GroupList = get-qadgroup $groupinput 
121.  
122. # Iterate through groups, creating output 
123.  foreach ($Group in $GroupList) { 
124.      Write-Host $group.dn 
125.     $GroupMembers = Get-RecursiveGroupMembership $group.DN | select name,type,dn,title,office,description | convertto-csv -NoTypeInformation 
126.     #now create file 
127.     $filename = $Group.Name + ".csv" 
128.     [String]$reportdate = "Report Generated: " + [datetime]::Now 
129.     $file = New-Item -ItemType file $filename -Force 
130.     Add-Content $file "Audit Report - Active Directory Group Membership" 
131.     Add-Content $file $reportDate 
132.     Add-Content $file $groupMembers 
133.   } 
134. } 
135.  
136. # End of Module 

Creating the Manifest

I used the New-ModuleManifest cmdlet to produce the basic module manifest, the .psd1 file. I then did a bit of editing with PowerSHell plus to achieve this final manifest:

1. # Module manifest for module 'audit' 
2. # Generated by: Thomas Lee 
3.  
4. @{ 
5. # These modules will be processed when the module manifest is loaded. 
6. NestedModules = 'Audit.psm1' 
7. # This GUID is used to uniquely identify this module. 
8. GUID = '5eed72f9-5f1d-4819-973c-63f80ccee415' 
9. # The author of this module. 
10. Author = 'Thomas Lee (tfl@psp.co.uk), with functions by dillon.' 
11. # The company or vendor for this module. 
12. CompanyName = 'PS Partnership' 
13. # The copyright statement for this module. 
14. Copyright = '(c) PS Partnership 2009' 
15. # The version of this module. 
16. ModuleVersion = '1.0' 
17. # A description of this module. 
18. Description = 'This module is a packaging of audit scripts by Dillon into a single module.' 
19. # The minimum version of PowerShell needed to use this module. 
20. PowerShellVersion = '2.0' 
21. # The CLR version required to use this module. 
22. CLRVersion = '2.0' 
23. # Functions to export from this manifest. 
24. ExportedFunctions = ('Audit-QuickGroup', 'Audit-MultipleGroups') 
25. # Aliases to export from this manifest. 
26. ExportedAliases = '*' 
27. # Variables to export from this manifest. 
28. ExportedVariables = '*' 
29. # Cmdlets to export from this manifest. 
30. ExportedCmdlets = '*' 
31. # This is a list of other modules that must be loaded before this module. 
32. RequiredModules = @() 
33. # The script files (.ps1) that are loaded before this module. 
34. ScriptsToProcess = @() 
35. # The type files (.ps1xml) loaded by this module. 
36. TypesToProcess = @() 
37. # The format files (.ps1xml) loaded by this module. 
38. FormatsToProcess = @() 
39. # A list of assemblies that must be loaded before this module can work. 
40. RequiredAssemblies = @() 
41. # Lists additional items like icons, etc. that the module will use. 
42. OtherItems = @() 
43. # Module specific private data can be passed via this member. 
44. PrivateData = '' 
45. } 

The Results

It turns out that converting a set of script files, like Dillon created initially, into a module (as above) is easy. The syntax of the module file turns out to be a bit tricky, and the error messages and help text in CTP3 are woefully inadequate.

Here’s what this module looks like at runtime:

PS MyMod:\> # Note the module is not yet loaded so you get no output from Get-module

PS MyMod:\> Get-Module audit
PS MyMod:\> # So import the module, then look at module details
PS MyMod:\> Import-Module audit
Importing Module Audit.psm1
PS MyMod:\> Get-Module audit

Name              : audit
Path              : C:\Users\tfl\Documents\WindowsPowerShell\Modules\audit\audit.psd1
Description       : This module is a packaging of audit scripts by Dillon into a single module.
Guid              : 5eed72f9-5f1d-4819-973c-63f80ccee415
Version           : 1.0
ModuleBase        : C:\Users\tfl\Documents\WindowsPowerShell\Modules\audit
ModuleType        : Manifest
PrivateData       :
AccessMode        : ReadWrite
ExportedAliases   : {}
ExportedCmdlets   : {}
ExportedFunctions : {[Audit-QuickGroup, Audit-QuickGroup], [Audit-MultipleGroups, Audit-MultipleGroups]}
ExportedVariables : {}
NestedModules     : {Audit.psm1}

PS MyMod:\> # Here – use AutoHelp feature to get help on the exported function/
PS MyMod:\> Get-Help Audit-QuickGroup

NAME
    Audit-QuickGroup

SYNOPSIS
    This function takes the distinguishedName of a group in any domain and writes
    the results of that group membership to a csv file of the same name.

SYNTAX
    Audit-QuickGroup [-Name] [<String>] [-Verbose] [-Debug] [-ErrorAction [<ActionPreference>]] [-WarningAction [<ActionPreference>]] [-ErrorVariable [<String>]] [-WarningVariable [<String>
    ]] [-OutVariable [<String>]] [-OutBuffer [<Int32>]] [<CommonParameters>]

DETAILED DESCRIPTION
    This script uses get-recursivegroupmembership function to get the group membership

RELATED LINKS
http://www.pshscripts.blogspot.com
http://tenbrink.us/index.php/2009/01/03/powershelling-audit-reports/

REMARKS
    To see the examples, type: "get-help Audit-QuickGroup -examples".
    For more information, type: "get-help Audit-QuickGroup -detailed".
    For technical information, type: "get-help Audit-QuickGroup -full".

What I learned

This was an interesting exercise. It was pretty easy, but I did stumble a bit with the module (how I wish there has been better documentation on modules with CTP3!). Here are some of my take-aways relating to PowerShell modules in CTP3:

1. Turning a set of inter-related scripts into a module is both easy, and a good thing!
2. If you have a module that you want to also have a manifest with, they can both have the same file name but with different extensions (the module itself in a .psm1 file and the manifest in a pds1 file).
3. To export only a subset of the functions in the .psm1 file, you use the ExportedFunctions feature in the manifest.
4. To export multiple functions you enclose the set of functions as a string array inside the parenthesis. See this in line 24 above. This format was not all that obvious at first.
5. You can add statements into the module that are executed when you import the module. See Line 2 in the module – this prints out a short message when you import the module. This has some great potential – thanks to Jeffrey Snover for the tip!
6. If you import a module (using import-module as above) you can generally remove it using remove-module. This aids in testing!

There’s certainly room for improvement in this module. One thing that could be done would be to check to see if the Quest QAD tools were installed and issue a warning message if not (even better, if the tools are not found the script could go get them and install them for you auto-magically!). There should also be some trap or try/catch statements in the functions to better handle errors. Some auditing of the functions usage could also be implemented.

Modules are pretty cool – I hope this helps you understand them a bit better!

Technorati Tags: module,manifest,PowerShell V2,CTP3,Quest QAD Tools,Quest