If you would like to read the other parts in this article series please go to:
Introduction
Exchange 2010 SP1 offers the functionality for administrators to setup specific audit logging on Mailboxes within their environment, and when required either via the Exchange Management Shell or via the administrative Exchange Control Panel report on the audit logs that during a given time frame.
Now it is not my intention in this article to get into the real concepts of Mailbox Auditing as that has been already covered very well on MSExchange.org by Neil Hobson in his series which starts here. What I would like to focus on is simplifying, or perhaps more to the point – automating mailbox auditing.
I have decided to do this series as a few things have struck me about the implementation of Mailbox Auditing within Exchange 2010 which are:
-
It can be a little unwieldy – enabling mailbox auditing can only be performed from the Management Shell, and when you wish to review the reports you can only do so via the Search-MailboxAuditLog or via an emailed XML report via the New-MailboxAuditLogSearch CMDlet
Figure 1: Search-MailboxAuditLog Output Example
-
The output from the shell (see figures 1 and 3) can be a little difficult to read – and indeed if you opt to use the New-MailboxAuditLogSearch CMDlet, the XML output can be little hard to interpret
Give the above; I thought it would be good to automate almost the entire process – from enabling the auditing on a mailbox all the way through to formatting the audit reports to look something like the example in figure 2.
Figure 2: Sample Formatted Audit Report
Rather than the default offering that you get depicted in figure 3:
Figure 3: Default XML Audit Report
Over the next three articles we will build a script that can be scheduled to perform the following actions:
-
Enables mailbox auditing based upon the AD account of the mailbox being in a specific OU
-
Executes mailbox audit log searches against the mailboxes which are determined from the AD accounts in the OU and mails them to a dedicated auditing mailbox
-
Queries the auditing mailbox for the XML output files and stores them in a folder on the server where the script has been executed
-
Converts the XML files into a more readable HTML format
-
Archive the old XML files into a separate folder for future reference
Further Learning Analysis
Aside from the stated objectives of this article (e.g. simplifying auditing of mailboxes) – there are a number of other learning points that the script will cover that that you might find useful.
For example;
-
The script shows you how to construct a HTML file with CSS formatting (credit to Thiyagu for the formatting example which I have modified and used in a number of my scripts)
-
How you can use the “Outlook.Application” object to automate the extraction of attachments from a mailbox to a disk location
-
How you can traverse XML files to produce HTML output
-
How you can archive files to another location on Disk
Script Requirements
Before we get into the script – there are a number of pre-requisites that you should ensure that you have complied with before we begin.
-
You will need the Quests AD CMDlets for PowerShell installed on your Management Server
-
You will need Outlook 2007 or 2010 installed on your Exchange server – or perhaps more preferably a dedicated management server with Outlook, Quest and the Exchange Management Tools installed
-
You will need to create a dedicated “Audits” Mailbox within your Exchange environment – it is recommended that you call this mailbox “Mailbox.Audit” – so that the SMTP address is [email protected]
-
You should create an Organizational Unit in Active Directory called “AuditedMailboxes” (or similar the script allows for you to change it) and move a few Active Directory Account which have mailboxes into the OU – these will be processed by the script later on
Figure 4: Audited Mailbox OU in AD
The Script – Functions, Global Constants & Snap-ins
Over the next three parts we will build a number of functions which when combined and executed as the complete script will hopefully simplify Mailbox Auditing functions.
These functions will be:
|
Function Name |
Purpose |
Defined in Part |
|
writeHeader |
Writes the header of a formatted HTML file |
1 |
|
WriteFooter |
Write the footer of a HTML file |
1 |
|
returnUsers |
Gets user AD accounts from a specific OU |
1 |
|
get_OU_CheckAudit |
Check to see if the Mailboxes attached to the accounts have auditing enabled – if not enables the audits |
1 |
|
gen_AuditXMLFiles |
Requests the mailbox audits for the last 24 hours |
2 |
|
perform_MailboxQuery |
Queries the audit mailbox for the XML files generated by the gen_AuditXMLFilesfunction and extracts them to disk |
2 |
|
format_XMLTOHTML |
Formats the audits to HTML and stores them |
2 |
|
manage_XMLPostProcessing |
Archives the old XML files |
3 |
Table 1
Part 3 of this series will also provide you with a completed script for download.
However parts 1, 2 and 3 will take you through each individual function and explain its purpose in detail, as well as any unique features or techniques used.
The script as a whole is designed ultimately to run independently from a batch process (essentially from the command line) therefore we need to ensure that the correct PowerShell Snap-ins are loaded by the script – in order to do this I have included the following Add-PSSnapin CMDlets right at the top of the script:
|
Snapin Name |
Description |
|
Add-PSSnapinMicrosoft.Exchange.Management.PowerShell.E2010 |
Includes the Exchange 2010 Powershell Snap-ins so that Exchange 2010 commands are available to the script |
|
Add-PSSnapinQuest.ActiveRoles.ADManagement |
Includes the Quest Active role AD Management CMDlets so that they are available to the script (only 1 is used – Get-QADUser) |
Table 2
There are a number of tasks that this script performs which require configurable constants to be set in order for them to function or produce output correctly – the following are the constants and their purpose, when using the script within your own environments these will need to be changed accordingly.
All of these are located underneath the PSSNAPIN’s area of the script:
|
Variable Name / Value |
Description |
|
$ErrorActionPreference=’SilentlyContinue’ |
Sets the Global Error Action condition for the entire script |
|
$AuditMailbox=”[email protected]” |
Defines Audit Mailbox to receive reports |
|
$AuditFolder=”x:\Audits” |
Defines the Path on server where the XML files will be extracted to |
|
$ArchivePath=”x:\Audits\Archive” |
Path to archived XML files (change to reflect your own environment) |
|
$OUPath=”prepad.local/AuditedMailboxes” |
OU to review in AD – this OU should contain the audited mailboxes |
|
$OLKProfile=”Audit” |
Outlook profile for the Audit Mailbox -no spaces in profile name! |
|
$EmptyDeletedItemsAfterProcessing=$true |
Empty the Deleted Items Folder in Outlook when the Script has completed (set $true or $false) |
|
$AccessTypes=”Owner,Delegate,Admin” |
The types of access to the mailbox which should be searched for |
Table 3
HTML Output File Construction
The purpose of this script is to provide administrators with a simple to read output of their Mailbox audits – this starts with us designing a couple of functions that will provide the basis for our end HTML reports.
|
Code |
Description |
|
FunctionwriteHeader{ param($fileName) Add-Content$fileName”<html>” Add-Content$fileName”<head>” Add-Content$fileName”<meta http-equiv=’Content-Type’ content=’text/html; charset=iso-8859-1′>” Add-Content$fileName'<title>Audited Mailbox Report</title>’ Add-content$fileName'<STYLE TYPE=”text/css”>’ Add-content$fileName”<!–“ Add-content$fileName”td {“ Add-content$fileName”font-family: Tahoma;” Add-content$fileName”font-size: 11px;” Add-content$fileName”border-top: 1px solid #999999;” Add-content$fileName”border-right: 1px solid #999999;” Add-content$fileName”border-bottom: 1px solid #999999;” Add-content$fileName”border-left: 1px solid #999999;” Add-content$fileName”padding-top: 0px;” Add-content$fileName”padding-right: 0px;” Add-content$fileName”padding-bottom: 0px;” Add-content$fileName”padding-left: 0px;” Add-content$fileName”}” Add-content$fileName “.Headings {“ Add-content$fileName”font-family: Tahoma;” Add-content$fileName”font-size: 14px;” Add-content$fileName”font-weight: bold;” Add-content$fileName”}” Add-content$fileName “p {“ Add-content$fileName”font-family: Tahoma;” Add-content$fileName”font-size: 11px;” Add-content$fileName”}” Add-content$fileName”body {“ Add-content$fileName”margin-left: 5px;” Add-content$fileName”margin-top: 5px;” Add-content$fileName”margin-right: 0px;” Add-content$fileName”margin-bottom: 10px;” Add-content$fileName”” Add-content$fileName”table {“ Add-content$fileName”border: thin solid #000000;” Add-content$fileName”}” Add-content$fileName”–>” Add-content$fileName”</style>” Add-Content$fileName”</head>” Add-Content$fileName”<body>” Add-content$fileName”<table width=’100%’>” Add-content$fileName”<tr bgcolor=’#3366FF’>” Add-content$fileName”<td colspan=’7′ height=’25’ align=’left’>” Add-content$fileName”<font face=’tahoma’ color=’#FFFFFF’ size=’4′><strong>Audited Mailbox Report for – $FileName</strong></font>” Add-content$fileName”</td>” Add-content$fileName”</tr>” Add-content$fileName”</table>” Add-content$fileName”<br>”
} |
The purpose of the “writeHeader” function is to create the basic construct for the HTML file(s) that contain the output of the mailbox audits from the XML source files generated by the New-MailboxAuditLogSearch CMDlet called in the gen_AuditXMLFiles function (detailed in a later part). The function accepts one parameter which is the filename of the HTML file to be created (this is passed from the format_XMLTOHTML function). As you can see the main CMDlet used within this function is Add-Content – with each string passed to the file being a specific HTML or CSS directive. |
|
FunctionWriteFooter{ Param($fileName)
Add-content$fileName”<table width=’100%’>” Add-content$fileName”<tr><td><img alt=’MSExchange.org Logo’ height=’60’ src=’http://www.msexchange.org/img/logo-mse.gif’ width=’300′ /><td>Generated by <a href=’http://msexchange.org’>MSExchange.org’s</a> Mailbox Audit Script</td></td><tr>” Add-content$fileName”</table>” Add-Content$fileName”</body>” Add-Content$fileName”</html>” } |
The WriteFooter function as you might expect writes the end of the output HTML file. Here you can customise the logo or the “Generated by” line to match that of your own company – there are referenced in the <img> tag for the Logo, and the <a Href> tag for the company strap line. WriteFooter is called by the format_XMLTOHTML (this is defined in a later part of this series) |
Table 4
Returning Users in the Organisational Unit in AD and Setting Mailbox Auditing
|
Code |
Description |
|
functionreturnUsers{ $Usrs=Get-QADUser-SearchRoot$OUPath return$Usrs } |
The returnUsers function make use of the Quest AD CMDlets (Get-QADUser) in order to return all of the Active Directory user accounts that are present in the OU which is specified in $OUPath global Constant. returnUsers is called by the get_OU_CheckAudit function in order to determine the accounts which have auditing enabled in the OU or those that don’t. |
|
functionget_OU_CheckAudit{ $Users=returnUsers
Foreach($Usrin$Users){
$Audit=Get-Mailbox$Usr.samAccountName If($Audit.AuditEnabled -eq$true){
Write-Host“Audit is enabled for Mailbox: $Audit”-ForegroundColorGreen }else{ Write-Host“Audit is NOT enabled for Mailbox: $Audit”-ForegroundColorRed Write-Host“Enabling Audit on Mailbox: $Audit”-ForegroundColorCyan Set-Mailbox$Audit-AuditEnabled$true } } } |
The get_OU_CheckAudit function is used to check the OU membership of the of the designated Audited mailboxes in AD. It calls the returnUsers function to get the OU membership into a variable called $Users and then by using a Foreach loop cycles through each account and checks the mailbox see if auditing is enabled. This is done by getting the details of each mailbox into a variable called $Audit using the Get-Mailbox CMDlet. If auditing is not enabled (determined by the If statement which queries the AuditEnabled value on the Exchange mailbox which is contained within the $Auditvariable) – the function corrects this by using the Set-Mailbox CMDlet with the -AuditEnabled$true parameter |
Table 5
Conclusion
In this part we have established that we will be constructing an automated Mailbox Auditing script using PowerShell for Exchange 2010. We determined the pre-requisites of the script and what functions it will contain, and defined the first four functions.
In part 2 we will continue with the next 3 functions:
-
gen_AuditXMLFiles
-
perform_MailboxQuery
-
format_XMLTOHTML
If you would like to read the other parts in this article series please go to:
