Expanding the functionality of the Start-HistoricalSearch cmdlet

Those of you accustomed to running message traces in Office 365 are probably aware of the Start-HistoricalSearch cmdlet, used to asynchronously request a trace for events past the 10-day horizon supported by Get-MessageTrace. In addition, the cmdlet is used to obtain “extended” trace reports, listing mail flow events. Now, it seems that Microsoft is positioning this cmdlet to provide other types of reports as well.

If you check the official documentation of the cmdlet, you might notice that the –ReportType parameter now lists quite few additional values, as follows:

  • ATPReport: Advanced Threat Protection File Types Report and Advanced Threat Protection Message Disposition Report
  • ATPV2: Exchange Online Protection and Advanced Threat Protection E-mail Malware Report.
  • ATPDocument: Advanced Threat Protection Content Malware Report for files in SharePoint, OneDrive and Microsoft Teams.
  • DLP: Data Loss Prevention Report.
  • Malware: Malware Detections Report.
  • MessageTrace: Message Trace Report.
  • MessageTraceDetail: Message Trace Details Report.
  • Phish: Exchange Online Protection and Advanced Threat Protection E-mail Phish Report.
  • SPAM: SPAM Detections Report.
  • Spoof: Spoof Mail Report.
  • TransportRule: Transport or Mail FLow Rules Report.
  • UnifiedDLP: Unified Data Loss Prevention Report.

To request each of these additional reports, you can use the following syntax:

Start-HistoricalSearch -ReportTitle testSpoof -ReportType Spoof -NotifyAddress vasil@domain.info -StartDate "14 Dec 2019" -EndDate "30 Dec 2019"

To get the status of any submitted reports, use the Get-HistoricalSearch cmdlet:

Get-HistoricalSearch

JobId SubmitDate ReportTitle Status Rows ErrorCode ErrorDescription

----- ---------- ----------- ------ ---- --------- ----------------

e8fe474e-424c-4dc3-a5be-6f41515174f6 20/01/2020 08:39:07 testATP Done 0

0aa02ccb-6a3a-4d68-961c-3c0c701e2eb5 20/01/2020 08:39:33 testDLP Done 0

cdcad072-2873-49de-a2cd-278ceeb35ecd 20/01/2020 08:39:53 testPhish Done 22

33e3f7f6-b13c-4ec8-9ff3-8cec042fea8e 20/01/2020 10:15:17 testSpam Done 28

80b1d7ce-e8c7-4e13-8843-15c47f7f0cb2 20/01/2020 10:15:26 testSpoof Done 4

As with the extended message trace reports, you will be submitting an async request, and after the corresponding report has been generated, you will receive an email notification with a link to download the report. Unfortunately, automatic this part is not possible.

The reports themselves seem to offer similar level of detail to the data obtained via the Get-MailDetail* cmdlets, where applicable, but also add some additional fields. For example, the Spam report will show the “standard” sender/recipient information, but also lists the original sender IP, connecting IP, hello string and SCL of the message:

SpamReport

In effect, the reports save you from running additional traces, as they readily provide those additional details. Here’s also an example Phish report generated for my tenant:

PhishReport

Since the documentation page is the only resource mentioning this new reports, it’s unclear at this point whether this is Microsoft’s planned replacement for the “old” reporting cmdlets, or just a new feature. I’ll update the article as I get new information about the reports.

UPDATE 03/2023: Some additional reports exposed in the “new” EAC use the Start-HistoricalSearch cmdlet for their export (Request report) functionality. For example, the Auto forwarded message report found under https://admin.exchange.microsoft.com/#/reports/autoforwardedmessages, the SMTP AUTH Clients report (https://admin.exchange.microsoft.com/#/reports/smtpauthmailflowdetails) or the Outbound Message in Transit Security report report (https://admin.exchange.microsoft.com/#/reports/outboundsecurity). To download the data from each of these, you can use the Start-HistoricalSearch cmdlet with the relevant paramters (-ReportType: AutoForward, SmtpCSReport or OutboundSecurityReport, respectively). Some additional parameters might be required depending on the report, such as –BlockStatus/-SmtpSecurityError for the Outbound Message in Transit Security report. Unfortunately, the documentation has not been updated with details on each parameter, so you’re better of scheduling them via the UI, then using the Get-HistoricalSearch cmdlet to examine the relevant properties and prepare your own request.

Here’s for example how the Get-HistoricalSearch output looks for the Outbound Message in Transit Security report:

JobId : ec082393-0bc8-4757-8226-5f1f6303f1f5
Identity : ec082393-0bc8-4757-8226-5f1f6303f1f5
SubmitDate : 05/03/2023 14:01:33
ReportTitle : Custom Report - OutboundSecurityReport_Secured - 3/5/2023
Status : Done
Rows : 277
FileRows : 277
ErrorCode :
ErrorDescription :
FileUrl : https://admin.protection.outlook.com/ExtendedReport/Download?Type=OnDemandReport&RequestID=ec082393-0bc8-4757-8226-5f1f6303f1f5
ReportStatusDescription : Complete – Ready for download
ReportType : OutboundSecurityReport
NotifyAddress : {vasil@michev.info}
StartDate : 05/12/2022 02:00:00
EndDate : 04/03/2023 01:59:59
DeliveryStatus : All
SenderAddress : {}
RecipientAddress : {}
OriginalClientIP :
MessageID : {}
DLPPolicy : {}
TransportRule : {}
Locale : en-US
Direction : All
CompletionDate : 05/03/2023 14:21:31
EstimatedCompletionTime :
JobProgress :
EncryptionType :
EncryptionTemplate :
IsSaved : False
NumOfBlocks : 0
CompressFile : False
NetworkMessageID : {}
Url :
BlockStatus : AllSecured
SmtpSecurityError : Success

Unfortunately, still no way to directly fetch the results out of the URL above, passign a token doesn’t seem to work.

4 thoughts on “Expanding the functionality of the Start-HistoricalSearch cmdlet

  1. Mar says:

    Dear Michev,

    is there any way to download the Historical Search Report? Couldn’t we do an OAuth against Office365 and then download with the Access token the report using Invoke-Webrequest?

    best Regards,
    Mar

    Reply
  2. Ryan says:

    This is a topical article and nice to see. I’m interested to know if you’re aware of any way to get recipient detail from the UnifiedDLP report type? When I run it we only see “Last modified by”, but we want to see who the item that triggered the DLP rule was sent to. Seems like an obvious ask, but maybe not!

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.