PowerShell - Monitor and Report Active Directory Group Membership Change

UPDATE 2016/05/03: The most recent update is available on Github

See also the related blogpost: http://www.lazywinadmin.com/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] 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 job has 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

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 "catfx@fx.local" -EmailFrom "PowerShellMonitoring@fx.local"

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

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

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] <string> [-Emailfrom] <mailaddress>
    [-Emailto] <mailaddress> [-EmailServer] <string> [<commonparameters>]


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:    info@lazywinadmin.com

        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 "From@Company.com" -EmailTo
    "To@Company.com" -EmailServer "mail.company.com"


    This will run the script against the group FXGROUP and send an email to To@Company.com using
    the address From@Company.com and the server mail.company.com.





    -------------------------- EXAMPLE 2 --------------------------

    C:\PS>.\TOOL-Monitor-AD_Group.ps1 -Group "FXGroup","FXGroup2","FXGroup3" -EmailFrom
    "From@Company.com" -Emailto "To@Company.com" -EmailServer "mail.company.com"


    This will run the script against the groups FXGROUP,FXGROUP2 and FXGROUP3  and send an email
    to To@Company.com using the address From@Company.com and the Server mail.company.com.





    -------------------------- EXAMPLE 3 --------------------------

    C:\PS>.\TOOL-Monitor-AD_Group.ps1 -Group "FXGroup" -EmailFrom "From@Company.com" -Emailto
    "To@Company.com" -EmailServer "mail.company.com" -Verbose


    This will run the script against the group FXGROUP and send an email to To@Company.com using
    the address From@Company.com 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 "From@Company.com" -Emailto
    "Auditor@Company.com","Auditor2@Company.com" -EmailServer "mail.company.com" -Verbose


    This will run the script against the group FXGROUP and send an email to 2 persons using the
    address From@Company.com 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


Thanks for Reading! If you have any questions, leave a comment or send me an email at fxcat@lazywinadmin.com. I invite you to follow me on Twitter @lazywinadm