Using Powershell to Simplify Mailbox Auditing (Part 1)

by [Published on 24 Nov. 2011 / Last Updated on 24 Nov. 2011]

In the first part of a three part series, the author develops a sample PowerShell script that allows Exchange administrators to configure daily Mailbox Auditing. The XML based audit reports are then converted into HTML which can be easily used for audit trails.

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:

  1. 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

  1. 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.

  1. You will need the Quests AD CMDlets for PowerShell installed on your Management Server
  2. 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
  3. 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 Mailbox.Audit@yourdomain.com
  4. 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="Mailbox.Audit@prepad.local"

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:

Advertisement

Featured Links