Microsoft Management Activity API (O365 Azure Events)

The Microsoft Management Activity API integration enables you to subscribe or unsubscribe to different audits, receive their content and fetch new content as incidents. Through the integration you can subscribe to new content types or stop your subscription, list the available content of each content type, and most importantly - fetch new content records from content types of your choice as Demisto incidents.

This integration was integrated and tested with version 1.0 of Microsoft Management Activity API (O365 Azure Events)

Grant Demisto Authorization in Microsoft Management Activity API

To allow us to access Microsoft Management Activity API you will be required to give us authorization to access it.

  1. To grant authorization, click HERE.
  2. After you click the link, click the Start Authorization Process button.
  3. When prompted, accept the Microsoft authorization request for the required permissions. You will get an ID, Token, and Key, which you need to enter in the corresponding fields when configuring an integration instance.

Self-Deployed Configuration

  1. Enter the following URL (Note: CLIENT_ID and REDIRECT_URI should be replaced by your own client ID and redirect URI, accordingly): https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https://manage.office.com&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
  2. When prompted, accept the Microsoft authorization request for the required permissions.
  3. The URL will change and will have the following structure: SOME_PREFIX?code=AUTH_CODE&session_state=SESSION_STATE Take the AUTH_CODE (without the “code=” prefix) and enter it to the instance configuration under the “Authentication” code section. Moreover, enter your client secret as the “Key” parameter and your client ID as the “ID” parameter.

Configure Microsoft Management Activity API (O365 Azure Events) on Demisto

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for Microsoft Management Activity API (O365 Azure Events).
  3. Click Add instance to create and configure a new integration instance.
ParameterDescriptionRequired
base_urlBase URLFalse
auth_idID (received from the authorization step - see Detailed Instructions (?) section)False
enc_keyKey (received from the authorization step - see Detailed Instructions (?) section)False
refresh_tokenToken (received from the authorization step - see Detailed Instructions (?) section)False
self_deployedUse a self-deployed Azure applicationFalse
auth_codeThe authentication code you got for the service. For instructions on how to receive it, see the detailed description ('?') section.False
insecureTrust any certificate (not secure)False
proxyUse system proxy settingsFalse
first_fetch_deltaFirst fetch time range (<number> <time unit>, e.g., 1 hour, 30 minutes)False
content_types_to_fetchContent types to fetchFalse
isFetchFetch incidentsFalse
incidentTypeIncident typeFalse
record_types_filterRecord types to fetch (Comma-separated list of the record types you wish to fetch. Content records with a record type that isn&#x27;t specified will not be fetched. If this field is left empty, all record types will be fetched.)False
workloads_filterWorkloads to fetch (Comma-separated list of the workloads you wish to fetch. Content records with a workload that isn&#x27;t specified will not be fetched. If this field is left empty, all workloads will be fetched.)False
operations_filterOperations to (Comma-separated list of the operations you wish to fetch. Content records with an operation that isn&#x27;t specified will not be fetched. If this field is left empty, all operations will be fetched.)False
  1. Click Test to validate the URLs, token, and connection.

Commands

You can execute these commands from the Demisto CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

ms-management-activity-start-subscription


Starts a subscription to a given content type

Base Command

ms-management-activity-start-subscription

Input
Argument NameDescriptionRequired
content_typeThe content type to subscribe to.Required
Context Output

There is no context output for this command.

Command Example

!ms-management-activity-start-subscription content_type=Audit.Exchange

Context Example
{
"MicrosoftManagement": {
"Subscription": {
"ContentType": "Audit.Exchange",
"Enabled": true
}
}
}
Human Readable Output

Successfully started subscription to content type: Audit.Exchange

ms-management-activity-stop-subscription


Stops a subscription to a given content type

Base Command

ms-management-activity-stop-subscription

Input
Argument NameDescriptionRequired
content_typeThe content type to unsubscribe from.Required
Context Output

There is no context output for this command.

Command Example

!ms-management-activity-stop-subscription content_type=Audit.Exchange

Context Example
{
"MicrosoftManagement": {
"Subscription": {
"ContentType": "Audit.Exchange",
"Enabled": false
}
}
}
Human Readable Output

Successfully stopped subscription to content type: Audit.Exchange

ms-management-activity-list-subscriptions


List the content types you are currently subscribed to

Base Command

ms-management-activity-list-subscriptions

Input

There are no input arguments for this command.

Context Output
PathTypeDescription
MicrosoftManagement.SubscriptionstringList of current subscriptions
Command Example

!ms-management-activity-list-subscriptions

Context Example
{
"MicrosoftManagement": {
"Subscription": [
{
"ContentType": "Audit.AzureActiveDirectory",
"Enabled": true
},
{
"ContentType": "Audit.Exchange",
"Enabled": true
},
{
"ContentType": "Audit.General",
"Enabled": true
},
{
"ContentType": "Audit.SharePoint",
"Enabled": true
}
]
}
}
Human Readable Output

Current Subscriptions

Current Subscriptions
Audit.AzureActiveDirectory
Audit.Exchange
Audit.General
Audit.SharePoint

ms-management-activity-list-content


Returns all content of a specific content type.

Base Command

ms-management-activity-list-content

Input
Argument NameDescriptionRequired
content_typeThe content type for which to receive content.Required
start_timeThe earliest time to get content from. If start_time is specified, end_time must also be specified. The start_time must be before the end_time, can be at most 7 days ago, and has to be within 24 hours from end_time. Required format: YYYY-MM-DDTHH-MM-SS. If not specified, start time will be 24 hours ago.Optional
end_timeThe latest time to get content from. If end_time is specified, start_time must be also specified. The start_time must be before the end_time and has to be within 24 hours from start_time. Required format: YYYY-MM-DDTHH-MM-SS. If not specified, end_time will be now.Optional
record_types_filterA comma-separated list of the record types to fetch. Content records with a record type that isn't specified will not be fetched. If this field is left empty, all record types will be fetched.Optional
workloads_filterA comma-separated list of the workloads to fetch. Content records with a workload that isn't specified will not be fetched. If this field is left empty, all workloads will be fetched.Optional
operations_filterA comma-separated list of the operations to fetch. Content records with an operation that isn't specified will not be fetched. If this field is left empty, all operations will be fetched.Optional
Context Output
PathTypeDescription
MicrosoftManagement.ContentRecord.IDnumberThe ID of the record.
MicrosoftManagement.ContentRecord.CreationTimedateThe creation time of the record.
MicrosoftManagement.ContentRecord.RecordTypestringThe type of the record.
MicrosoftManagement.ContentRecord.OperationstringThe operation described in the record.
MicrosoftManagement.ContentRecord.UserTypestringThe type of the related user.
MicrosoftManagement.ContentRecord.OrganizationIDnumberThe ID of the organization relevant to the record.
MicrosoftManagement.ContentRecord.UserKeystringThe key of the related user.
MicrosoftManagement.ContentRecord.ClientIPstringThe IP of the record&#x27;s client.
MicrosoftManagement.ContentRecord.ScopestringThe scope of the record.
MicrosoftManagement.ContentRecord.WorkloadstringThe workload of the record.
MicrosoftManagement.ContentRecord.ResultsStatusstringThe results status of the record.
MicrosoftManagement.ContentRecord.ObjectIDstringThe ID of the record&#x27;s object.
MicrosoftManagement.ContentRecord.UserIDstringThe ID of the record&#x27;s user.
Command Example

!ms-management-activity-list-content content_type=audit.general

Context Example
{
"MicrosoftManagement": {
"ContentRecord": [
{
"CreationTime": "2020-04-26T10:10:10",
"ID": "TEST ID",
"ObjectID": "test-id",
"Operation": "TeamsSessionStarted",
"OrganizationID": "test-organization",
"RecordType": 9,
"UserID": "test@mail.com",
"UserKey": "test-key",
"UserType": 12,
"Workload": "MicrosoftTeams"
},
{
"CreationTime": "2020-04-26T09:09:09",
"ID": "TEST ID",
"Operation": "MemberAdded",
"OrganizationID": "test-organization",
"RecordType": 8,
"UserID": "Application",
"UserKey": "test-key",
"UserType": 11,
"Workload": "MicrosoftTeams"
}
]
}
}
Human Readable Output

Content for content type audit.general

IDCreationTimeWorkloadOperation
1111111-aaaa-bbbb2020-04-26T10:10:10MicrosoftTeamsTeamsSessionStarted
2222222-vvvv-gggg2020-04-26T09:09:09MicrosoftTeamsMemberAdded