PowerShell - Monitor and Report Active Directory Group Membership Change

2013/10/13 | 7 minute read |

UPDATE 2016/05/03:The most recent update is availableon Github See also the related blogpost:https://lazywinadmin.github.io/2013/11/update-powershell-monitor-and-report.html

Today I will update a post that I published at the beginning of last year : Monitor Active Directory Membership changes.I updated the script to add some of the things I learned during the Scripting Games 2013 back in April/May. The script will also create a nice html report and send it via Email.

Basically, the script will monitor the Active Directory groups that you specify and notify you if a change occurred since the last time it checked.

##

###

Overview

  • How does the script works ?

  • Main Process

  • Comparing

  • Change History

  • Reporting

  • What does this script does not cover ?

  • Workflow

  • Requirements

  • PowerShell 3.0

  • Quest Active Directory Snapin

  • A Schedule task (Automate it!)

  • Permissions

  • Running the Script the first time

  • Running the Script after the first change

  • Running the Script after the second change

  • Comments Based Help

  • Download

How does the script works ?

Main Process This script checks an Active Directory Group membership that you specify and notify you if a change occurred since the last time it checked. In order to find the right group to monitor, you can specify the group Name, SID(Security Identifier), GUID(Globally Unique IDentifier) or DN(Distinguished Name). Group name like 'DOMAIN\GROUPNAME' will also work. Comparing The membership of each group is saved in a CSV file "DOMAIN_GROUPNAME-membership.csv" If the file does not exist, the script will create one, so the next time it will be able to compare the membership with this file. Change History Each time a change is detected (Add or Remove an Account (Nested or Not)) a CSV file will be generated with the following name: "DOMAIN_GROUPNAME-ChangesHistory-yyyyMMdd-hhmmss.csv" When generating the HTML Report, the script will add this Change History to the Email (if there is one to add)

Reporting Here is an example of report generated when a change is detected. You can see the user 'catfx' was removed from the group FX\FXGROUP Also, If the script find some Change History files for this group, it will be added to the report. Finally at the end of the report, information on when, where and who ran the script.
Example of Email Report generated by the script

###

What does this script does not cover ? This script won't: * Use the Active Directory module (Next update) * Tell you who changed the Group Membership in Active Directory (You would need to active Auditing in Active Directory) * Create the Schedule Task for you * Generate a HTML file (Next update) ### Workflow The script is a bit complex to understand, so I created a small workflow that explain how each parts interact with each other: ### Requirements

PowerShell v3.0 You will need PowerShell version 3.0 to take advantage [mailaddress]</b> which make a validation on the Source and Destination Email addresses.

Quest Active Directory PowerShell Snappin I used the Quest Active Directory Snapin to do my queries, get it here In the next update I plan to add support for the Active Directory module (maybe ADSI too).

A Scheduled task (Automate it!!) You will need to configure a Scheduled task that will run your task for you every minute * Make sure the account that will run the task is an Administrator OR is member of the Local Security Policy "Log on as a batch job". * Create your task and make sure it runs every minutes! * I recommend to assign a dedicated AD account to this task
Local Security Policy console

Permissions This PowerShell script will need some rights, it will: * Create CSV files inside of the script parent directory * Make sure the account you use for this jobhas the rights to write files inside the parent directory of this script (this does not apply if the account is part of the Local Administrators group) * Access the Active Directory (read) * Make sure the account you use has the rights to read the membership of the group(s) you want to monitor. ### ### Running the Script the first time</u> In this example I run the script against 2 Active Directory Groups with the verbose parameter so it will let me know what it's doing. ``` .\TOOL-MONITOR-AD_Groups.ps1 -verbose -Group "FXGROUP", "FXGROUP2" -EmailServer "mail.fx.local" -EmailTo "[email protected]" -EmailFrom "[email protected]" ``` ``` VERBOSE: Creating the Output Folder : C:\LazyWinAdmin\Output VERBOSE: Creating the ChangeHistory Folder : C:\LazyWinAdmin\ChangeHistory VERBOSE: GROUP: FXGROUP VERBOSE: FXGROUP - The following file did not exist: FX_FXGROUP-membership.csv VERBOSE: FXGROUP - Exporting the current membership information into the file: FX_FXGROUP-membership.csv VERBOSE: FXGROUP - Comparing Current and Before VERBOSE: FXGROUP - Compare Block Done ! VERBOSE: FXGROUP - No Change VERBOSE: GROUP: FXGROUP2 VERBOSE: FXGROUP2 - The following file did not exist: FX_FXGROUP2-membership.csv VERBOSE: FXGROUP2 - Exporting the current membership information into the file: FX_FXGROUP2-membership.csv VERBOSE: FXGROUP2 - Comparing Current and Before VERBOSE: FXGROUP2 - Compare Block Done ! VERBOSE: FXGROUP2 - No Change VERBOSE: Script Completed ``` As you can see, the first time you run the script it will create the two directories 'Output' and 'ChangeHistory' Output: contains the membership files ChangeHistory: contains all the change that occurred since the script is operational.
In the Output folder, the script save the current membership of each groups
At this point the ChangeHistory is empty. ### Running the script after making a first change on a group</u> I changed the membership of the group FX\FXGROUP
A change is detected by the script, so it creates a file for this group.
Then the script send the following Email Report:
The script send an email with the above report. Notice there is no 'Change History' since no previous changes were detected
### Running the script after making a second change on a group</u> Again, I changed the membership of the group FX\FXGROUP,
A second Change History file is created by the script
You will notice that the email you receive is a bit different. It will contains the Change History of the first file (the previous change made at first) "FX_FXGROUP-ChangeHistory-20131013_185831.csv"
This time the Email Report is a bit different, the script did detect some previous change and include a 'Change History' table in the Email Report.
### Comments Based Help Let's test the help now... ``` PS C:\LazyWinAdmin> Get-Help .\TOOL-MONITOR-AD_Groups.ps1 -full ``` ``` NAME C:\LazyWinAdmin\TOOL-MONITOR-AD_Group.ps1 SYNOPSIS This script is monitoring group(s) in Active Directory and send an email when someone is changing the membership. SYNTAX C:\LazyWinAdmin\TOOL-MONITOR-AD_Group.ps1 [-Group] [-Emailfrom] [-Emailto] [-EmailServer] [] DESCRIPTION This script is monitoring group(s) in Active Directory and send an email when someone is changing the membership. It will also report the Change History made for this/those group(s). PARAMETERS -Group Specifies the group(s) to query in Active Directory. You can also specify the 'DN','GUID','SID' or the 'Name' of your group(s). Using 'Domain\Name' will also work. Required? true Position? 1 Default value Accept pipeline input? false Accept wildcard characters? false -Emailfrom Specifies the Email Address of the Sender Required? true Position? 2 Default value Accept pipeline input? false Accept wildcard characters? false -Emailto Specifies the Email Address of the Destination Required? true Position? 3 Default value Accept pipeline input? false Accept wildcard characters? false -EmailServer Specifies the Email Server IPAddress/FQDN Required? true Position? 4 Default value Accept pipeline input? false Accept wildcard characters? false This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). INPUTS System.String OUTPUTS Email Report NOTES NAME: TOOL-Monitor-AD_Group.ps1 AUTHOR: Francois-Xavier CAT DATE: 2012/02/01 EMAIL: [email protected] REQUIREMENTS: -Read Permission in Active Directory on the monitored groups -Quest Active Directory PowerShell Snapin -A Scheduled Task (in order to check every X seconds/minutes/hours) VERSION HISTORY: 1.0 2012.02.01 Initial Version 1.1 2012.03.13 CHANGE to monitor both Domain Admins and Enterprise Admins 1.2 2013.09.23 FIX issue when specifying group with domain 'DOMAIN\Group' CHANGE Script Format (BEGIN, PROCESS, END) ADD Minimal Error handling. (TRY CATCH) 1.3 2013.10.05 CHANGE in the PROCESS BLOCK, the TRY CATCH blocks and placed them inside the FOREACH instead of inside the TRY block ADD support for Verbose CHANGE the output file name "DOMAIN_GROUPNAME-membership.csv" ADD a Change History File for each group(s) example: "GROUPNAME-ChangesHistory-yyyyMMdd-hhmmss.csv" ADD more Error Handling ADD a HTML Report instead of plain text ADD HTML header ADD HTML header for change history 1.4 2013.10.11 CHANGE the 'Change History' filename to "DOMAIN_GROUPNAME-ChangesHistory-yyyyMMdd-hhmmss.csv" UPDATE Comments Based Help ADD Some Variable Parameters 1.5 2013.10.13 ADD the full Parameter Names for each Cmdlets used in this script ADD Alias to the Group ParameterName -------------------------- EXAMPLE 1 -------------------------- C:\PS>.\TOOL-Monitor-AD_Group.ps1 -Group "FXGroup" -EmailFrom "[email protected]" -EmailTo "[email protected]" -EmailServer "mail.company.com" This will run the script against the group FXGROUP and send an email to [email protected] using the address [email protected] and the server mail.company.com. -------------------------- EXAMPLE 2 -------------------------- C:\PS>.\TOOL-Monitor-AD_Group.ps1 -Group "FXGroup","FXGroup2","FXGroup3" -EmailFrom "[email protected]" -Emailto "[email protected]" -EmailServer "mail.company.com" This will run the script against the groups FXGROUP,FXGROUP2 and FXGROUP3 and send an email to [email protected] using the address [email protected] and the Server mail.company.com. -------------------------- EXAMPLE 3 -------------------------- C:\PS>.\TOOL-Monitor-AD_Group.ps1 -Group "FXGroup" -EmailFrom "[email protected]" -Emailto "[email protected]" -EmailServer "mail.company.com" -Verbose This will run the script against the group FXGROUP and send an email to [email protected] using the address [email protected] and the server mail.company.com. Additionally the switch Verbose is activated to show the activities of the script. -------------------------- EXAMPLE 4 -------------------------- C:\PS>.\TOOL-Monitor-AD_Group.ps1 -Group "FXGroup" -EmailFrom "[email protected]" -Emailto "[email protected]","[email protected]" -EmailServer "mail.company.com" -Verbose This will run the script against the group FXGROUP and send an email to 2 persons using the address [email protected] and the server mail.company.com. Additionally the switch Verbose is activated to show the activities of the script. RELATED LINKS ``` ## Download ### Github Repo Technet Script Repository