O365beat

O365beat is an open-source log shipper used to fetch Office 365 audit logs from the Office 365 Management Activity API and forward them with all the flexibility and capability provided by the beats platform (specifically, libbeat).

It:

1. Includes new kibana visualizations and a dashboard since v1.4.1, showing AlertTriggered events from Microsoft’s Advanced Threat Protection service, a chart of common client IP addresses, a list of unique users, and a running stream of summarized activity.
2. Updates processors to better handle certain log fields. Specifically, the API provides Parameters and ExtendedProperties fields as arrays of objects with just Name and Value keys, which is very confusing and difficult to work with and causes issues with elasticsearch. We found this was true of the ModifiedProperties field as well. This version ships all those as strings, which can then be deserialized or parsed with string-based tools. Most importantly, it stops indexing errors and dropped events.

O365beat requires that you enable audit log search for your Office 365 tenancy, done through the Security and Compliance Center in the Office 365 Admin Portal.

It also needs access to the Office 365 Management API: instructions for setting this up are available in the Microsoft documentation.

Once you have these setup, you’ll be able to get the information needed in the config file. The naming conventions for the settings are a bit odd, in o365beat.yml you’ll see some of the synonyms: client id is also called the application id, and the directory id is also called the tenant id. In the Azure portal, go to “App registrations” and you’ll see the Application (Client) ID – a GUID – right there in the application list. If you click on that you’ll see the application (client) id and the directory (tenant) id in the top area.

The client secret is a little trickier, you can create them by clicking the “Certificates & secrets” link on the left there. Be sure to copy it somewhere or you’ll have to create a new one … there’s no facility for viewing them later. The default config file expects these config values to be in your environment (i.e., as environment variables), named O365BEAT_TENANT_DOMAIN, O365BEAT_CLIENT_SECRET, etc. You can hard-code them in that file if you like, especially when testing, just be smart about the permissions.

Finally, the Azure app registration permissions should look like this:

You can edit those using that “API permissions” link on the left, with more detailed instructions available from Microsoft. The beat should automatically subscribe you to the right feeds, though that functionality is currently undergoing testing.

Changelog v1.5.1

Added

• Added support for the script processor and provided a sample processor script in o365beat.reference.yml to convert fields that contain arrays of name-value pairs into a “normal” object (closes #41)

Changed

• Updated README and config files to highlight options to help avoid timeouts on busy tenancies (closes #39)
• Updated README to link to references on API event data (closes #37)

Download & Use

Copyright (c) 2019 Chris Hendricks