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.

Data Enrichment & Threat Intelligence · Microsoft Management Activity API (O365/Azure Events)

Details

ID	`Microsoft Management Activity API (O365 Azure Events)`
Provider	Microsoft
Category	Data Enrichment & Threat Intelligence
From Version	5.0.0
Docker Image	`demisto/auth-utils:1.0.0.10133006`
Supported Modules	Agentix XSIAM Cloud Posture Security

README

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 Cortex XSOAR incidents.

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

Authentication

There are two application authentication methods available:

Note - The credentials (created by the Cortex XSOAR application) are valid for a single instance only.

Self-Deployed Azure App

To use a self-configured Azure application, you need to add a new Azure App Registration in the Azure Portal. To add the registration, refer to the following Microsoft documentation.
Make sure the following permissions are granted for the app registration:
- User.Read of type Delegated
- ActivityFeed.Read of type Delegated
- ActivityFeed.Read of type Application
- ActivityFeed.ReadDlp of type Delegated
- ActivityFeed.ReadDlp of type Application
- ServiceHealth.Read of type Delegated
- ServiceHealth.Read of type Application

Configure Microsoft Management Activity API (O365 Azure Events) in Cortex

Parameter	Description	Required
Base URL	The host URL.	False
Application ID or Client ID	The app registration ID.	False
Key or Client Secret	The app registration secret.	False
Token or Tenant ID	The tenant ID.	False
Certificate Thumbprint	Used for certificate authentication as it appears in the “Certificates & secrets” page of the app.	False
Private Key	Used for certificate authentication. The private key of the registered certificate.	False
Use a self-deployed Azure application	Whether to use a selp-deployed application.	False
Application redirect URI (for self-deployed mode)	The app registration redirect URI.	False
The authentication code you got for the service	For instructions on how to receive it, see the Help tab.	False
Use Azure Managed Identities	Relevant only if the integration is running on Azure VM. If selected, authenticates based on the value provided for the Azure Managed Identities Client ID field. If no value is provided for the Azure Managed Identities Client ID field, authenticates based on the System Assigned Managed Identity. For additional information, see the Help tab.	False
Azure Managed Identities Client ID	The Managed Identities client ID for authentication - relevant only if the integration is running on Azure VM.	False
Trust any certificate (not secure)	Whether to trust any certificate. If set to True, is not secure.	False
Use system proxy settings	Whether to use system proxy settings.	False
First fetch time range	<number> <time unit>, for example 1 hour, 30 minutes.	False
Timeout	The default timeout (in seconds) for API calls. Default is 15 seconds.	False
Content types to fetch	The content types to fetch.	False
Fetch incidents	Whether to fetch incidents.	False
Incident type	The incident type to apply.	False
Record types to fetch	A comma-separated list of the record types you want to fetch. Content records with a record type that is not specified will not be fetched. If this field is left empty, all record types will be fetched.	False
Workloads to fetch	A comma-separated list of the workloads you want to fetch. Content records with a workload that is not specified will not be fetched. If this field is left empty, all workloads will be fetched.	False
Operations to fetch	A comma-separated list of the operations you want to fetch. Content records with an operation that is not specified will not be fetched. If this field is left empty, all operations will be fetched. Important: This field is case-sensitive.	False

Fetch Alerts

The operations to fetch parameter is case-sensitive. For example, DlpRuleMatch and DLPRuleMatch are treated as distinct operations that retrieve information from different workloads.
For more information, see Microsoft’s technical blog and Splunk portal article.

Commands

You can execute these commands from the 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 Name	Description	Required
content_type	The content type to subscribe to. Possible values are: Audit.AzureActiveDirectory, Audit.Exchange, Audit.SharePoint, Audit.General, DLP.All.	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 Name	Description	Required
content_type	The content type to unsubscribe from. Possible values are: Audit.AzureActiveDirectory, Audit.Exchange, Audit.SharePoint, Audit.General, DLP.All.	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

Path	Type	Description
MicrosoftManagement.Subscription	string	List of current subscriptions

Command Example


##### 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 Name** | **Description** | **Required** |
| --- | --- | --- |
| content_type | The content type for which to receive content. Possible values are: Audit.AzureActiveDirectory, Audit.Exchange, Audit.SharePoint, Audit.General, DLP.All. | Required |
| start_time | The 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_time | The 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_filter | A 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_filter | A 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_filter | A 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 |
| timeout | The timeout (in seconds) for the content requesting HTTP call. Default is the value provided as an integration parameter. | Optional |

#### Context Output

| **Path** | **Type** | **Description** |
| --- | --- | --- |
| MicrosoftManagement.ContentRecord.ID | number | The ID of the record. |
| MicrosoftManagement.ContentRecord.CreationTime | date | The creation time of the record. |
| MicrosoftManagement.ContentRecord.RecordType | string | The type of the record. |
| MicrosoftManagement.ContentRecord.Operation | string | The operation described in the record. |
| MicrosoftManagement.ContentRecord.UserType | string | The type of the related user. |
| MicrosoftManagement.ContentRecord.OrganizationID | number | The ID of the organization relevant to the record. |
| MicrosoftManagement.ContentRecord.UserKey | string | The key of the related user. |
| MicrosoftManagement.ContentRecord.ClientIP | string | The IP of the record's client. |
| MicrosoftManagement.ContentRecord.Scope | string | The scope of the record. |
| MicrosoftManagement.ContentRecord.Workload | string | The workload of the record. |
| MicrosoftManagement.ContentRecord.ResultsStatus | string | The results status of the record. |
| MicrosoftManagement.ContentRecord.ObjectID | string | The ID of the record's object. |
| MicrosoftManagement.ContentRecord.UserID | string | The ID of the record'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

ID	CreationTime	Workload	Operation
1111111-aaaa-bbbb	2020-04-26T10:10:10	MicrosoftTeams	TeamsSessionStarted
2222222-vvvv-gggg	2020-04-26T09:09:09	MicrosoftTeams	MemberAdded

ms-management-activity-generate-login-url

Generate the login url used for Authorization code flow.

Base Command

ms-management-activity-generate-login-url

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

Command Example

ms-management-activity-generate-login-url

Human Readable Output

Authorization instructions

Click on the login URL to sign in and grant Cortex XSOAR permissions for your Azure Service Management.
You will be automatically redirected to a link with the following structure:
REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE

Copy the AUTH_CODE (without the code= prefix, and the session_state parameter)
and paste it in your instance configuration under the Authorization code parameter.

ms-management-activity-auth-reset

Run this command if for some reason you need to rerun the authentication process.

Base Command

ms-management-activity-auth-reset

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

Additional Information

Record types to fetch from should be set with numerical values from the Microsoft documentation. For example, in order to fetch events of type MailSubmission, the value 29 should be set.
Note that the API only supports start times up to 7 days in the past when fetching. If the last fetch timestamp exceeds this limit, the integration automatically fetches data from 7 days ago.
The credentials are valid for a single instance only.

Troubleshooting

In case of a hash verification error:

Use the Oproxy flow to generate a new pair of credentials. This is crucial as it ensures that any issues related to authentication can be mitigated with fresh credentials.
Execute the command !ms-management-activity-auth-reset. This command resets the authentication mechanism, allowing for the new credentials to be accepted.
Insert the newly created credentials into the original instance where the error occurred. Make sure the credentials are entered correctly to avoid further errors.
After updating the credentials, test the integration.

Configuration parameters

base_url — Base URL
auth_id — Application ID or Client ID
credentials_auth_id —
refresh_token — Token or Tenant ID
credentials_refresh_token —
enc_key — Key or Client Secret
credentials_enc_key —
certificate_thumbprint — Certificate Thumbprint
credentials_certificate_thumbprint —
private_key — Private Key
self_deployed — Use a self-deployed Azure application
redirect_uri — Application redirect URI (for self-deployed mode)
auth_code — Authorization code (for self-deployed mode)
credentials_auth_code —
use_managed_identities — Use Azure Managed Identities
managed_identities_client_id —
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings
first_fetch_delta — First fetch time range
timeout — Timeout
content_types_to_fetch — Content types to fetch
isFetch — Fetch incidents
incidentType — Incident type
incidentFetchInterval — Incidents Fetch Interval
record_types_filter — Record types to fetch
workloads_filter — Workloads to fetch
operations_filter — Operations to fetch

Commands (6)

ms-management-activity-auth-reset
Run this command if for some reason you need to rerun the authentication process.
ms-management-activity-generate-login-url
Generate the login url used for Authorization code flow.
ms-management-activity-list-content
Returns all content of a specific content type.
ms-management-activity-list-subscriptions
List the content types you are currently subscribed to.
ms-management-activity-start-subscription
Starts a subscription to a given content type.
ms-management-activity-stop-subscription
Stops a subscription to a given content type.

Source

MicrosoftManagementActivity.py MicrosoftManagementActivity_test.py MicrosoftManagementActivity.yml MicrosoftManagementActivity_description.md

Download History Raw

category: Data Enrichment & Threat Intelligence
provider: Microsoft
sectionorder:
- Connect
- Collect
commonfields:
  id: Microsoft Management Activity API (O365 Azure Events)
  version: -1
configuration:
- defaultvalue: https://manage.office.com/api/v1.0/
  display: Base URL
  name: base_url
  type: 0
  section: Connect
  required: false
- display: Application ID or Client ID
  additionalinfo: See the Help tab.
  name: auth_id
  type: 4
  section: Connect
  hidden: true
  required: false
- displaypassword: Application ID or Client ID
  additionalinfo: See the Help tab.
  name: credentials_auth_id
  hiddenusername: true
  section: Connect
  type: 9
  required: false
- display: Token or Tenant ID
  additionalinfo: See the Help tab.
  name: refresh_token
  type: 4
  section: Connect
  hidden: true
  required: false
- displaypassword: Token or Tenant ID
  additionalinfo: See the Help tab.
  name: credentials_refresh_token
  hiddenusername: true
  type: 9
  section: Connect
  required: false
- display: Key or Client Secret
  additionalinfo: See the Help tab.
  name: enc_key
  type: 4
  section: Connect
  hidden: true
  required: false
- displaypassword: Key or Client Secret
  additionalinfo: See the Help tab.
  name: credentials_enc_key
  hiddenusername: true
  type: 9
  section: Connect
  required: false
- additionalinfo: Used for certificate authentication as it appears in the "Certificates & secrets" page of the app.
  display: Certificate Thumbprint
  name: certificate_thumbprint
  type: 4
  hidden: true
  section: Connect
  required: false
- displaypassword: Certificate Thumbprint
  additionalinfo: Used for certificate authentication as it appears in the "Certificates & secrets" page of the app.
  name: credentials_certificate_thumbprint
  hiddenusername: true
  type: 9
  section: Connect
  required: false
- additionalinfo: Used for certificate authentication. The private key of the registered certificate.
  display: Private Key
  name: private_key
  type: 14
  section: Connect
  required: false
- additionalinfo: Select this checkbox if you are using a self-deployed Azure application.
  display: Use a self-deployed Azure application
  name: self_deployed
  type: 8
  section: Connect
  advanced: false
  required: false
- display: Application redirect URI (for self-deployed mode)
  name: redirect_uri
  type: 0
  section: Connect
  advanced: true
  required: false
- display: Authorization code (for self-deployed mode)
  additionalinfo: Run the !ms-management-activity-generate-login-url command to generate the Authorization code.
  name: auth_code
  type: 4
  section: Connect
  hidden: true
  required: false
- displaypassword: Authorization code (for self-deployed mode)
  additionalinfo: Run the !ms-management-activity-generate-login-url command to generate the Authorization code.
  name: credentials_auth_code
  hiddenusername: true
  type: 9
  required: false
  section: Connect
- additionalinfo: Relevant only if the integration is running on Azure VM. If selected, authenticates based on the value provided for the Azure Managed Identities Client ID field. If no value is provided for the Azure Managed Identities Client ID field, authenticates based on the System Assigned Managed Identity. For additional information, see the Help tab.
  display: Use Azure Managed Identities
  name: use_managed_identities
  type: 8
  section: Connect
  required: false
- additionalinfo: The Managed Identities client ID for authentication - relevant only if the integration is running on Azure VM.
  displaypassword: Azure Managed Identities Client ID
  name: managed_identities_client_id
  hiddenusername: true
  type: 9
  section: Connect
  required: false
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  section: Connect
  advanced: true
  required: false
- display: Use system proxy settings
  name: proxy
  type: 8
  section: Connect
  advanced: true
  required: false
- defaultvalue: 10 minutes
  display: First fetch time range
  additionalinfo: <number> <time unit>, for example 1 hour, 30 minutes
  name: first_fetch_delta
  type: 0
  section: Collect
  required: false
- additionalinfo: The default timeout (in seconds) for API calls. Default is 15 seconds.
  defaultvalue: 15
  display: Timeout
  name: timeout
  type: 0
  section: Connect
  advanced: true
  required: false
- display: Content types to fetch
  name: content_types_to_fetch
  options:
  - Audit.AzureActiveDirectory
  - Audit.Exchange
  - Audit.SharePoint
  - Audit.General
  - DLP.All
  section: Collect
  type: 16
  required: false
- display: Fetch incidents
  name: isFetch
  type: 8
  section: Collect
  required: false
  supportedModules:
  - agentix
  - xsiam
- display: Incident type
  name: incidentType
  type: 13
  section: Connect
  required: false
  supportedModules:
  - agentix
  - xsiam
- display: Incidents Fetch Interval
  name: incidentFetchInterval
  defaultvalue: '1'
  required: false
  type: 19
  section: Collect
  advanced: true
  supportedModules:
  - agentix
  - xsiam
- display: Record types to fetch
  additionalinfo: A comma-separated list of the record types you want to fetch. Content records with a record type that is not specified will not be fetched. If this field is left empty, all record types will be fetched.
  name: record_types_filter
  type: 0
  section: Collect
  advanced: true
  required: false
- display: Workloads to fetch
  additionalinfo: A comma-separated list of the workloads you want to fetch. Content records with a workload that is not specified will not be fetched. If this field is left empty, all workloads will be fetched.
  name: workloads_filter
  type: 0
  section: Collect
  advanced: true
  required: false
- display: Operations to fetch
  additionalinfo: "A comma-separated list of the operations you want to fetch. Content records with an operation that is not specified will not be fetched. If this field is left empty, all operations will be fetched. Important: This field is case-sensitive."
  name: operations_filter
  type: 0
  section: Collect
  advanced: true
  required: false
description: The Microsoft Management Activity API integration enables you to subscribe or unsubscribe to different audits, receive their content, and fetch new content as incidents.
display: Microsoft Management Activity API (O365 Azure Events)
name: Microsoft Management Activity API (O365 Azure Events)
script:
  commands:
  - arguments:
    - auto: PREDEFINED
      description: The content type to subscribe to.
      name: content_type
      predefined:
      - Audit.AzureActiveDirectory
      - Audit.Exchange
      - Audit.SharePoint
      - Audit.General
      - DLP.All
      required: true
    description: Starts a subscription to a given content type.
    name: ms-management-activity-start-subscription
  - arguments:
    - auto: PREDEFINED
      description: The content type to unsubscribe from.
      name: content_type
      predefined:
      - Audit.AzureActiveDirectory
      - Audit.Exchange
      - Audit.SharePoint
      - Audit.General
      - DLP.All
      required: true
    description: Stops a subscription to a given content type.
    name: ms-management-activity-stop-subscription
  - description: List the content types you are currently subscribed to.
    name: ms-management-activity-list-subscriptions
    outputs:
    - contextPath: MicrosoftManagement.Subscription
      description: List of current subscriptions.
      type: string
  - arguments:
    - auto: PREDEFINED
      description: The content type for which to receive content.
      name: content_type
      predefined:
      - Audit.AzureActiveDirectory
      - Audit.Exchange
      - Audit.SharePoint
      - Audit.General
      - DLP.All
      required: true
    - description: 'The 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.'
      name: start_time
    - description: 'The 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.'
      name: end_time
    - description: A 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.
      name: record_types_filter
    - description: A 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.
      name: workloads_filter
    - description: "A 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. Important: This field is case-sensitive."
      name: operations_filter
    - description: The timeout (in seconds) for the content requesting HTTP call. Default is the value provided as an integration parameter.
      name: timeout
    description: Returns all content of a specific content type.
    name: ms-management-activity-list-content
    outputs:
    - contextPath: MicrosoftManagement.ContentRecord.ID
      description: The ID of the record.
      type: number
    - contextPath: MicrosoftManagement.ContentRecord.CreationTime
      description: The creation time of the record.
      type: date
    - contextPath: MicrosoftManagement.ContentRecord.RecordType
      description: The type of the record.
      type: string
    - contextPath: MicrosoftManagement.ContentRecord.Operation
      description: The operation described in the record.
      type: string
    - contextPath: MicrosoftManagement.ContentRecord.UserType
      description: The type of the related user.
      type: string
    - contextPath: MicrosoftManagement.ContentRecord.OrganizationID
      description: The ID of the organization relevant to the record.
      type: number
    - contextPath: MicrosoftManagement.ContentRecord.UserKey
      description: The key of the related user.
      type: string
    - contextPath: MicrosoftManagement.ContentRecord.ClientIP
      description: The IP of the record's client.
      type: string
    - contextPath: MicrosoftManagement.ContentRecord.Scope
      description: The scope of the record.
      type: string
    - contextPath: MicrosoftManagement.ContentRecord.Workload
      description: The workload of the record.
      type: string
    - contextPath: MicrosoftManagement.ContentRecord.ResultsStatus
      description: The results status of the record.
      type: string
    - contextPath: MicrosoftManagement.ContentRecord.ObjectID
      description: The ID of the record's object.
      type: string
    - contextPath: MicrosoftManagement.ContentRecord.UserID
      description: The ID of the record's user.
      type: string
  - description: Generate the login url used for Authorization code flow.
    name: ms-management-activity-generate-login-url
    arguments: []
  - description: Run this command if for some reason you need to rerun the authentication process.
    name: ms-management-activity-auth-reset
    arguments: []
  dockerimage: demisto/auth-utils:1.0.0.10133006
  isfetch: true
  runonce: false
  script: '-'
  subtype: python3
  type: python
tests:
- No test
fromversion: 5.0.0