Security-Focused O365 Management and Log Scripts
Contributions are welcome, whether new scripts, documentation, or improvements to existing work. Refer to CONTRIBUTING.md for details.
Table of Contents
- Common EDU License Types
- Logs Within Office 365
- Exporting Logs
- Scripts for Log Processing
- Log Examples
- Describe what O365 logs are available per common EDU license types
- Describe how and with what tools the logs can be accessed
- Describe how the logs may be exported to external tools (e.g. SIEM)
- Provide scripts that retrieve log information for specific investigative actions.
- Nurture community-of-practice contributions to sustain and increase the value of this open resource.
Common EDU License Types
Please note that MS currently (Fall 2018) identifies five (5) license tiers or SKUs:
- Office 365 Education A1
- Office 365 Education A3
- Office 365 Education A5
- Microsoft 365 Education A3
- Microsoft 365 Education A5
One of the chief distinctions between #1-3 and #4-5 above is Microsoft's licensing model based on knowledge workers vs. FTEs (https://blog.shi.com/software/new-licensing-microsoft-enrollment-education-solutions/). With the exception of A1, the following refer to the Microsoft 365 Education SKUs.
A1: Office 365 Education
A1 is the bottom tier, free licenses for Microsoft O365. No additional security tools are available in this tier.
Note: Alumni and other "loosely affiliated" populations are typically not assigned A3/A5 licenses (depending on the institution), so it's safe to assume you'll have users at this tier with fewer security tools.
A3: Microsoft 365 Education
A3 is the middle tier license for Microsoft O365. A3 includes EMS A3 which adds the following security tools:
- Azure AD Premium P1/Azure AD Plan 1: Secure single sign-on to cloud and on-premises app MFA, conditional access, and advanced security reporting
- Azure Information Protection P1: Encryption for all files and storage locations; Cloud-based file tracking
- Microsoft Advanced Threat Analytics: Protection from advanced targeted attacks leveraging user and entity behavioral analytics
- Microsoft Intune: Mobile device and app management to protect corporate apps and data on any device
A5: Microsoft 365 Education
A5 is the top tier license for Microsoft O365. A5 includes EMS A3 (Intune and Advanced Threat Analytics) + EMS A5 which adds the following security tools:
- Azure AD Premium P2/Azure AD Plan 2 (includes P1 features): Identity and access management with advanced protection for users and privileged identities
- Azure Information Protection P2 (includes P1 features): Intelligent classification and encryption for files shared inside and outside your organization
- Microsoft Cloud App Security: Enterprise-grade visibility, control, and protection for your cloud applications
- Advanced Threat Protection: Safe Links, Safe Attachments, Phish (spoof) policies
- Threat Intelligence: Dashboard of attacks detected against your tenant with easy remediation steps.
Organizations can buy licenses ad-hoc through either their reseller or the Microsoft O365 Admin Portal. Please note that while some features can be enabled for the whole tenant by purchasing only 1 license, this can lead to your tenant not being properly licensed or service degradation. You should only enable the features for the users that you purchased licenses for.
A1/3/5 comparison chart
For a more up to date version, please see the Microsoft 365 Education - Services and features comparison page
Logs Within Office 365
Types of logs
- Email Inbound/Outbound
- Safe Links clicks
- DLP Logs
- Azure AD Logs
- Exchange Online Actions
Note: The Activities API (AKA: Magic Unicorn Tool) is no longer available.3
- OCAS - O365 Cloud App Security (formerly known as Advanced Security Management-ASM)
- MCAS - MS Cloud App Security
- Management API
- Admin Portal
Log Collection Methods available by SKU
|License||OCAS||MCAS||Management API||PowerShell||Admin Portal|
Logs Types available by Collection Method
|Log Type||OCAS||MCAS||Management API||PowerShell||Admin Portal|
|Azure AD Logs||Yes||Yes||Yes||Yes||Yes|
|Exchange Online Actions||Yes||Yes||Yes||Yes||no|
|Export predefined alerts to SIEM||Yes||?||?||?||?|
|Export raw data to SIEM||no||Yes||Possible2||Possible2||no|
OCAS supports exporting alerts to your SIEM by using the SIEM Connector provided by Microsoft. The connector supports exporting as Generic CEF and Micro Focus ArcSight. Both Splunk and ELK appear to be able to import this format; ref: Splunk Deploy and Use Splunk App for CEF and ELK: Cef codec plugin
MCAS logs and alerts can be exported using the SIEM Connector provided by Microsoft. The connector supports exporting as Generic CEF and Micro Focus ArcSight. Both Splunk and ELK appear to be able to import this format; ref: Splunk Deploy and Use Splunk App for CEF and ELK: Cef codec plugin
You can write custom scripts to query MCAS via PowerShell. Microsoft has provided a PowerShell module to help with querying this data.
Note: that this method can be slow for large tenants. There is a POC that speeds this data collection up and will be shared
Using the Management API, you can write custom scripts to export the data. Microsoft employee Brandon Koeller has written a PowerShell script that allows you to export this data to MySQL, Azure Blob Storage, Azure SQL, JSON or CSV.
Splunk provides an add on that will ingest the data for your tenant (from the Management API). The add on is available from the the Splunk base site. Depending on usage, user counts, and audited events, you can expect ~1 GB/day per 10,000 users.
Message Trace logs
Microsoft 365 provides admins with access to Message trace logs either programatically (over PowerShell) or via a GUI (Security and Compliance Center).
For help on using the GUI, see Message trace in the Office 365 Security & Compliance Center .
For pull these logs automatically over PowerShell see Gather Message Trace Logs Script sample
Scripts for Log Processing
A number of community-developed scripts are provided, supporting log query and retrieval, and management actions for specific investigative purposes. View the scripts directory. Please consider contributing your helpful scripts.
Various log examples are provided. Please consider contributing.
1: Requires a license for each user that is being logged. OCAS/MCAS supports scoped deployments now based on Azure AD group.
2: Local scripting & infrastructure development, operations, and maintenance required.
3: Official statement (July 2018) from Microsoft about the Activities API (AKA: Magic Unicorn Tool):
Microsoft has always discouraged the use of undocumented APIs, as it can lead to incorrect assumptions, poor user experience or broken functionality. In this case, the particular Outlook Mail REST API referenced and underlying telemetry was built to support service to service communication and does not guarantee the type of complete and accurate activities data that would be necessary to support security investigation scenarios. Following feedback, we are disabling this API.