Note
We’ve renamed Microsoft Cloud App Security. It’s now called Microsoft Defender for Cloud Apps. In the coming weeks, we’ll update the screenshots and instructions here and in related pages. For more information about the change, see this announcement. To learn more about the recent renaming of Microsoft security services, see the Microsoft Ignite Security blog.
You can use the Activities APIs to investigate the activities performed by your users across connected cloud apps.
The activities API mode is optimized for scanning and retrieval of large quantities of data (over 5,000 activities). The API scan queries the activity data repeatedly until all the results have been scanned.
Note
For large quantities of activities and large scale deployments, we recommended that you use the SIEM agent for activity scanning.
To use the activity scan script
- Run the query on your data.
- If there are more records than could be listed in a single scan, you will get a return command with
nextQueryFiltersthat you should run. You will get this command each time you scan until the query has returned all the results.
Request body parameters
- “filters”: Filter objects with all the search filters for the request, see Activity filters for more information. To avoid having your requests be throttled, make sure to include a limitation on your query, for example, query the last day’s activities, or filter for a particular app.
- “isScan”: Boolean. Enables the scanning mode.
- “sortDirection”: The sorting direction. Possible values are
ascanddesc. - “sortField”: Fields used to sort activities. Possible values are:
date– The date when then the activity occurred (this is the default).created– The timestamp when the activity was saved.
- “limit”: Integer. In scan mode, between 500 and 5000 (defaults to 500). Controls the number of iterations used for scanning all the data.
Response parameters
- “data”: the returned data. Will contain up to “limit” number of records each iteration. If there are more records to be pulled (hasNext=true), the last few records will be dropped to ensure that all data is listed only once.
- “hasNext”: Boolean. Denotes whether another iteration on the data is needed.
- “nextQueryFilters”: If another iteration is needed, it contains the consecutive JSON query to be run. Use this as the “filters” parameter in the next request. Note that if the “hasNext” parameter is set to False, this parameter will be missing since you’ve iterated over all of the data.
The following Python example gets all the activities from the past day from Exchange Online.
import requests
import json
ACTIVITIES_URL = 'https://<your_tenant>.<tenant_region>.portal.cloudappsecurity.com/api/v1/activities/'
your_token = '<your_token>'
headers = {
'Authorization': 'Token {}'.format(your_token),
}
filters = {
# optionally, edit to match your filters
'date': {'gte_ndays': 1},
'service': {'eq': [20893]}
}
request_data = {
'filters': filters,
'isScan': True
}
records = []
has_next = True
while has_next:
content = json.loads(requests.post(ACTIVITIES_URL, json=request_data, headers=headers).content)
response_data = content.get('data', [])
records += response_data
print('Got {} more records'.format(len(response_data)))
has_next = content.get('hasNext', False)
request_data['filters'] = content.get('nextQueryFilters')
print('Got {} records in total'.format(len(records)))