Skip to main content

Microsoft 365 Defender (Beta)

This Integration is part of the Microsoft 365 Defender Pack.#

Supported versions

Supported Cortex XSOAR versions: 5.5.0 and later.

beta

This is a beta Integration, which lets you implement and test pre-release software. Since the integration is beta, it might contain bugs. Updates to the integration during the beta phase might include non-backward compatible features. We appreciate your feedback on the quality and usability of the integration to help us identify issues, fix them, and continually improve.

Microsoft 365 Defender is a unified pre- and post-breach enterprise defense suite that natively coordinates detection, prevention, investigation, and response across endpoints, identities, email, and applications to provide integrated protection against sophisticated attacks.

Authentication Using the Device Code Flow#

Use the device code flow to link Microsoft 365 Defender with Cortex XSOAR.

To connect to the Microsoft 365 Defender:

  1. Fill in the required parameters.
  2. Run the !microsoft-365-defender-auth-start command.
  3. Follow the instructions that appear.
  4. Run the !microsoft-365-defender-auth-complete command.

At the end of the process you'll see a message that you've logged in successfully.

Note: In case of a password change, the microsoft-365-defender-auth-reset command should be executed followed by the authentication process described above.

Cortex XSOAR App#

In order to use the Cortex XSOAR application, use the default application ID. 9093c354-630a-47f1-b087-6768eb9427e6

Self-Deployed Application - Device Code Flow#

To use a self-configured Azure application, you need to add a new Azure App Registration in the Azure Portal. For more details, follow Self Deployed Application - Device Code Flow.

Required Permissions#

The required API permissions are for the Microsoft Threat Protection app.

  • offline_access - Delegate
  • Incident.ReadWrite.All - Application
  • AdvancedHunting.Read.All - Application

Self-Deployed Application - Client Credentials Flow#

Follow these steps for a self-deployed configuration:

  1. 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 article steps 1-8.
  2. In the instance configuration, select the client-credentials checkbox.
  3. Enter your Client/Application ID in the Application ID parameter.
  4. Enter your Client Secret in the Client Secret parameter.
  5. Enter your Tenant ID in the Tenant ID parameter.

Required Permissions#

  • AdvancedHunting.Read.All - Application
  • Incident.ReadWrite.All - Application

Configure Microsoft 365 Defender on Cortex XSOAR#

  1. Navigate to Settings > Integrations > Servers & Services.

  2. Search for Microsoft 365 Defender.

  3. Click Add instance to create and configure a new integration instance.

    ParameterDescriptionRequired
    Application IDThe API key to use to connect.True
    Endpoint URIThe United States: api-us.security.microsoft.com
    Europe: api-eu.security.microsoft.com
    The United Kingdom: api-uk.security.microsoft.co
    True
    Use Client Credentials Authorization FlowUse a self-deployed Azure application and authenticate using the Client Credentials flow.False
    Tenant ID (for Client Credentials mode)Tenant IDFalse
    Client Secret (for Client Credentials mode)Encryption key given by the adminFalse
    First fetch timestamp (<number> <time unit>, e.g., 12 hours, 7 days)False
    Fetch incidents timeoutThe time limit in seconds for fetch incidents to run. Leave this empty to cancel the timeout limit.False
    Number of incidents for each fetch.Due to API limitations, the maximum is 100.False
    Incident typeFalse
    isFetchFetch incidentsFalse
    insecureTrust any certificate (not secure)False
    proxyUse system proxy settingsFalse
  4. Run the !microsoft-365-defender-auth-test command to validate the authentication process.

Commands#

You can execute these commands from the Cortex XSOAR 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.

microsoft-365-defender-auth-start#


Run this command to start the authorization process and follow the instructions in the command results. (for device-code mode)

Base Command#

microsoft-365-defender-auth-start

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Command Example#

!microsoft-365-defender-auth-start

Human Readable Output#

###Authorization instructions

  1. To sign in, use a web browser to open the page {URL} and enter the code {code} to authenticate.
  2. Run the !microsoft-365-defender-auth-complete command in the War Room.

microsoft-365-defender-auth-complete#


Run this command to complete the authorization process. Should be used after running the microsoft-365-defender-auth-start command. (for device-code mode)

Base Command#

microsoft-365-defender-auth-complete

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Command Example#

!microsoft-365-defender-auth-complete

Human Readable Output#

โœ… Authorization completed successfully.

microsoft-365-defender-auth-reset#


Run this command if you need to rerun the authentication process. (for device-code mode)

Base Command#

microsoft-365-defender-auth-reset

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Command Example#

!microsoft-365-defender-auth-reset

Human Readable Output#

Authorization was reset successfully. You can now run !microsoft-365-defender-auth-start and !microsoft-365-defender-auth-complete.

microsoft-365-defender-auth-test#


Tests the connectivity to the Azure SQL Management.

Base Command#

microsoft-365-defender-auth-test

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Command Example#

!microsoft-365-defender-auth-test

Human Readable Output#

โœ… Success!

microsoft-365-defender-incidents-list#


Get the most recent incidents.

Base Command#

microsoft-365-defender-incidents-list

Input#

Argument NameDescriptionRequired
statusCategorize incidents (as Active, Resolved, or Redirected). Possible values are: Active, Resolved, Redirected.Optional
assigned_toOwner of the incident.Optional
limitNumber of incidents in the list. Maximum is 100. Default is 100.Optional
offsetNumber of entries to skip.Optional
timeoutThe time limit in seconds for the http request to run. Default value is 30.Optional

Context Output#

PathTypeDescription
Microsoft365Defender.Incident.incidentIdNumberIncident's ID.
Microsoft365Defender.Incident.redirectIncidentIdUnknownOnly populated in case an incident is grouped together with another incident, as part of the incident processing logic.
Microsoft365Defender.Incident.incidentNameStringThe name of the incident.
Microsoft365Defender.Incident.createdTimeDateThe date and time (in UTC) the incident was created.
Microsoft365Defender.Incident.lastUpdateTimeDateThe date and time (in UTC) the incident was last updated.
Microsoft365Defender.Incident.assignedToStringOwner of the incident.
Microsoft365Defender.Incident.classificationStringSpecification of the incident. Possible values are: Unknown, FalsePositive, and TruePositive.
Microsoft365Defender.Incident.determinationStringThe determination of the incident. Possible values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, and Other.
Microsoft365Defender.Incident.statusStringThe current status of the incident. Possible values are: Active, Resolved, and Redirected.
Microsoft365Defender.Incident.severityStringSeverity of the incident. Possible values are: UnSpecified, Informational, Low, Medium, and High.
Microsoft365Defender.Incident.alertsUnknownList of alerts relevant for the incidents.

Command Example#

!ms-365-defender-incidents-list status=Active limit=10 assigned_to=user

Human Readable Output#

Incidents:#

Incident nameTagsSeverityIncident IDCategoriesImpacted entitiesActive alertsService sourcesDetection sourcesFirst activityLast activityStatusAssigned toClassificationDevice groups
Automated investigation started manually on one endpointtag1, tag2Informational263SuspiciousActivityuser5 / 12MicrosoftDefenderForEndpointAutomatedInvestigation2021-03-22T12:34:31.8123759Z2021-03-22T12:59:07.526847ZActiveemailUnknowncomputer
Impossible travel activity involving one userMedium264InitialAccessuser1 / 1MicrosoftCloudAppSecurityMCAS2021-04-05T06:56:06.833Z2021-04-05T15:34:25.736ZResolvedemailUnknown

microsoft-365-defender-incident-update#


Update incident with the given ID.

Base Command#

microsoft-365-defender-incident-update

Input#

Argument NameDescriptionRequired
statusCategorize incidents. Possible values are: Active, Resolved, and Redirected.Optional
assigned_toOwner of the incident.Optional
idIncident's ID.Required
classificationThe specification for the incident. Possible values are: Unknown, FalsePositive, and TruePositive.Optional
determinationDetermination of the incident. Possible values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, and Other.Optional
tagsA comma-separated list of custom tags associated with an incident. For example: tag1,tag2,tag3.Optional
timeoutThe time limit in seconds for the http request to run. Default value is 30Optional

Context Output#

PathTypeDescription
Microsoft365Defender.Incident.incidentIdNumberIncident's ID.
Microsoft365Defender.Incident.redirectIncidentIdUnknownOnly populated in case an incident is grouped together with another incident, as part of the incident processing logic.
Microsoft365Defender.Incident.incidentNameStringThe name of the incident.
Microsoft365Defender.Incident.createdTimeDateThe date and time (in UTC) the incident was created.
Microsoft365Defender.Incident.lastUpdateTimeDateThe date and time (in UTC) the incident was last updated.
Microsoft365Defender.Incident.assignedToStringOwner of the incident.
Microsoft365Defender.Incident.classificationStringSpecification of the incident. Possible values are: Unknown, FalsePositive, and TruePositive.
Microsoft365Defender.Incident.determinationStringThe determination of the incident. Possible values are: NotAvailable, Apt, Malware, SecurityPersonnel, SecurityTesting, UnwantedSoftware, and Other.
Microsoft365Defender.Incident.statusStringThe current status of the incident. Possible values are: Active, Resolved, and Redirected.
Microsoft365Defender.Incident.severityStringSeverity of the incident. Possible values are: UnSpecified, Informational, Low, Medium, and High.
Microsoft365Defender.Incident.alertsUnknownList of alerts relevant for the incidents.

Command Example#

!microsoft-365-defender-incident-update id=264 tags=test5

Human Readable Output#

Updated incident No. 263:#

Incident nameTagsSeverityIncident IDCategoriesImpacted entitiesActive alertsService sourcesDetection sourcesFirst activityLast activityStatusAssigned toClassificationDevice groups
Automated investigation started manually on one endpointtest5Informational263SuspiciousActivity10 / 12MicrosoftDefenderForEndpointAutomatedInvestigation2021-03-22T12:34:31.8123759Z2021-03-22T12:59:07.526847ZActiveUserUnknowncomputer

microsoft-365-defender-advanced-hunting#


Advanced hunting is a threat-hunting tool that uses specially constructed queries to examine the past 30 days of event data in Microsoft 365 Defender. Details on how to write queries you can find here.

Base Command#

microsoft-365-defender-advanced-hunting

Input#

Argument NameDescriptionRequired
queryAdvanced hunting query.Required
limitNumber of entries. Enter -1 for unlimited query. Default is 50.Required
timeoutThe time limit in seconds for the http request to run. Default is 30.Optional

Context Output#

PathTypeDescription
Microsoft365Defender.Hunt.queryStringThe query used, also acted as a key.
Microsoft365Defender.Hunt.results.UnknownThe results of the query.

Command Example#

!microsoft-365-defender-advanced-hunting query=AlertInfo

Human Readable Output#

Result of query: AlertInfo:#

TimestampAlertIdTitleCategorySeverityServiceSourceDetectionSourceAttackTechniques
2021-04-25T10:11:00ZalertIdeDiscovery search started or exportedInitialAccessMediumMicrosoft Defender for Office 365Microsoft Defender for Office 365