Using Exchange Server 2007 Built-in Scripts - Part 2: Generating Transport AntiSpam Agent Reports

Introduction

In our last article we saw some built-in scripts related to Public Folder management. We also saw that all Exchange default scripts are located under the scripts folder within the Exchange Server installation folder.

In this article we are going to go over some scripts that enable administrators to get some reports from anti-spam agents and we are also going to use some extra scripts to improve the admin experience in order to create better reports.

Generating HTML output from the Exchange Management Shell …

First of all, let’s use the PowerShell Scriptacular that is a set of useful scripts that can be used with PowerShell and also with the Exchange Management Console. This set of scripts was developed by Vivek Sharma and Mihai Jalobenau during their work on Exchange Management Shell.

To download this pack we can check the viveksharma.com: techlog where you can download the latest version. The current Scriptacular has the following scripts:

Addfakeservers.ps1
removefakeservers.ps1
balancemailboxes.ps1
generate.ps1
cleanup.ps1
initvars.ps1
mailstorm.ps1
mailstorm2.ps1
multi-matrix.ps1
out-email.ps1
out-html.ps1
out-ie.ps1

In order to install Scriptacular just download the zip file from Vivek’s web site and extract all the content into the Scripts folders of the Exchange Server 2007 installation path. If you installed Exchange Server using the default settings it should be at c:\program files\Microsoft\Exchange Server\Scripts folder.

In this article we are going to work with the last two scripts of that list which are: out-html.ps1 and out-ie.ps1. Both of these can be used with an extra (pipe) at the end of any PowerShell commandlet, the first one generates the output in HTML format and the second one gets the output and displays it in an Internet Explorer session.

Now, that we know how to install it and which scripts we are going to work on, let’s see how to use them. Let’s say that we create a daily report of our Mailbox statistics and we have been running Get-MailboxStatistics select DisplayName,ItemCount Export-csv c:\report.csv. Now, let’s improve the output format using Scriptacular by just adding the following two extra commands:

Get-MailboxStatistics select DisplayName,ItemCount out-html out-ie

Now you can compare both outputs as shown in Figure 01 and Figure 02.

Figure 01: Output created by out-html out-ie
Figure 02: Output created by Export-csv cmdlet

We can go a little bit further and create a script to generate an html report using some scripts that we have just seen. The following three lines can be saved as a .ps1 extension and it can be executed daily, the result will be a file name containing month and day of the execution in the name, the content of this file will be the output of Get-MailboxStatistics.

$VarDay = (Get-Date).day

$VarMonth = (Get-Date).month

Get-MailboxStatistics out-html out-file c:\reports\MailboxStatistics-$VarMonth-$VarDay.html
Creating Anti-spam usage reports…

Before diving in the built-in scripts about anti-spam agents we have to be aware of how the transport agents record their actions in Exchange Server 2007. All operations performed by some anti-spam agents are recorded in text files in the directory AgentLog and this folder can be found at \TransportRoles\Logs\AgentLog\, and by default any Hub Transport and Edge Transport Server writes information in that folder. The only transport agents that are able to write in this folder are: Connection Filter, Content Filter, Edge Rules, Recipient Filter, Sender Filter and Sender ID agents.

The content of the AgentLog folder is a bunch of log files in a circular logging mode which means that when they reach the age limit of 30 days or 250MB (whichever comes first) in total they will be automatically removed. They are generated by day or 10MB whichever comes first, as well. An Exchange Administrator can enable or disable the AgentLog files but there is no way to configure path, age limit, maximum individual size, and maximum size for the directory. Each agent log file has the following data information:

Timestamp
SessionId
LocalEndpoint
RemoteEndpoint
EnteredOrgFromIP
MessageId
P1FromAddress
P2FromAddresses
Recipient
NumRecipients
Agent
Event
Action
SmtpResponse
Reason
ReasonData
Diagnostics

We can use notepad to open the log files (Figure 03) and all the information can be read from that file, we can also use Excel to separate the content in different columns.
Figure 03: Agent Log file opened in notepad

There is another way to read and sort information from those log files easily which is by using the Get-Agentlog cmdlet (Figure 04). The agent-log will display the same information but in a better way. We can take a closer look at the output of the get-AgentLog output and we are able to check who sent the message, who was supposed to receive the message, the action taken, and also the SMTP Response and Reason why the message was not delivered.
Figure 04: Get-Agentlog cmdlet output

Okay, now that we know how the anti-spam agents record the information and we also know how to use out-html and out-ie we can add one more item to our mix: anti-spam scripts that generate some reports about anti-spam activity .

The following anti-spam scripts can be used to gather information from Agentlog, as follows:

SCL Histogram: We can retrieve the information logged by the Content Filter agent and group it by SCL value. In order to sort the output, we can use the following cmdlet (Figure 05)

.\get-antispamSCLHistogram.ps1 sort-object Name

Figure 05: SCL Histogram

Top Blocked Sender Domains: Lists the top N sender domains that were blocked by anti-spam transport agents and we also need to specify if this information is coming from p1 or p2, where P1 information comes from message envelope (from header field) and p2 comes from message header (from header field). We can use the following command, as shown in Figure 06.

.\get-AntispamTopBlockedSenderDomains.ps1 p1
Figure 06: Top Blocked Sender Domains

Filtering Report: This script allows the administrator to list which agents are responsible for any of these options:

MessagesRejected
MessagesDeleted
MessagesQuarantined
Connections
Commands

For example, let’s use the following command to retrieve a list of the agents that are rejecting messages, as shown in Figure 07.

.\get-AntispamFilteringReport.ps1 messagesrejected

Now we know that the Content Filter is responsible for 546 messages blocked in our organization.

Figure 07: Filtering Report

Top Blocked Sender IP: Using this script we can list the top N blocked Sender IP, we can use the switch –top and specify how many entries we want to see in the output of the script, in the following script (Figure 08) we are retrieving the 20 top IPs that were blocked by our anti-spam agents, as follows:

.\Get-AntispamTopBlockedSenderIPs.ps1 –top 20
Figure 08: Top Blocked Sender IP

Top Blocked Senders: Shows a list of the top N blocked senders, we also have to specify if we are listing from p1 or p2 field, as shown in Figure 09.

.\get-AntispamTopBlockedSenders.ps1 p1

Figure 09: Top Blocked Senders

Top RBL Providers: Will list the top N Real time Block List Providers, the default value for top is 10 which is not applicable in the current environment because I am using only 2 RBLs, as shown in Figure 10.

.\Get-AntiSpamTopRBLProviders.ps1
Figure 10: Top RBL Providers

Top Recipients: This script gets the top N recipients that were blocked by anti-spam agents. To get the top 10 the following command can be used, as shown in Figure 11.

.\Get-AntispamTopRecipients.ps1

Figure 11: Top Recipients

Validating the Exchange Server installation

There is also a script which improves the reading of Exchange Setup Logs. During the installation process the setup creates a folder called C:\ExchangeSetupLogs and adds a lot of information that is being processed in the background into the ExchangeSetup.log file. We can go over that file using any text editor because it is a simple text file, however we can use GetSetupLogs.ps1 to see the same information. The difference is that it shows the warning and critical errors in different colors and it may help you in understanding installation troubleshooting issues.

To validate the setup installation log using the built-in script, just run .\Get-SetupLog.ps1 from the Scripts folder, as shown in Figure 12.

Figure 12: .\Get-SetupLog.ps1

There are some switches that may be helpful, such as:

tree: where the output will be in a tree format
error: only errors and warnings will e displayed

Conclusion

In this article we saw how the built-in anti-spam scripts gather information from agentlog to create some reports, we also saw how to use Scriptacular package to enable html and Internet Explorer output from a PowerShell session.
Finally, we can combine the out-html and out-ie with any of the scripts shown in this article in order to get better view of the anti-spam transport agents.