PS Reporting – You’ve Got Mail

Automating tasks is typically the end goal of using PowerShell and scheduling normally tedious work. When the automation is done, do you run reports? The reports don’t necessarily have to be the results of the task that the PowerShell script was written to accomplish. The report could also notify an admin if their script ran. Maybe the report sent will include details about how much of the script was successful or how much failed, what parts did fail and so on.

Adding an email notification to an admin is a good practice to get into. For example if you have a script that crawls your Exchange environment to look for users that have had their access to ActiveSync enabled or disabled might be useful from an auditing perspective. It can also be helpful to the admin who may require this to keep track of their user base in a more detailed fashion than just the numbers of users who are affected.

Now, adding email notification does have some caveats. Depending on the email server that you are using to send the emails through, there may be some additional configuration to allow your source workstation/server to send email messages. For an Exchange Server, a Receive Connector will need to be modified or created in order to handle this. If you are using Office 365, additional parameters to the Send-MailMessage cmdlet will be required (ports, credentials, etc.). Thus it may take additional planning in order to make these mailed reports to work properly.

Example of using PowerShell for sending reports:

First, let’s explore the parts of an email message that need to be considered when sending an email message via PowerShell. For this example we are using the Send-MailMessage PowerShell cmdlet.
To: This parameter defines who is receiving the email message
From: This parameter defines the sender, typically for automated reporting this would be a no reply address like ‘No-Reply@Domain.Com’
Subject: This defines the subject of the message and should contain a brief message as to what the report is about.
Body: This is where the report can either be attached as an HTML message body or it can be a simplified summary of data that needs to be replayed as part of the reporting process.
Attachments: If there are multiple reports or files that need to be sent to the recipient that are relevant to the reporting process
Server: This is the server that will be relaying the email message for us. It may need to be configured to allow the email message (as state above)
Port: When connecting to Office 365 SMTP servers to relay email, you need to specify a port to send the email through, use Port 587.
UseSSL: This is a required setting for connecting to Office 365

Credential: Need in order to authenticate to Office 365 and relay email properly.

The Scenario

Let’s say we have a security conscientious environment where the Security Team wants to make sure only the required personnel have access to ActiveSync with their personal devices. In order to control this an approved list has been created and is used with a scheduled task to disable or enable an end-users’ access to ActiveSync.

This scheduled task has been in place for a month and now an auditing process has been initiated and tasked to you, the Exchange Admin. In order to accommodate the request, you decided to produce some results and email them to the IT Admins group for visibility. These reports will be scheduled and emailed to the group once per week.
How can we code for the email portion of the reporting process?

Code for Sample Scenario
[sourcecode language=”powershell”]
#########################
# Information Gathering #
#########################
$ActiveSyncMailboxes = (Get-CasMailbox -ResultSize Unlimited | where {$_.ActiveSyncEnabled -eq $True}).DisplayName
$NoActiveSyncMailboxes = (Get-CasMailbox -ResultSize Unlimited | where {$_.ActiveSyncEnabled -eq $False}).DisplayName
$EnabledCount = ($ActiveSyncMailboxes).Count
$DisabledCount = ($NoActiveSyncMailboxes).Count
#########################
# Create Summary Report #
#########################
$Summary += "Summary of ActiveSync Enabled and Disabled Users"
$Summary += "———————————————————————"
$Summary += ""
$Summary += "Users Enabled for ActiveSync: $EnabledCount"
$Summary += "Users with no access to ActiveSync: $DisabledCount"
$Summary += ""
$Summary += "** Attached are lists of users enabled and disabled for ActiveSync access."
$ActiveSyncMailboxes | Out-File 'ActiveSyncEnabledUsers.csv'
$NoActiveSyncMailboxes | Out-File 'ActiveSyncDisabledUsers.csv'
#######################
# Sample of Reporting #
#######################
# SMTP Server Connection settings – Office 365
$SMTPusername = "YourGlobalAdmin@domain.Com"
$SMTPpassword = Cat C:\SecureString.txt | ConvertTo-secureString
$SMTPCred = New-Object -typeName System.Management.Automation.PSCredential -argumentlist $SMTPusername, $SMTPpassword
$SMTPServer = 'smtp.office365.com'
$Port = '587'
# Email Configuration
$To = 'ITAdmins@domain.com'
$From = 'Reporting@domain.com'
$Subject = 'Report on Users enabled for ActiveSync'
$Body = Get-Content Summary.txt -Raw
$Attachments = 'ActiveSyncEnabledUsers.csv','ActiveSyncDisabledUsers.csv'
# Send the email using the above parameters
Send-MailMessage -To $To -From $From -Subject $Subject -Bodyashtml -Body $Body -SMTPServer $SMTPServer -Credential $SMTPCred -Port $Port -UseSsl -Attachments $Attachments
[/sourcecode]
Summary

As we can see above, coding an email report can be straightforward, but it can take some code to produce the desired results. While the above example is used for relaying email through an Exchange Online tenant, it can be modified to relay through an on-premises server as well.