Microsoft Defender

Microsoft Defender integration allowing A-Ops to communicate with Microsoft Defender via the use of Microsoft graph API. This integration enables the retrieval of alerts, incidents as well as performing custom graph API requests which could even be used to create custom detection policies etc.

Actions

MS Defender Connect

Make an API connection using Microsoft Graph API that can be used to interact with MS Defender. This connection will be used for further API request with the actions listed further down within the documentation page.

Input

Name Description Type Required Syntax
Name Display name for the action object. input false false
Enabled Enable / Disable this action object. checkbox false false
Logic Logic that when defined must be evaluated as true for the action object to return True otherwise False will be returned. input false false
Variables Variables to define when triggering an event. var false true
Tenant ID Entra ID registered application tenant ID input true true
Client ID Entra ID registered application client ID input true true
refresh_token oAuth2 refresh token for the target delegate user password-input false true
client_secret oAuth2 client secret when using credential based access password-input false true
Scope Entra oAuth scope requirements input true true
Comment User defined comments. input false false

Output

Name Description Type always_present values
MSDefender_connection_id Returns the index of the connection created for use when more than one connections are active in a given flow. number True {"True": {"description": "Successful."}, "False": {"description": "Failure."}}
result Returns True when successful. boolean True {"True": {"description": "Successful."}, "False": {"description": "Failure."}}
rc Returns the exit code for the action. number True {"200": {"description": "Successful."}}

MS Defender Get Alerts

Execute a graph API request that retrieves alerts.

Input

Name Description Type Required Syntax
Name Display name for the action object. input false false
Enabled Enable / Disable this action object. checkbox false false
Logic Logic that when defined must be evaluated as true for the action object to return True otherwise False will be returned. input false false
Variables Variables to define when triggering an event. var false true
Connection ID Existing connection ID that was created when using the MSDefender Connect action input true true
Parameters Additional parameters based on graph API for MSDefender input false true
Comment User defined comments. input false false

Output

Name Description Type always_present values
rc Returns the status code returned by the HTTP server. number True {"0": {"description": "Successful."}}
response Returns the response body returned by the HTTP server. text True {"data": {"description": ""}}
result Returns True when successful. boolean True {"True": {"description": "Successful 2xx HTTP response code."}, "False": {"description": "Failure due to error or non 2xx HTTP response code."}}

MS Defender Get Incidents

Execute a graph API request that retreives incidents.

Input

Name Description Type Required Syntax
Name Display name for the action object. input false false
Enabled Enable / Disable this action object. checkbox false false
Logic Logic that when defined must be evaluated as true for the action object to return True otherwise False will be returned. input false false
Variables Variables to define when triggering an event. var false true
Connection ID Existing connection ID that was created when using the MSDefender Connect action input true true
Parameters Additional paremeters based on graph API for MSDefender input false true
Expand Alerts When enabled, the action retrieves both alerts and incidents group-checkbox false true
Comment User defined comments. input false false

Output

Name Description Type always_present values
rc Returns the status code returned by the HTTP server. number True {"0": {"description": "Successful."}}
response Returns the response body returned by the HTTP server. text True {"data": {"description": ""}}
result Returns True when successful. boolean True {"True": {"description": "Successful 2xx HTTP response code."}, "False": {"description": "Failure due to error or non 2xx HTTP response code."}}

MS Defender Get New Incidents

Execute a graph API request that retrieves new incidents.

Input

Name Description Type Required Syntax
Name Display name for the action object. input false false
Enabled Enable / Disable this action object. checkbox false false
Logic Logic that when defined must be evaluated as true for the action object to return True otherwise False will be returned. input false false
Variables Variables to define when triggering an event. var false true
Connection ID Existing connection ID that was created when using the MSDefender Connect action input true true
Last Event Point in time in which the object will retrieve incidents from. If left blank, the object will use current time. input false true
Expand Alerts When enabled, the action retrieves both alerts and incidents checkbox false true
Comment User defined comments. input false false

Output

Name Description Type always_present values
rc Returns the status code returned by the HTTP server. number True {"0": {"description": "Successful."}}
response Returns the response body returned by the HTTP server. text True {"data": {"description": ""}}
result Returns True when successful. boolean True {"True": {"description": "Successful 2xx HTTP response code."}, "False": {"description": "Failure due to error or non 2xx HTTP response code."}}

MS Defender Custom Request

Execute a custom graph API request.

Input

Name Description Type Required Syntax
Name Display name for the action object. input false false
Enabled Enable / Disable this action object. checkbox false false
Logic Logic that when defined must be evaluated as true for the action object to return True otherwise False will be returned. input false false
Variables Variables to define when triggering an event. var false true
Connection ID Existing connection ID that was created when using the MSDefender Connect action input true true
API Endpoint Target API endpoint when making a custom request input true true
method HTTP method to use when making a custom request dropdown true true
Data Any data to include in the API request. json-input false true
Comment User defined comments. input false false

Output

Name Description Type always_present values
rc Returns the status code returned by the HTTP server. number True {"0": {"description": "Successful."}}
response Returns the response body returned by the HTTP server. text True {"data": {"description": ""}}
result Returns True when successful. boolean True {"True": {"description": "Successful 2xx HTTP response code."}, "False": {"description": "Failure due to error or non 2xx HTTP response code."}}

Examples

Connect to MS Defender and retrieve new incidents and alerts

Example use of the Actions MS Defender Connect and MS Defender Get New Incidents

MS Defender Connect

MS Defender Get New Incidents

Download template

Requirements

  • Tenant ID
  • Client ID
  • Scope

Walkthrough

  1. Configure MS Defender Connect information
    • Tenant ID
    • Client ID
    • Scope

MS Defender Connect

  1. Configure Main tab
    • Enable Expand Alerts

MS Defender Get New Incidents