Converting the Dropbox Activity Log into Common Event Format Events

Dropbox Audit Events in a SIEM-Friendly Format

Dropbox Business accounts keep a detailed activity log of team actions: file modifications, policy changes by admins, new member additions, and more. That log is accessible through the admin console or the Dropbox Business APIs, making it a solid source for security auditing, monitoring, and data-loss prevention work.

Security information and event management (SIEM) tools typically need to ingest events from many different systems. Consolidating those inputs is often messy, which is why MicroFocus ArcSight defined the Common Event Format (CEF). CEF establishes a standard structure for log and audit messages so that SIEM applications can process events from diverse sources without custom parsing for each one.

The value of converting Dropbox events to CEF is straightforward: it makes the data easier for SIEM platforms to consume. Below we cover how to pull events from the Dropbox activity log, the key elements of CEF, and how to map Dropbox fields into that format.

Pulling Events from the Dropbox Team Log

The Dropbox Business API exposes activity through the team_log/get_events and team_log/get_events/continue endpoints. To call these you need an access token from an app with either “Team Auditing” or “Team Member File Access” permissions.

Four optional parameters control the result set: limit, account_id, time, and category. Omit them and the endpoints return the complete list, which can be unwieldy. Two cURL examples show typical usage.

Objective: Return 10 events, filtered on file operation events

curl -X POST https://api.dropboxapi.com/2/team_log/get_events \
    --header "Authorization: Bearer <auth_token>" \
    --header "Content-Type: application/json" \
    --data "{\"limit\": \"10\",
            \"category\":\"file_operations\"}"

Objective: Return all events for account id dbid:AACaXNrKenjisuUqxju9ppCK5B4J1rknytk from a specific date range

curl -X POST https://api.dropboxapi.com/2/team_log/get_events \
    --header "Authorization: Bearer <auth_token>" \
    --header "Content-Type: application/json" \
    --data "{\"account_id\": \"dbid:AACaXNrKenjisuUqxju9ppCK5B4J1rknytk\",
            \"time\":
              {\"start_time"\: \"2019-09-12T00:00:00Z"\,
              \"end_time"\: \"2019-12-12T00:00:00Z"\}
            }"

The response from the team_log endpoints contains a list of entries under an event field, a cursor, and a has_more flag. Each entry includes fields such as event_type, actor, origin, and assets. Every event will always carry the timestamp, event category, event type, and details fields; other fields like origin and assets may be absent depending on the event type.

Whenever has_more is true, the returned cursor lets you paginate through the remaining events by passing it to team_log/get_events/continue. Cursors can also be saved and reused to poll for new activity, but they expire after a few days and need to be refreshed with each call. Plan for reset exceptions when a cursor has lapsed.

CEF Structure at a Glance

CEF standardizes log output into two parts: a fixed header with metadata, and an extension composed of key-value pairs. Pipes (|) separate each header field, and the extension follows the final pipe. A full CEF event, once dispatched to a syslog server, looks like:

CEF:Version|Device Vendor|Device Product|Device Version|Device Event Class ID|Name|Severity|[Extension]

Three header fields carry event-specific meaning. Device Event Class ID maps to a unique identifier per event type. Name is a human-readable description of the event. Severity is an integer ranking of importance: 0-3 is Low, 4-6 Medium, 7-8 High, and 9-10 Very-High. The other header values are static descriptors of the device producing the log.

The extension holds defined keys that map to particular data types. For instance, src is used for IPv4 addresses (src=10.0.0.1). Extensions are space-separated, and any number of key-value pairs can appear in any order.

A sample Dropbox team event formatted as CEF:

CEF:0|Dropbox|Dropbox Audit Log|1|logout|Signed out|6|[email protected] duid=dbmid:AAACCXX cat=logins rt=Feb 24 2016 22:45:43 end=Feb 24 2016 22:45:43 src=10.10.0.111

Mapping Dropbox Fields to CEF Keys

Converting a Dropbox event to CEF means translating the available fields into the CEF key names. The Dropbox log often includes detail that does not map cleanly to a CEF extension key; the CEF key list comes from MicroFocus’ documentation.

Severity needs to be assigned per event, since CEF headers do not carry Dropbox’s own severity or categories. Pick a value based on the impact an event category has on the team. A document comment might rate Low, while a change to two-factor authentication settings or team-wide policies would rate High. The severity ranking can be adjusted to each organization’s own definitions.