This guide will work thru the steps required in order to collect events from Exchange Admin Reports, including Message Trace, DLP, SPAM, Malware and Spoof mail.
- How to collect events from Exchange Admin Reports
Preface
The Exchange Admin Reports contain valuable information about email traffic, from the raw traffic information (emails sent, received, etc.), to analysis and anomaly detection provided by the Office365 platform. In SkyFormation, this information is collected as part of the Office365 connector. To enable this data collection additional configuration is required as in the MS platform this information is available thru a different set of APIs, which require its own set of permissions and credentials.
Steps
- Ensure Message Trace is collected by Microsoft
- Test if data is collected
- Enable its collection - Create/Configure a user with permissions to collect the events
- Choose which of the Exchange Admin Reports’ data you’d like to collect
- Assign the minimal set of required permissions to the user
- Validate that the user is able to read the events via the API - Configure the Office365 connector with the new credentials
- Set the credentials
- Enable the endpoints
Ensure Message Trace is collected by Microsoft
By default, Microsoft does not collect Message Trace events, and following that, does not analyse the data to generate anomaly and detection events. So before we move forward, lets ensure that the data we’d like to collect is available for us.
Test if data is collected
- Browse to https://protection.office.com/messagetrace
- Click “+ Start a trace”, use the defaults of no specified ‘from’ nor ‘to’ people and a time-range of 2 days, Click Search
- Verify there are results as you’d expect
Enable its collection
In the case that there was no data in the Message Trace search results, or some results were missing, i.e. some users excluded, etc., Here are the steps to enable the collection of message trace events by Microsoft - Microsoft’s guide
It may take up to 24 hours for MS to start collecting the data once the configuration was made
Create/Configure a user with permissions to collect the events
In order to collect the data from Microsoft, a user with permissions to access those events is needed.
It is best practice to create a dedicated user for this task, as it would be easier to track its actions in the future, as well as ensure only the minimal permissions are assigned to it.
So, create a user in the Office365 platform. This user does not need to be assigned to any subscription. Set a strong password for it.
Make sure this user does not need to go thru Multi Factor Authentication, SAML, or any other non-basic methods.
Optionally set the password’s expiry to Never/A very long time, as once the password expires, it’ll break the integration until a new password is set to the user and also updated on the SkyFormation end.
Make sure to create the user in the organization / domain you’d like to monitor. The organization needs to be licensed to the Exchange email functionality.
Choose which of the Exchange Admin Reports’ data you’d like to collect
As some of the Exchange Admin Reports require different permissions, it is important to understand what needs to be configured to allow the collection of the data you need.
In this table, at the bottom row (View reports), MS lists the required permission for each report type Link
Copied here for brevity -
- Organization Management: Users have access to mailbox reports and mail protection reports.
- View-Only Organization Management: Users have access to mailbox reports.
- View-Only Recipients: Users have access to mail protection reports.
- Compliance Management: Users have access to mail protection reports and Data Loss Prevention (DLP) reports (if their subscription has DLP capabilities).
So for example, if you’d only like to collect the Message Trace events, then the “View-Only Organization Management” role is sufficient.
If you’d also like to collect all other Exchange Reports, except the DLP, then you’d also need to assign the “View-Only Recipients” role.
And for DLP, assign the “Compliance Management” role.
For the DLP data source, ensure that the organization have the required subscription. An Office ATP plan is required - See link
Assign the minimal set of required permissions to the user
To set the above roles on the user, log into the old Exchange Admin Portal - https://outlook.office365.com/ecp
- Go to “permissions” of the left panel -> “admin roles” tab
- Select the required role and click the pencil icon at the top
- Under the “Members” section click “+” and search for the username of the user we’d like to set this role to, select it and click “add ->” at the bottom and “OK” and “Save” in the popup windows respectively
It may take anywhere between 3 to 12 hours for the new roles’ permissions to be applied on the user.
Note: View-Only Recipients is a default role and not an admin role. If you want to use this role you should either select one of the admin roles that has it, or create a new admin role with this permission.
Validate that the user is able to read the events via the API
Once the user is created and the desired permissions were set on it, validate that permissions were applied and the user is indeed able to collect events from the MS APIs.
On a machine with the curl command/package available on it, run the following - with adjustments to the username and password -
curl -X GET \
https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace \
-H 'Accept: application/json' \
-H 'cache-control: no-cache' \
-u myuser@mycompany.com:somepassword If successful, it should return with status code 200 and some data.
Configure the Office365 connector with the new credentials
Set the credentials
Once a user with the required permissions is set, data is available from the MS portal, and the user is able to collect it via the test curl command,
Head back to the SkyFormation web interface,
Go to Settings -> Accounts.
Select the row of the Office365 connector and click “EDIT”.
Under the “ENDPOINT Exchange Admin Reports” section enter the Username - the user’s email address - e.g. mysk4user@myorg.com, and Password.
Click “DONE”.
Enable the endpoints
By default, the Exchange Admin Report endpoints, all prefixed by ‘exchange-admin-report-’, are stopped.
Once the credentials are set, we need to enable the ones the credentials allow collection of.
To do that, click on “STATUS” on the Office365 connector row, and find the rows of the respective endpoints.
Click “START” on each of the endpoints.
It’ll take about 2-5 minutes until the first sync. attempts are complete. The respective UI rows will update the status columns automatically.
Click “DONE” to get back to the accounts list.
By default when first started, the exchange-admin-reports-* endpoints will collect data from the past 7 days.
See MS’s guide on retention policies of this data source
Troubleshooting
In case of an error in collection of one or more of the Exchange Admin Reports endpoints, the connector will show a status of “ERROR”.
Click “STATUS” to see which endpoints are failing. Click a row of an endpoint that is failing to open the sync. details on the right panel.
It’ll list up to 3 of the last sync. attempts, each with the result status.
An error will show there as well.
Common errors are a 401 status code - which indicates that a permission is missing.
If it has been more than 3-12 hours since the permissions were granted to the user, and you’re still getting this error, try to run the command listed in the Validate that the user is able to read the events via the API section.
If the error shows there as well, re-validate the all the permissions listed in the step Create/Configure a user with permissions to collect the events were successfully complete.
If still the issue persists, please open a ticket with Microsoft to troubleshoot.
Sample data
If you would like to see how a message trace event from SkyFormation Office 365 connector will look like in your SIEM please download the attached csv event example in this guide.
Comments
0 comments
Please sign in to leave a comment.