Fortinet black logo

Windows Defender ATP

Windows Defender ATP v2.1.0

2.1.0
Copy Link
Copy Doc ID 6d18d7c5-d62b-11ea-96b9-00505692583a:52

About the connector

Windows Defender Advanced Threat Protection (ATP) is a unified platform designed to help enterprise networks prevent, detect, investigate, and respond to advanced threats.

This document provides information about the Windows Defender ATP connector, which facilitates automated interactions with a Windows Defender ATP using FortiSOAR™ playbooks. Add the Windows Defender ATP connector as a step in FortiSOAR™ playbooks and perform automated operations, such as isolating a specified machine from accessing an external network, retrieving a list of logged-on users, and preventing a file from being executed in the organization.

You can use FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling alerts from Windows Defender ATP. For more information, see the Data Ingestion Support section.

Version information

Connector Version: 2.1.0

FortiSOAR™ Versions Tested on: 6.4.1-2133

Authored By: Fortinet.

Certified: Yes

Release Notes for version 2.1.0

Following enhancements have been made to the Windows Defender ATP connector in version 2.1.0:

  • Added the following new operations and playbooks:
    • Update Alert
    • Advanced Hunting
  • Updated the tags in the sample playbooks and also updated the name of the publisher of this connector.
  • Updated the data ingestion playbooks.
  • Added the "Create and Link Asset" playbook for linking assets to alerts.

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-windows-defender-atp

Prerequisites to configuring the connector

  • You must have your Service-based URI to which you will connect and perform the automated operations.
  • You must also have the Client ID and the Tenant ID of your Azure application.
  • Ensure that host login.microsoftonline.com on port 443 is whitelisted.

Important: You must also create an application with appropriate permissions that will access Microsoft Windows Defender ATP. For more information, see the "Create an app to access Microsoft Defender ATP without a user" article.

Minimum Permissions Required

To run all the connector actions, you need the following permissions:

Permission type Permission Permission display name
Application Machine.Read.All 'Read all machine profiles'
Application Machine.ReadWrite.All 'Read and write all machine information'
Application User.Read.All 'Read user profiles'
Application Alert.Read.All 'Read all alerts'
Application Alert.ReadWrite.All 'Read and write all alerts'
Application Machine.CollectForensics 'Collect forensics'
Application Machine.Isolate 'Isolate machine'
Application Machine.RestrictExecution 'Restrict code execution'
Application Machine.Scan 'Scan machine
Application Machine.Offboard 'Offboard machine'
Application File.Read.All 'Read all file profiles'
Application File.Read.All 'Read file profiles'
Application URL.Read.All 'Read URLs'
Application Ip.Read.All 'Read IP address profiles'
Application Ti.ReadWrite 'Read and write Indicators'
Application Ti.ReadWrite.All 'Read and write All Indicators'
Application AdvancedQuery.Read.All 'Run advanced queries'

Microsoft Source info: https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exposed-apis-list?view=o365-worldwide

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the Windows Defender ATP connector card. On the connector popup, click the Configurations tab to enter the required configuration details.

Parameter Description
Server URL Service-based URI to which you will connect and perform the automated operations.
For better performance, you can use a server that is close to your geographic location. You can use one of the following URIs:
  • api-us.securitycenter.windows.com
  • api-eu.securitycenter.windows.com
  • api-uk.securitycenter.windows.com
By default, this is set as api.securitycenter.windows.com
Client ID Client ID of the Azure application that is used to access Windows Defender ATP.
Client Secret Secret string that the application (used to access Windows Defender ATP) uses to prove its identity.
To get the secret key, see "Create an app to access Microsoft Defender ATP without a user" article.
Tenant ID Tenant ID of the Azure application.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations:

Function Description Annotation and Category Permissions Required*
Get Machines List Retrieves the collection of all recently seen machines or specific machines based on the search query and other input parameters that you have specified. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Find Machine Information By IP Searches for and retrieves information about a machine from Window Defender ATP, based on the requested internal IP in the time range of 15 minutes prior and after a given timestamp. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Get Machine Logged on Users Retrieves a list of users logged on a specified machine, based on the machine ID you have specified, from Window Defender ATP. get_logged_users
Investigation
  • User.Read.All
    Type: Application
    Display Name: 'Read user profiles'
Get Machine Alerts Retrieves the collection of alerts related to the specified machine, based on the machine ID you have specified, from Window Defender ATP. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Isolate Machine Isolates a specified machine, based on the machine ID you have specified, from accessing an external network. isolate_machine
Investigation
  • Machine.Isolate
    Type: Application
    Display Name: 'Isolate machine'
Remove Isolation Removes the Isolation of a specified machine, based on the machine ID you have specified. unisolate_machine
Investigation
  • Machine.Isolate
    Type: Application
    Display Name: 'Isolate machine'
Restrict Application Execution Restricts application execution on a specified machine, based on the machine ID you have specified. restrict_app
Investigation
  • Machine.RestrictExecution
    Type: Application
    Display Name: 'Restrict code execution'
Remove Application Restriction Removes the execution restriction of a set of predefined applications from a specified machine, based on the machine ID you have specified. remove_restriction
Investigation
  • Machine.RestrictExecution
    Type: Application
    Display Name: 'Restrict code execution'
Run Antivirus Scan Initiates a Windows Defender Antivirus scan on a machine, based on the machine ID you have specified. run_antivirus
Investigation
  • Machine.Scan
    Type: Application
    Display Name: 'Scan machine'
Get File Information Retrieves a file, based on the file identifier (SHA1, SHA256, or MD5) you have specified, from Window Defender ATP. get_file_info
Investigation
  • File.Read.All
    Type: Application
    Display Name: 'Read file profiles'
Get File Statistics Retrieves the prevalence (statistics) about a specific file, based on the SHA1 of the file you have specified, from Window Defender ATP. get_file_statistics
Investigation
  • File.Read.All
    Type: Application
    Display Name: 'Read file profiles'
Get File Related Machines Retrieves the collection of machines associated with the filehash (SHA1 only) you have specified, from Window Defender ATP. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Get File Related Alerts Retrieves the collection of alerts associated with the filehash (SHA1 only) you have specified, from Window Defender ATP. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Domain Related Alerts Retrieves the collection of alerts associated with the domain you have specified, from Window Defender ATP. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Domain Related Machines Retrieves the collection of machines associated with the domain you have specified, from Window Defender ATP. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Get Domain Statistics Retrieves the prevalence (statistics) about a specific domain, based on the domain name you have specified, from Window Defender ATP. get_domain_statistics
Investigation
  • URL.Read.All
    Type: Application
    Display Name: 'Read URLs'
Get IP Related Alerts Retrieves the collection of alerts associated with the IP address you have specified, from Window Defender ATP. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get IP Statistics Retrieves the prevalence (statistics) about a specific IP, based on the IP address you have specified, from Window Defender ATP. get_ip_statistics
Investigation
  • Ip.Read.All
    Type: Application
    Display Name: 'Read IP address profiles'
Get Alert By ID Retrieves details for a specific alert from Window Defender ATP, based on the alert ID you have specified. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Alert List Retrieves all alerts or specific alerts based on the search query and other input parameters that you have specified. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Domains by Alert Retrieves domains that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_domain
Investigation
  • URL.Read.All
    Type: Application
    Display Name: 'Read URLs'
Get Files by Alert Retrieves files that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_file
Investigation
  • File.Read.All
    Type: Application
    Display Name: 'Read file profiles'
Get IPs by Alert Retrieves IP addresses that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_ip
Investigation
  • Ip.Read.All
    Type: Application
    Display Name: 'Read IP address profiles'
Get Machines by Alert Retrieves machines that are related to a specific alert from Window Defender ATP, based on the alert ID you have specified. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Update Alert Updates properties such as the status, classification, etc. of a specific alert, based on the alert ID you have specified. update_alert
Investigation
  • Alerts.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Machine Action List Retrieves all collection actions done on machines or specific collection actions based on the search query and other input parameters that you have specified. get_machine_collection
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name:'Read and write all machine information'
Get Machine Action Retrieves details of the machine action object from Windows Defender ATP, based on the machine action object ID you have specified. get_machine_collection
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name:'Read and write all machine information'
Submit Indicator Submits or updates a new Indicator entity to Windows Defender ATP based on the indicator value and type, expiration time, action, and other input parameters you have specified. submit_indicator
Investigation
  • Ti.ReadWrite
    Type: Application
    Display Name: 'Read and write indicators'
  • Ti.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all indicators'
Get Indicator List Retrieves a collection of all TI (Threat Intelligence) indicators or specific TI based on the search query and other input parameters that you have specified. get_indicators
Investigation
  • Ti.ReadWrite
    Type: Application
    Display Name: 'Read and write indicators'
  • Ti.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all indicators'
Delete Indicator Deletes an indicator entity from Windows Defender ATP based on the indicator ID you have specified. delete_indicator
Investigation
  • Ti.ReadWrite
    Type: Application
    Display Name: 'Read and write TI indicators'
  • Ti.ReadWrite.All
    Type: Application
    Display Name: 'Read and write indicators'
Collect Investigation Package Initiates forensics collection on a specific machine based on the machine ID you have specified. collect_investigation_package
Investigation
  • Machine.CollectForensics
    Type: Application
    Display Name: 'Collect forensics'
Offboard Machine Offboards a machine from Windows Defender ATP, based on the machine ID you have specified. restrict_app
Investigation
  • Machine.Offboard
    Type: Application
    Display Name: 'Offboard machine'
Get Package SAS URI Retrieves a URI from Windows Defender ATP that allows downloading of an investigation package, based on the machine action ID you have specified. download_investigation_package
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name:'Read and write all machine information'
Get Machine by ID Retrieves the details of a specific machine from Windows Defender ATP, based on the machine ID you have specified. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Advanced Hunting Advanced hunting lets you explore raw data from Windows Defender ATP, for the last 30 days, based on the custom query you have specified. Using this operation, you can proactively inspect events in your network to locate interesting indicators and entities. advanced_hunting
Investigation
  • AdvancedQuery.Read.All
    Type: Application
    Display Name: 'Run advanced queries'

* Microsoft Source info: https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exposed-apis-list?view=o365-worldwide

operation: Get Machines List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Search Query Query using which you want to search for machines in Windows Defender ATP. The OData's filter query is supported on: "Id", "ComputerDnsName", "LastSeen", "LastIpAddress", "HealthStatus", "OsPlatform", "RiskScore", "MachineTags" and "RbacGroupId". For example, [machineTags/any(tag: tag eq 'ExampleTag')] gets all the machines with the tag 'ExampleTag'.
Number of Machines to Fetch Maximum number of machines that this operation should return from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"osPlatform": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"firstSeen": "",
"isAadJoined": "",
"rbacGroupId": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"systemProductName": "",
"osVersion": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"id": ""
}
],
"@odata.context": "",
"@odata.count": ""
}

operation: Find Machine Information By IP

Input parameters

Parameter Description
Time Timestamp, based on which you want to find the machine entity in Windows Defender ATP. The timestamp that you specify must be within the last 30 days.

The response of this operation will return a list of all machines that had reported the specified IP address 15 minutes before and after the timestamp.

FQDN/IP IP address that you want to lookup on Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"osPlatform": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"firstSeen": "",
"isAadJoined": "",
"rbacGroupId": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"systemProductName": "",
"osVersion": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"id": ""
}
],
"@odata.context": ""
}

operation: Get Machine Logged on Users

Input parameters

Parameter Description
Machine ID ID of the machine whose logged on users' list you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"accountDomainName": "",
"mostPrevalentMachineId": "",
"firstSeen": "",
"leastPrevalentMachineId": "",
"id": "",
"logonTypes": "",
"isDomainAdmin": "",
"accountName": "",
"accountSid": "",
"logOnMachinesCount": "",
"isOnlyNetworkUser": "",
"lastSeen": ""
}
],
"@odata.context": ""
}

operation: Get Machine Alerts

Input parameters

Parameter Description
Machine ID ID of the machine whose related alerts collection you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"recommendedAction": "",
"severity": "",
"category": "",
"resolvedTime": "",
"alertCreationTime": "",
"determination": "",
"id": "",
"title": "",
"classification": "",
"description": "",
"firstEventTime": "",
"status": "",
"assignedTo": "",
"lastEventTime": "",
"threatFamilyName": "",
"detectionSource": ""
}
],
"@odata.context": "",
"@odata.count": ""
}

operation: Isolate Machine

Input parameters

Parameter Description
Machine ID ID of the machine that you want to isolate.
Comment Comment that you want to associate with isolating the machine.
Isolation Type Type of isolation that you want to apply to the specified machine. You can choose one of the following:
Full: Complete isolation, i.e., the specified machine cannot access the external network.
Selective: Restricts only a limited set of applications present on the specified machine from accessing the network.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"error": "",
"status": "",
"creationDateTimeUtc": "",
"machineId": "",
"lastUpdateDateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Remove Isolation

Input parameters

Parameter Description
Machine ID ID of the machine that you want to unisolate, i.e., whose isolation you want to remove.
Comment Comment that you want to associate with unisolating the machine.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"error": "",
"status": "",
"creationDateTimeUtc": "",
"machineId": "",
"lastUpdateDateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Restrict Application Execution

Input parameters

Parameter Description
Machine ID ID of the machine on which you want to restrict application execution.
Comment Comment that you want to associate with restricting application execution.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"creationDateTimeUtc": "",
"status": "",
"machineId": "",
"error": "",
"lastUpdateDateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Remove Application Restriction

Input parameters

Parameter Description
Machine ID ID of the machine from which remove the application execution restriction.
Comment Comment that you want to associate with removing the application execution restriction.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"creationDateTimeUtc": "",
"status": "",
"machineId": "",
"error": "",
"lastUpdateDateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Run Antivirus Scan

Input parameters

Parameter Description
Machine ID ID of the machine on which you want to initiate a Windows Defender Antivirus scan.
Comment Comment that you want to associate with initiating a Windows Defender Antivirus scan.
Scan Type Type of Windows Defender Antivirus scan that you want to initiate on the specified machine. You can choose one of the following:
Quick: Performs a quick scan on the specified machine.
Full: Performs a full scan on the specified machine.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"error": "",
"status": "",
"creationDateTimeUtc": "",
"machineId": "",
"lastUpdateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Get File Information

Input parameters

Parameter Description
Filehash SHA1, SHA256, or MD5D of the file that you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"filePublisher": "",
"signerHash": "",
"size": "",
"md5": "",
"isPeFile": "",
"globalLastObserved": "",
"globalFirstObserved": "",
"fileProductName": "",
"sha256": "",
"issuer": "",
"sha1": "",
"globalPrevalence": "",
"windowsDefenderAVThreatName": "",
"isValidCertificate": "",
"signer": "",
"@odata.context": "",
"fileType": ""
}

operation: Get File Statistics

Input parameters

Parameter Description
Filehash SHA1 of the file whose prevalence (statistics) you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"sha1": "",
"orgFirstSeen": "",
"orgPrevalence": "",
"orgLastSeen": "",
"topFileNames": [],
"@odata.context": ""
}

operation: Get File Related Machines

Input parameters

Parameter Description
Filehash SHA1 of the file whose related collection of machines you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"firstSeen": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"osPlatform": "",
"rbacGroupId": "",
"isAadJoined": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"systemProductName": "",
"osVersion": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"id": ""
}
],
"@odata.context": ""
}

operation: Get File Related Alerts

Input parameters

Parameter Description
Filehash SHA1 of the file whose related collection of alerts you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"recommendedAction": "",
"severity": "",
"category": "",
"resolvedTime": "",
"title": "",
"determination": "",
"id": "",
"alertCreationTime": "",
"classification": "",
"description": "",
"firstEventTime": "",
"status": "",
"assignedTo": "",
"lastEventTime": "",
"threatFamilyName": "",
"detectionSource": ""
}
],
"@odata.context": "",
"@odata.count": ""
}

operation: Get Domain Related Alerts

Input parameters

Parameter Description
Domain Name of the domain whose related collection of alerts you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"status": "",
"id": "",
"recommendedAction": "",
"description": "",
"severity": ""
}
],
"@odata.count": "",
"@odata.context": ""
}

operation: Get Domain Related Machines

Input parameters

Parameter Description
Domain Name of the domain whose related collection of machines you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"firstSeen": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"osPlatform": "",
"rbacGroupId": "",
"isAadJoined": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"systemProductName": "",
"osVersion": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"id": ""
}
],
"@odata.context": ""
}

operation: Get Domain Statistics

Input parameters

Parameter Description
Domain Name of the domain whose prevalence (statistics) you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"orgPrevalence": "",
"orgFirstSeen": "",
"orgLastSeen": "",
"@odata.context": "",
"host": ""
}

operation: Get IP Related Alerts

Input parameters

Parameter Description
IP Address IP address whose related collection of alerts you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"status": "",
"id": "",
"recommendedAction": "",
"description": "",
"severity": ""
}
],
"@odata.count": "",
"@odata.context": ""
}

operation: Get IP Statistics

Input parameters

Parameter Description
IP Address IP address whose prevalence (statistics) you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"orgLastSeen": "",
"ipAddress": "",
"orgFirstSeen": "",
"orgPrevalence": "",
"@odata.context": ""
}

operation: Get Alert By ID

Input parameters

Parameter Description
Alert ID ID of the alert whose details you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"resolvedTime": "",
"severity": "",
"alertCreationTime": "",
"recommendedAction": "",
"lastEventTime": "",
"classification": "",
"id": "",
"title": "",
"category": "",
"description": "",
"firstEventTime": "",
"status": "",
"assignedTo": "",
"determination": "",
"threatFamilyName": "",
"detectionSource": ""
}
],
"@odata.count": "",
"@odata.context": ""
}

operation: Get Alert List

Input parameters

Parameter Description
Search Query Query using which you want to search for alerts in Windows Defender ATP. The OData's filter query is supported on: "Id", "IncidentId", "AlertCreationTime", "Status", "Severity" and "Category".
For example, the [alertCreationTime gt 2019-09-22T00:00:00Z] query will retrieve all the alerts that created after 2019-09-22T00:00:00Z
Number of Alerts to Fetch Maximum number of alerts that this operation should return from Windows Defender ATP.

Include more Details of

Object of the alert for which you want to retrieve additional information. You can choose from the following options: Files, IPs, or Domains.
Note: If you do not select any option, the additional information will not get populated in the final result.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"incidentId": "",
"assignedTo": "",
"classification": "",
"severity": "",
"title": "",
"status": "",
"alertCreationTime": "",
"determination": "",
"description": "",
"threatFamilyName": "",
"investigationState": "",
"machineId": "",
"firstEventTime": "",
"resolvedTime": "",
"category": "",
"lastEventTime": "",
"detectionSource": "",
"id": ""
}
]
}

operation: Get Domains by Alert

Input parameters

Parameter Description
Alert ID ID of the alert whose related domains you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"host": ""
}
],
"@odata.context": ""
}

operation: Get Files by Alert

Input parameters

Parameter Description
Alert ID ID of the alert whose related files you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"filePublisher": "",
"size": "",
"md5": "",
"isPeFile": "",
"globalLastObserved": "",
"globalFirstObserved": "",
"signer": "",
"sha256": "",
"issuer": "",
"signerHash": "",
"sha1": "",
"fileType": "",
"windowsDefenderAVThreatName": "",
"isValidCertificate": "",
"fileProductName": "",
"globalPrevalence": ""
}
],
"@odata.context": ""
}

operation: Get IPs by Alert

Input parameters

Parameter Description
Alert ID ID of the alert whose related IP addresses you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"id": ""
}
],
"@odata.context": ""
}

operation: Get Machines by Alert

Input parameters

Parameter Description
Alert ID ID of the alert whose related machines you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"firstSeen": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"systemProductName": "",
"rbacGroupId": "",
"isAadJoined": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"id": "",
"osVersion": "",
"@odata.context": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"osPlatform": ""
}

operation: Update Alert

Input parameters

Parameter Description
Alert ID ID of the alert that you want to update in Windows Defender ATP.
Status (Optional) Status that you want to assign to the specified alert. You can choose from the following options: 'New', 'In Progress', or 'Resolved'.
Assigned To (Optional) Assignment, i.e., the person to whom you want to assign the specified alert.
Classification (Optional) Classification that you want to assign to the specified alert. You can choose from the following options: 'Unknown', 'False alert', or 'True alert'.
Determination (Optional) Determination that you want to assign to the specified alert. You can choose from the following options: Not Available', 'Apt', 'Malware', 'Security Personnel', 'Security Testing', 'Unwanted Software', or 'Other'.
Comment (Optional) Comment that you want to add to the alert that you want to update in Windows Defender ATP.

Output

The output contains a non-dictionary value.

operation: Get Machine Action List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Search Query Query using which you want to search for collection actions done on machines in Windows Defender ATP. The OData's filter query is supported on: "Id", "Status", "MachineId", "Type", "Requestor", and "CreationDateTimeUtc".
Number of Machine Actions to Fetch Maximum number of collection actions that this operation should return from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"type": "",
"lastUpdateDateTimeUtc": "",
"creationDateTimeUtc": "",
"machineId": "",
"scope": "",
"relatedFileInfo": "",
"cancellationComment": "",
"id": "",
"errorHResult": "",
"status": "",
"requestor": "",
"requestorComment": "",
"cancellationDateTimeUtc": "",
"cancellationRequestor": ""
}
]
}

operation: Get Machine Action

Input parameters

Parameter Description
Machine Action ID ID of the machine action object whose details you want to retrieve from Windows Defender ATP. You can generate a machine action object ID by running the "Restrict Apps" or "Run Antivirus Scan" operations.

Output

The output contains the following populated JSON schema:
{
"type": "",
"lastUpdateDateTimeUtc": "",
"creationDateTimeUtc": "",
"machineId": "",
"relatedFileInfo": "",
"cancellationComment": "",
"requestorComment": "",
"id": "",
"errorHResult": "",
"status": "",
"requestor": "",
"cancellationRequestor": "",
"@odata.context": "",
"cancellationDateTimeUtc": "",
"scope": ""
}

operation: Submit Indicator

Input parameters

Parameter Description
Indicator Value Indicator value or identity of the indicator entity that you want to submit to Windows Defender ATP.
Indicator Type Type of the indicator that you want to submit to Windows Defender ATP. You can choose from the following options: FileSha1, FileSha256, IpAddress, DomainName, or and Url.
Action Action that will be taken if the indicator is discovered in the organization. You can choose from the following options: Alert only, Alert and block, or Allowed.
Expiration Time Duration after which the indicator will expire in Windows Defender ATP.
Alert Title (Optional) Title of the alert associated with the indicator.
Alert Severity (Optional) Severity of the alert associated with the indicator. You can choose from the following options: Informational, Low, Medium, or High.
Description (Optional) Description of the indicator that you want to submit to Windows Defender ATP.
Recommended Actions (Optional) Recommended actions that get performed as a part of a response. For example, a recovery action that is performed if a certain event occurs.

Output

The output contains the following populated JSON schema:
{
"severity": "",
"rbacGroupNames": [],
"title": "",
"indicatorType": "",
"description": "",
"createdBy": "",
"expirationTime": "",
"indicatorValue": "",
"@odata.context": "",
"recommendedActions": "",
"creationTimeDateTimeUtc": "",
"action": ""
}

operation: Get Indicator List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Search Query Query using which you want to search for TI indicators in Windows Defender ATP. OData's filter query is supported.
For example, the query: [action eq 'AlertAndBlock'] retrieves all Indicators with the "AlertAndBlock" action.
Number of Indicators to Fetch Maximum number of indicators that this operation should return from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"createdBy": "",
"expirationTime": "",
"indicatorValue": "",
"description": "",
"rbacGroupNames": [],
"severity": "",
"title": "",
"indicatorType": "",
"recommendedActions": "",
"creationTimeDateTimeUtc": "",
"action": ""
}
]
}

operation: Delete Indicator

Input parameters

Parameter Description
Indicator ID ID of the indicator that you want to delete from the Windows Defender ATP.

Output

The output contains a non-dictionary value.

operation: Collect Investigation Package

Input parameters

Parameter Description
Machine ID ID of the machine on which you want to initiate forensic collection.
Comment Comment that you want to associate with the action

Output

The output contains the following populated JSON schema:
{
"requestor": "",
"type": "",
"@odata.context": "",
"relatedFileInfo": "",
"lastUpdateTimeUtc": "",
"machineId": "",
"requestorComment": "",
"status": "",
"creationDateTimeUtc": "",
"id": ""
}

operation: Offboard Machine

Input parameters

Parameter Description
Machine ID ID of the machine that you want to offboard from Windows Defender ATP.
Comment Comment that you want to associate with the action.

Output

The output contains the following populated JSON schema:
{
"requestor": "",
"type": "",
"@odata.context": "",
"relatedFileInfo": "",
"lastUpdateTimeUtc": "",
"machineId": "",
"requestorComment": "",
"status": "",
"creationDateTimeUtc": "",
"id": ""
}

operation: Get Package SAS URI

Input parameters

Parameter Description
Machine Action ID ID of the machine action whose SAS URI you want so that you can download the investigation package from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": ""
}

operation: Get Machine by ID

Input parameters

Parameter Description
Machine ID ID of the machine whose details you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"rbacGroupId": "",
"firstSeen": "",
"agentVersion": "",
"riskScore": "",
"exposureLevel": "",
"computerDnsName": "",
"lastIpAddress": "",
"id": "",
"osBuild": "",
"version": "",
"aadDeviceId": "",
"osVersion": "",
"@odata.context": "",
"machineTags": [],
"lastSeen": "",
"healthStatus": "",
"rbacGroupName": "",
"osPlatform": "",
"lastExternalIpAddress": "",
"osProcessor": ""
}

operation: Advanced Hunting

Input parameters

Parameter Description
Query Custom query to identify and investigate breach activity in Windows Defender ATP. For more details, see https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-query-language.

Output

The output contains the following populated JSON schema:
{
"Schema": [
{
"Name": "",
"Type": ""
}
],
"Results": [
{
"Timestamp": "",
"FileName": "",
"InitiatingProcessFileName": "",
"DeviceId": ""
}
],
"Stats": {
"ExecutionTime": "",
"resource_usage": {
"cpu": {
"user": "",
"kernel": "",
"total cpu": ""
},
"cache": {
"disk": {
"hits": "",
"total": "",
"misses": ""
},
"memory": {
"hits": "",
"total": "",
"misses": ""
}
},
"memory": {
"peak_per_node": ""
}
},
"dataset_statistics": [
{
"table_size": "",
"table_row_count": ""
}
]
}
}

Included playbooks

The Sample - Windows Defender ATP - 2.1.0 playbook collection comes bundled with the Windows Defender ATP connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Windows Defender ATP connector.

  • Advanced Hunting
  • Collect Investigation Package
  • Create and Link Asset. This is a reference playbook that gets called when an alert has an asset; and it creates and links the asset to the particular alert.
  • Delete Indicator
  • Find Machine Information By IP
  • Get Alert By ID
  • Get Alert List
  • Get Domain Related Alerts
  • Get Domain Related Machines
  • Get Domains by Alert
  • Get Domain Statistics
  • Get File Information
  • Get File Related Alerts
  • Get File Related Machines
  • Get Files by Alert
  • Get File Statistics
  • Get Indicator List
  • Get IP Related Alerts
  • Get IPs by Alert
  • Get IP Statistics
  • Get Machine Action
  • Get Machine Action List
  • Get Machine Alerts
  • Get Machine by ID
  • Get Machine Logged on Users
  • Get Machines by Alert
  • Get Machines List
  • Get Package SAS URI
  • Isolate Machine
  • Offboard Machine
  • Remove Application Restriction
  • Remove Isolation
  • Restrict Application Execution
  • Run Antivirus Scan
  • Submit Indicator
  • Update Alert
  • > Windows Defender ATP > Create
  • > Windows Defender ATP > Fetch
  • >> Windows Defender ATP > Handle Macros
  • Windows Defender ATP > Ingest

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling alerts from Windows Defender ATP. Currently, "alerts" in Windows Defender ATP are mapped to "alerts" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.

Configure Data Ingestion

You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming Windows Defender ATP "Alerts" to FortiSOAR™ "Alerts".

The Data Ingestion Wizard enables you to configure scheduled pulling of data from Windows Defender ATP into FortiSOAR™. It also lets you pull some sample data from Windows Defender ATP using which you can define the mapping of data between Windows Defender ATP and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users mostly require to only map any custom fields that are added to the Windows Defender ATP alert.

  1. To begin configuring data ingestion, click Configure Data Ingestion on the Windows Defender ATP connector’s "Configurations" page.
    Click Let’s Start by fetching some data, to open the “Fetch Sample Data” screen.

    Sample data is required to create a field mapping between Windows Defender ATP data and FortiSOAR™. The sample data is pulled from connector actions or ingestion playbooks.
  2. On the Fetch Data screen, provide the configurations required to fetch Windows Defender ATP data.
    Users can choose to pull data from Windows Defender ATP specifying a search query using which you want to pull alerts from Windows Defender ATP. You can use the OData's Filter query to pull alerts from Windows Defender ATP. The OData's Filter query is supported on the "Id", "IncidentId", "AlertCreationTime", "Status", "Severity" and "Category" fields. You can also specify additional parameters such as the maximum number of alerts to be fetched, and the last X minutes in which the alerts have been updated in Windows Defender ATP. The fetched data is used to create a mapping between the Windows Defender ATP data and FortiSOAR™ alerts.

    Once you have completed specifying the configurations, click Fetch Data.
  3. On the Field Mapping screen, map the fields of a Windows Defender ATP alert to the fields of an alert present in FortiSOAR™.
    To map a field, click the key in the sample data to add the “jinja” value of the field. For example, to map the title parameter of a Windows Defender ATP alert to the Name parameter of a FortiSOAR™ alert, click the Name field and then click the title field to populate its keys:

    For more information on field mapping, see the Data Ingestion chapter in the "Connectors Guide" in the FortiSOAR™ product documentation.
    Once you have completed the mapping of fields, click Save Mapping & Continue.

  4. Use the Scheduling screen to configure schedule-based ingestion, i.e., specify the polling frequency to Windows Defender ATP, so that the content gets pulled from the Windows Defender ATP integration into FortiSOAR™.
    On the Scheduling screen, from the Do you want to schedule the ingestion? drop-down list, select Yes.
    In the “Configure Schedule Settings” section, specify the Cron expression for the schedule. For example, if you want to pull data from Windows Defender ATP every 5 minutes, click Every X Minute, and in the minute box enter */5. This would mean that based on the configuration you have set up, data, i.e., alerts will be pulled from Windows Defender ATP every 5 minutes.

    Once you have completed scheduling, click Save Settings & Continue.

  5. The Summary screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks. Click Done to complete the data ingestion and exit the Data Ingestion Wizard.

Troubleshooting Data Ingestion Issues

The Data Ingestion Wizard fails to launch

If you have installed version 2.1.0 of the Windows Defender ATP connector on FortiSOAR™ version 6.4.1, then the Data Ingestion Wizard does not work. This is because version 2.1.0 of the Windows Defender ATP connector has more than 30 sample playbooks and FortiSOAR™ has a UI limitation of being able to load only a maximum of 30 playbooks, causing the data ingestion wizard to fail. If you have upgraded your Windows Defender ATP connector, then this issue does not occur.

Resolution: You need to move a few sample playbooks out of the Windows Defender ATP folder into a different folder. Once the sample playbook count falls below 30, the Data Ingestion Wizard will work.

Important: This issue has been fixed in FortiSOAR™ version 6.4.3.

Previous
Next

About the connector

Windows Defender Advanced Threat Protection (ATP) is a unified platform designed to help enterprise networks prevent, detect, investigate, and respond to advanced threats.

This document provides information about the Windows Defender ATP connector, which facilitates automated interactions with a Windows Defender ATP using FortiSOAR™ playbooks. Add the Windows Defender ATP connector as a step in FortiSOAR™ playbooks and perform automated operations, such as isolating a specified machine from accessing an external network, retrieving a list of logged-on users, and preventing a file from being executed in the organization.

You can use FortiSOAR™'s Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling alerts from Windows Defender ATP. For more information, see the Data Ingestion Support section.

Version information

Connector Version: 2.1.0

FortiSOAR™ Versions Tested on: 6.4.1-2133

Authored By: Fortinet.

Certified: Yes

Release Notes for version 2.1.0

Following enhancements have been made to the Windows Defender ATP connector in version 2.1.0:

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-windows-defender-atp

Prerequisites to configuring the connector

Important: You must also create an application with appropriate permissions that will access Microsoft Windows Defender ATP. For more information, see the "Create an app to access Microsoft Defender ATP without a user" article.

Minimum Permissions Required

To run all the connector actions, you need the following permissions:

Permission type Permission Permission display name
Application Machine.Read.All 'Read all machine profiles'
Application Machine.ReadWrite.All 'Read and write all machine information'
Application User.Read.All 'Read user profiles'
Application Alert.Read.All 'Read all alerts'
Application Alert.ReadWrite.All 'Read and write all alerts'
Application Machine.CollectForensics 'Collect forensics'
Application Machine.Isolate 'Isolate machine'
Application Machine.RestrictExecution 'Restrict code execution'
Application Machine.Scan 'Scan machine
Application Machine.Offboard 'Offboard machine'
Application File.Read.All 'Read all file profiles'
Application File.Read.All 'Read file profiles'
Application URL.Read.All 'Read URLs'
Application Ip.Read.All 'Read IP address profiles'
Application Ti.ReadWrite 'Read and write Indicators'
Application Ti.ReadWrite.All 'Read and write All Indicators'
Application AdvancedQuery.Read.All 'Run advanced queries'

Microsoft Source info: https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exposed-apis-list?view=o365-worldwide

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the Windows Defender ATP connector card. On the connector popup, click the Configurations tab to enter the required configuration details.

Parameter Description
Server URL Service-based URI to which you will connect and perform the automated operations.
For better performance, you can use a server that is close to your geographic location. You can use one of the following URIs:
  • api-us.securitycenter.windows.com
  • api-eu.securitycenter.windows.com
  • api-uk.securitycenter.windows.com
By default, this is set as api.securitycenter.windows.com
Client ID Client ID of the Azure application that is used to access Windows Defender ATP.
Client Secret Secret string that the application (used to access Windows Defender ATP) uses to prove its identity.
To get the secret key, see "Create an app to access Microsoft Defender ATP without a user" article.
Tenant ID Tenant ID of the Azure application.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations:

Function Description Annotation and Category Permissions Required*
Get Machines List Retrieves the collection of all recently seen machines or specific machines based on the search query and other input parameters that you have specified. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Find Machine Information By IP Searches for and retrieves information about a machine from Window Defender ATP, based on the requested internal IP in the time range of 15 minutes prior and after a given timestamp. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Get Machine Logged on Users Retrieves a list of users logged on a specified machine, based on the machine ID you have specified, from Window Defender ATP. get_logged_users
Investigation
  • User.Read.All
    Type: Application
    Display Name: 'Read user profiles'
Get Machine Alerts Retrieves the collection of alerts related to the specified machine, based on the machine ID you have specified, from Window Defender ATP. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Isolate Machine Isolates a specified machine, based on the machine ID you have specified, from accessing an external network. isolate_machine
Investigation
  • Machine.Isolate
    Type: Application
    Display Name: 'Isolate machine'
Remove Isolation Removes the Isolation of a specified machine, based on the machine ID you have specified. unisolate_machine
Investigation
  • Machine.Isolate
    Type: Application
    Display Name: 'Isolate machine'
Restrict Application Execution Restricts application execution on a specified machine, based on the machine ID you have specified. restrict_app
Investigation
  • Machine.RestrictExecution
    Type: Application
    Display Name: 'Restrict code execution'
Remove Application Restriction Removes the execution restriction of a set of predefined applications from a specified machine, based on the machine ID you have specified. remove_restriction
Investigation
  • Machine.RestrictExecution
    Type: Application
    Display Name: 'Restrict code execution'
Run Antivirus Scan Initiates a Windows Defender Antivirus scan on a machine, based on the machine ID you have specified. run_antivirus
Investigation
  • Machine.Scan
    Type: Application
    Display Name: 'Scan machine'
Get File Information Retrieves a file, based on the file identifier (SHA1, SHA256, or MD5) you have specified, from Window Defender ATP. get_file_info
Investigation
  • File.Read.All
    Type: Application
    Display Name: 'Read file profiles'
Get File Statistics Retrieves the prevalence (statistics) about a specific file, based on the SHA1 of the file you have specified, from Window Defender ATP. get_file_statistics
Investigation
  • File.Read.All
    Type: Application
    Display Name: 'Read file profiles'
Get File Related Machines Retrieves the collection of machines associated with the filehash (SHA1 only) you have specified, from Window Defender ATP. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Get File Related Alerts Retrieves the collection of alerts associated with the filehash (SHA1 only) you have specified, from Window Defender ATP. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Domain Related Alerts Retrieves the collection of alerts associated with the domain you have specified, from Window Defender ATP. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Domain Related Machines Retrieves the collection of machines associated with the domain you have specified, from Window Defender ATP. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Get Domain Statistics Retrieves the prevalence (statistics) about a specific domain, based on the domain name you have specified, from Window Defender ATP. get_domain_statistics
Investigation
  • URL.Read.All
    Type: Application
    Display Name: 'Read URLs'
Get IP Related Alerts Retrieves the collection of alerts associated with the IP address you have specified, from Window Defender ATP. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get IP Statistics Retrieves the prevalence (statistics) about a specific IP, based on the IP address you have specified, from Window Defender ATP. get_ip_statistics
Investigation
  • Ip.Read.All
    Type: Application
    Display Name: 'Read IP address profiles'
Get Alert By ID Retrieves details for a specific alert from Window Defender ATP, based on the alert ID you have specified. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Alert List Retrieves all alerts or specific alerts based on the search query and other input parameters that you have specified. get_alerts
Investigation
  • Alert.Read.All
    Type: Application
    Display Name: 'Read all alerts'
  • Alert.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Domains by Alert Retrieves domains that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_domain
Investigation
  • URL.Read.All
    Type: Application
    Display Name: 'Read URLs'
Get Files by Alert Retrieves files that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_file
Investigation
  • File.Read.All
    Type: Application
    Display Name: 'Read file profiles'
Get IPs by Alert Retrieves IP addresses that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_ip
Investigation
  • Ip.Read.All
    Type: Application
    Display Name: 'Read IP address profiles'
Get Machines by Alert Retrieves machines that are related to a specific alert from Window Defender ATP, based on the alert ID you have specified. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Update Alert Updates properties such as the status, classification, etc. of a specific alert, based on the alert ID you have specified. update_alert
Investigation
  • Alerts.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all alerts'
Get Machine Action List Retrieves all collection actions done on machines or specific collection actions based on the search query and other input parameters that you have specified. get_machine_collection
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name:'Read and write all machine information'
Get Machine Action Retrieves details of the machine action object from Windows Defender ATP, based on the machine action object ID you have specified. get_machine_collection
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name:'Read and write all machine information'
Submit Indicator Submits or updates a new Indicator entity to Windows Defender ATP based on the indicator value and type, expiration time, action, and other input parameters you have specified. submit_indicator
Investigation
  • Ti.ReadWrite
    Type: Application
    Display Name: 'Read and write indicators'
  • Ti.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all indicators'
Get Indicator List Retrieves a collection of all TI (Threat Intelligence) indicators or specific TI based on the search query and other input parameters that you have specified. get_indicators
Investigation
  • Ti.ReadWrite
    Type: Application
    Display Name: 'Read and write indicators'
  • Ti.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all indicators'
Delete Indicator Deletes an indicator entity from Windows Defender ATP based on the indicator ID you have specified. delete_indicator
Investigation
  • Ti.ReadWrite
    Type: Application
    Display Name: 'Read and write TI indicators'
  • Ti.ReadWrite.All
    Type: Application
    Display Name: 'Read and write indicators'
Collect Investigation Package Initiates forensics collection on a specific machine based on the machine ID you have specified. collect_investigation_package
Investigation
  • Machine.CollectForensics
    Type: Application
    Display Name: 'Collect forensics'
Offboard Machine Offboards a machine from Windows Defender ATP, based on the machine ID you have specified. restrict_app
Investigation
  • Machine.Offboard
    Type: Application
    Display Name: 'Offboard machine'
Get Package SAS URI Retrieves a URI from Windows Defender ATP that allows downloading of an investigation package, based on the machine action ID you have specified. download_investigation_package
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name:'Read and write all machine information'
Get Machine by ID Retrieves the details of a specific machine from Windows Defender ATP, based on the machine ID you have specified. get_endpoints
Investigation
  • Machine.Read.All
    Type: Application
    Display Name: 'Read all machine profiles'
  • Machine.ReadWrite.All
    Type: Application
    Display Name: 'Read and write all machine information'
Advanced Hunting Advanced hunting lets you explore raw data from Windows Defender ATP, for the last 30 days, based on the custom query you have specified. Using this operation, you can proactively inspect events in your network to locate interesting indicators and entities. advanced_hunting
Investigation
  • AdvancedQuery.Read.All
    Type: Application
    Display Name: 'Run advanced queries'

* Microsoft Source info: https://docs.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exposed-apis-list?view=o365-worldwide

operation: Get Machines List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Search Query Query using which you want to search for machines in Windows Defender ATP. The OData's filter query is supported on: "Id", "ComputerDnsName", "LastSeen", "LastIpAddress", "HealthStatus", "OsPlatform", "RiskScore", "MachineTags" and "RbacGroupId". For example, [machineTags/any(tag: tag eq 'ExampleTag')] gets all the machines with the tag 'ExampleTag'.
Number of Machines to Fetch Maximum number of machines that this operation should return from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"osPlatform": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"firstSeen": "",
"isAadJoined": "",
"rbacGroupId": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"systemProductName": "",
"osVersion": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"id": ""
}
],
"@odata.context": "",
"@odata.count": ""
}

operation: Find Machine Information By IP

Input parameters

Parameter Description
Time Timestamp, based on which you want to find the machine entity in Windows Defender ATP. The timestamp that you specify must be within the last 30 days.

The response of this operation will return a list of all machines that had reported the specified IP address 15 minutes before and after the timestamp.

FQDN/IP IP address that you want to lookup on Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"osPlatform": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"firstSeen": "",
"isAadJoined": "",
"rbacGroupId": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"systemProductName": "",
"osVersion": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"id": ""
}
],
"@odata.context": ""
}

operation: Get Machine Logged on Users

Input parameters

Parameter Description
Machine ID ID of the machine whose logged on users' list you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"accountDomainName": "",
"mostPrevalentMachineId": "",
"firstSeen": "",
"leastPrevalentMachineId": "",
"id": "",
"logonTypes": "",
"isDomainAdmin": "",
"accountName": "",
"accountSid": "",
"logOnMachinesCount": "",
"isOnlyNetworkUser": "",
"lastSeen": ""
}
],
"@odata.context": ""
}

operation: Get Machine Alerts

Input parameters

Parameter Description
Machine ID ID of the machine whose related alerts collection you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"recommendedAction": "",
"severity": "",
"category": "",
"resolvedTime": "",
"alertCreationTime": "",
"determination": "",
"id": "",
"title": "",
"classification": "",
"description": "",
"firstEventTime": "",
"status": "",
"assignedTo": "",
"lastEventTime": "",
"threatFamilyName": "",
"detectionSource": ""
}
],
"@odata.context": "",
"@odata.count": ""
}

operation: Isolate Machine

Input parameters

Parameter Description
Machine ID ID of the machine that you want to isolate.
Comment Comment that you want to associate with isolating the machine.
Isolation Type Type of isolation that you want to apply to the specified machine. You can choose one of the following:
Full: Complete isolation, i.e., the specified machine cannot access the external network.
Selective: Restricts only a limited set of applications present on the specified machine from accessing the network.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"error": "",
"status": "",
"creationDateTimeUtc": "",
"machineId": "",
"lastUpdateDateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Remove Isolation

Input parameters

Parameter Description
Machine ID ID of the machine that you want to unisolate, i.e., whose isolation you want to remove.
Comment Comment that you want to associate with unisolating the machine.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"error": "",
"status": "",
"creationDateTimeUtc": "",
"machineId": "",
"lastUpdateDateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Restrict Application Execution

Input parameters

Parameter Description
Machine ID ID of the machine on which you want to restrict application execution.
Comment Comment that you want to associate with restricting application execution.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"creationDateTimeUtc": "",
"status": "",
"machineId": "",
"error": "",
"lastUpdateDateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Remove Application Restriction

Input parameters

Parameter Description
Machine ID ID of the machine from which remove the application execution restriction.
Comment Comment that you want to associate with removing the application execution restriction.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"creationDateTimeUtc": "",
"status": "",
"machineId": "",
"error": "",
"lastUpdateDateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Run Antivirus Scan

Input parameters

Parameter Description
Machine ID ID of the machine on which you want to initiate a Windows Defender Antivirus scan.
Comment Comment that you want to associate with initiating a Windows Defender Antivirus scan.
Scan Type Type of Windows Defender Antivirus scan that you want to initiate on the specified machine. You can choose one of the following:
Quick: Performs a quick scan on the specified machine.
Full: Performs a full scan on the specified machine.

Output

The output contains the following populated JSON schema:
{
"id": "",
"requestorComment": "",
"requestor": "",
"error": "",
"status": "",
"creationDateTimeUtc": "",
"machineId": "",
"lastUpdateTimeUtc": "",
"@odata.context": "",
"type": ""
}

operation: Get File Information

Input parameters

Parameter Description
Filehash SHA1, SHA256, or MD5D of the file that you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"filePublisher": "",
"signerHash": "",
"size": "",
"md5": "",
"isPeFile": "",
"globalLastObserved": "",
"globalFirstObserved": "",
"fileProductName": "",
"sha256": "",
"issuer": "",
"sha1": "",
"globalPrevalence": "",
"windowsDefenderAVThreatName": "",
"isValidCertificate": "",
"signer": "",
"@odata.context": "",
"fileType": ""
}

operation: Get File Statistics

Input parameters

Parameter Description
Filehash SHA1 of the file whose prevalence (statistics) you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"sha1": "",
"orgFirstSeen": "",
"orgPrevalence": "",
"orgLastSeen": "",
"topFileNames": [],
"@odata.context": ""
}

operation: Get File Related Machines

Input parameters

Parameter Description
Filehash SHA1 of the file whose related collection of machines you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"firstSeen": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"osPlatform": "",
"rbacGroupId": "",
"isAadJoined": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"systemProductName": "",
"osVersion": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"id": ""
}
],
"@odata.context": ""
}

operation: Get File Related Alerts

Input parameters

Parameter Description
Filehash SHA1 of the file whose related collection of alerts you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"recommendedAction": "",
"severity": "",
"category": "",
"resolvedTime": "",
"title": "",
"determination": "",
"id": "",
"alertCreationTime": "",
"classification": "",
"description": "",
"firstEventTime": "",
"status": "",
"assignedTo": "",
"lastEventTime": "",
"threatFamilyName": "",
"detectionSource": ""
}
],
"@odata.context": "",
"@odata.count": ""
}

operation: Get Domain Related Alerts

Input parameters

Parameter Description
Domain Name of the domain whose related collection of alerts you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"status": "",
"id": "",
"recommendedAction": "",
"description": "",
"severity": ""
}
],
"@odata.count": "",
"@odata.context": ""
}

operation: Get Domain Related Machines

Input parameters

Parameter Description
Domain Name of the domain whose related collection of machines you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"firstSeen": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"osPlatform": "",
"rbacGroupId": "",
"isAadJoined": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"systemProductName": "",
"osVersion": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"id": ""
}
],
"@odata.context": ""
}

operation: Get Domain Statistics

Input parameters

Parameter Description
Domain Name of the domain whose prevalence (statistics) you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"orgPrevalence": "",
"orgFirstSeen": "",
"orgLastSeen": "",
"@odata.context": "",
"host": ""
}

operation: Get IP Related Alerts

Input parameters

Parameter Description
IP Address IP address whose related collection of alerts you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"status": "",
"id": "",
"recommendedAction": "",
"description": "",
"severity": ""
}
],
"@odata.count": "",
"@odata.context": ""
}

operation: Get IP Statistics

Input parameters

Parameter Description
IP Address IP address whose prevalence (statistics) you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"orgLastSeen": "",
"ipAddress": "",
"orgFirstSeen": "",
"orgPrevalence": "",
"@odata.context": ""
}

operation: Get Alert By ID

Input parameters

Parameter Description
Alert ID ID of the alert whose details you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"resolvedTime": "",
"severity": "",
"alertCreationTime": "",
"recommendedAction": "",
"lastEventTime": "",
"classification": "",
"id": "",
"title": "",
"category": "",
"description": "",
"firstEventTime": "",
"status": "",
"assignedTo": "",
"determination": "",
"threatFamilyName": "",
"detectionSource": ""
}
],
"@odata.count": "",
"@odata.context": ""
}

operation: Get Alert List

Input parameters

Parameter Description
Search Query Query using which you want to search for alerts in Windows Defender ATP. The OData's filter query is supported on: "Id", "IncidentId", "AlertCreationTime", "Status", "Severity" and "Category".
For example, the [alertCreationTime gt 2019-09-22T00:00:00Z] query will retrieve all the alerts that created after 2019-09-22T00:00:00Z
Number of Alerts to Fetch Maximum number of alerts that this operation should return from Windows Defender ATP.

Include more Details of

Object of the alert for which you want to retrieve additional information. You can choose from the following options: Files, IPs, or Domains.
Note: If you do not select any option, the additional information will not get populated in the final result.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"incidentId": "",
"assignedTo": "",
"classification": "",
"severity": "",
"title": "",
"status": "",
"alertCreationTime": "",
"determination": "",
"description": "",
"threatFamilyName": "",
"investigationState": "",
"machineId": "",
"firstEventTime": "",
"resolvedTime": "",
"category": "",
"lastEventTime": "",
"detectionSource": "",
"id": ""
}
]
}

operation: Get Domains by Alert

Input parameters

Parameter Description
Alert ID ID of the alert whose related domains you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"host": ""
}
],
"@odata.context": ""
}

operation: Get Files by Alert

Input parameters

Parameter Description
Alert ID ID of the alert whose related files you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"filePublisher": "",
"size": "",
"md5": "",
"isPeFile": "",
"globalLastObserved": "",
"globalFirstObserved": "",
"signer": "",
"sha256": "",
"issuer": "",
"signerHash": "",
"sha1": "",
"fileType": "",
"windowsDefenderAVThreatName": "",
"isValidCertificate": "",
"fileProductName": "",
"globalPrevalence": ""
}
],
"@odata.context": ""
}

operation: Get IPs by Alert

Input parameters

Parameter Description
Alert ID ID of the alert whose related IP addresses you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"id": ""
}
],
"@odata.context": ""
}

operation: Get Machines by Alert

Input parameters

Parameter Description
Alert ID ID of the alert whose related machines you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"firstSeen": "",
"healthStatus": "",
"lastExternalIpAddress": "",
"systemProductName": "",
"rbacGroupId": "",
"isAadJoined": "",
"computerDnsName": "",
"lastIpAddress": "",
"osBuild": "",
"id": "",
"osVersion": "",
"@odata.context": "",
"agentVersion": "",
"machineTags": [],
"groupName": "",
"osPlatform": ""
}

operation: Update Alert

Input parameters

Parameter Description
Alert ID ID of the alert that you want to update in Windows Defender ATP.
Status (Optional) Status that you want to assign to the specified alert. You can choose from the following options: 'New', 'In Progress', or 'Resolved'.
Assigned To (Optional) Assignment, i.e., the person to whom you want to assign the specified alert.
Classification (Optional) Classification that you want to assign to the specified alert. You can choose from the following options: 'Unknown', 'False alert', or 'True alert'.
Determination (Optional) Determination that you want to assign to the specified alert. You can choose from the following options: Not Available', 'Apt', 'Malware', 'Security Personnel', 'Security Testing', 'Unwanted Software', or 'Other'.
Comment (Optional) Comment that you want to add to the alert that you want to update in Windows Defender ATP.

Output

The output contains a non-dictionary value.

operation: Get Machine Action List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Search Query Query using which you want to search for collection actions done on machines in Windows Defender ATP. The OData's filter query is supported on: "Id", "Status", "MachineId", "Type", "Requestor", and "CreationDateTimeUtc".
Number of Machine Actions to Fetch Maximum number of collection actions that this operation should return from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"type": "",
"lastUpdateDateTimeUtc": "",
"creationDateTimeUtc": "",
"machineId": "",
"scope": "",
"relatedFileInfo": "",
"cancellationComment": "",
"id": "",
"errorHResult": "",
"status": "",
"requestor": "",
"requestorComment": "",
"cancellationDateTimeUtc": "",
"cancellationRequestor": ""
}
]
}

operation: Get Machine Action

Input parameters

Parameter Description
Machine Action ID ID of the machine action object whose details you want to retrieve from Windows Defender ATP. You can generate a machine action object ID by running the "Restrict Apps" or "Run Antivirus Scan" operations.

Output

The output contains the following populated JSON schema:
{
"type": "",
"lastUpdateDateTimeUtc": "",
"creationDateTimeUtc": "",
"machineId": "",
"relatedFileInfo": "",
"cancellationComment": "",
"requestorComment": "",
"id": "",
"errorHResult": "",
"status": "",
"requestor": "",
"cancellationRequestor": "",
"@odata.context": "",
"cancellationDateTimeUtc": "",
"scope": ""
}

operation: Submit Indicator

Input parameters

Parameter Description
Indicator Value Indicator value or identity of the indicator entity that you want to submit to Windows Defender ATP.
Indicator Type Type of the indicator that you want to submit to Windows Defender ATP. You can choose from the following options: FileSha1, FileSha256, IpAddress, DomainName, or and Url.
Action Action that will be taken if the indicator is discovered in the organization. You can choose from the following options: Alert only, Alert and block, or Allowed.
Expiration Time Duration after which the indicator will expire in Windows Defender ATP.
Alert Title (Optional) Title of the alert associated with the indicator.
Alert Severity (Optional) Severity of the alert associated with the indicator. You can choose from the following options: Informational, Low, Medium, or High.
Description (Optional) Description of the indicator that you want to submit to Windows Defender ATP.
Recommended Actions (Optional) Recommended actions that get performed as a part of a response. For example, a recovery action that is performed if a certain event occurs.

Output

The output contains the following populated JSON schema:
{
"severity": "",
"rbacGroupNames": [],
"title": "",
"indicatorType": "",
"description": "",
"createdBy": "",
"expirationTime": "",
"indicatorValue": "",
"@odata.context": "",
"recommendedActions": "",
"creationTimeDateTimeUtc": "",
"action": ""
}

operation: Get Indicator List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Search Query Query using which you want to search for TI indicators in Windows Defender ATP. OData's filter query is supported.
For example, the query: [action eq 'AlertAndBlock'] retrieves all Indicators with the "AlertAndBlock" action.
Number of Indicators to Fetch Maximum number of indicators that this operation should return from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"createdBy": "",
"expirationTime": "",
"indicatorValue": "",
"description": "",
"rbacGroupNames": [],
"severity": "",
"title": "",
"indicatorType": "",
"recommendedActions": "",
"creationTimeDateTimeUtc": "",
"action": ""
}
]
}

operation: Delete Indicator

Input parameters

Parameter Description
Indicator ID ID of the indicator that you want to delete from the Windows Defender ATP.

Output

The output contains a non-dictionary value.

operation: Collect Investigation Package

Input parameters

Parameter Description
Machine ID ID of the machine on which you want to initiate forensic collection.
Comment Comment that you want to associate with the action

Output

The output contains the following populated JSON schema:
{
"requestor": "",
"type": "",
"@odata.context": "",
"relatedFileInfo": "",
"lastUpdateTimeUtc": "",
"machineId": "",
"requestorComment": "",
"status": "",
"creationDateTimeUtc": "",
"id": ""
}

operation: Offboard Machine

Input parameters

Parameter Description
Machine ID ID of the machine that you want to offboard from Windows Defender ATP.
Comment Comment that you want to associate with the action.

Output

The output contains the following populated JSON schema:
{
"requestor": "",
"type": "",
"@odata.context": "",
"relatedFileInfo": "",
"lastUpdateTimeUtc": "",
"machineId": "",
"requestorComment": "",
"status": "",
"creationDateTimeUtc": "",
"id": ""
}

operation: Get Package SAS URI

Input parameters

Parameter Description
Machine Action ID ID of the machine action whose SAS URI you want so that you can download the investigation package from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": ""
}

operation: Get Machine by ID

Input parameters

Parameter Description
Machine ID ID of the machine whose details you want to retrieve from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
"rbacGroupId": "",
"firstSeen": "",
"agentVersion": "",
"riskScore": "",
"exposureLevel": "",
"computerDnsName": "",
"lastIpAddress": "",
"id": "",
"osBuild": "",
"version": "",
"aadDeviceId": "",
"osVersion": "",
"@odata.context": "",
"machineTags": [],
"lastSeen": "",
"healthStatus": "",
"rbacGroupName": "",
"osPlatform": "",
"lastExternalIpAddress": "",
"osProcessor": ""
}

operation: Advanced Hunting

Input parameters

Parameter Description
Query Custom query to identify and investigate breach activity in Windows Defender ATP. For more details, see https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/advanced-hunting-query-language.

Output

The output contains the following populated JSON schema:
{
"Schema": [
{
"Name": "",
"Type": ""
}
],
"Results": [
{
"Timestamp": "",
"FileName": "",
"InitiatingProcessFileName": "",
"DeviceId": ""
}
],
"Stats": {
"ExecutionTime": "",
"resource_usage": {
"cpu": {
"user": "",
"kernel": "",
"total cpu": ""
},
"cache": {
"disk": {
"hits": "",
"total": "",
"misses": ""
},
"memory": {
"hits": "",
"total": "",
"misses": ""
}
},
"memory": {
"peak_per_node": ""
}
},
"dataset_statistics": [
{
"table_size": "",
"table_row_count": ""
}
]
}
}

Included playbooks

The Sample - Windows Defender ATP - 2.1.0 playbook collection comes bundled with the Windows Defender ATP connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Windows Defender ATP connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling alerts from Windows Defender ATP. Currently, "alerts" in Windows Defender ATP are mapped to "alerts" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.

Configure Data Ingestion

You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming Windows Defender ATP "Alerts" to FortiSOAR™ "Alerts".

The Data Ingestion Wizard enables you to configure scheduled pulling of data from Windows Defender ATP into FortiSOAR™. It also lets you pull some sample data from Windows Defender ATP using which you can define the mapping of data between Windows Defender ATP and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users mostly require to only map any custom fields that are added to the Windows Defender ATP alert.

  1. To begin configuring data ingestion, click Configure Data Ingestion on the Windows Defender ATP connector’s "Configurations" page.
    Click Let’s Start by fetching some data, to open the “Fetch Sample Data” screen.

    Sample data is required to create a field mapping between Windows Defender ATP data and FortiSOAR™. The sample data is pulled from connector actions or ingestion playbooks.
  2. On the Fetch Data screen, provide the configurations required to fetch Windows Defender ATP data.
    Users can choose to pull data from Windows Defender ATP specifying a search query using which you want to pull alerts from Windows Defender ATP. You can use the OData's Filter query to pull alerts from Windows Defender ATP. The OData's Filter query is supported on the "Id", "IncidentId", "AlertCreationTime", "Status", "Severity" and "Category" fields. You can also specify additional parameters such as the maximum number of alerts to be fetched, and the last X minutes in which the alerts have been updated in Windows Defender ATP. The fetched data is used to create a mapping between the Windows Defender ATP data and FortiSOAR™ alerts.

    Once you have completed specifying the configurations, click Fetch Data.
  3. On the Field Mapping screen, map the fields of a Windows Defender ATP alert to the fields of an alert present in FortiSOAR™.
    To map a field, click the key in the sample data to add the “jinja” value of the field. For example, to map the title parameter of a Windows Defender ATP alert to the Name parameter of a FortiSOAR™ alert, click the Name field and then click the title field to populate its keys:

    For more information on field mapping, see the Data Ingestion chapter in the "Connectors Guide" in the FortiSOAR™ product documentation.
    Once you have completed the mapping of fields, click Save Mapping & Continue.

  4. Use the Scheduling screen to configure schedule-based ingestion, i.e., specify the polling frequency to Windows Defender ATP, so that the content gets pulled from the Windows Defender ATP integration into FortiSOAR™.
    On the Scheduling screen, from the Do you want to schedule the ingestion? drop-down list, select Yes.
    In the “Configure Schedule Settings” section, specify the Cron expression for the schedule. For example, if you want to pull data from Windows Defender ATP every 5 minutes, click Every X Minute, and in the minute box enter */5. This would mean that based on the configuration you have set up, data, i.e., alerts will be pulled from Windows Defender ATP every 5 minutes.

    Once you have completed scheduling, click Save Settings & Continue.

  5. The Summary screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks. Click Done to complete the data ingestion and exit the Data Ingestion Wizard.

Troubleshooting Data Ingestion Issues

The Data Ingestion Wizard fails to launch

If you have installed version 2.1.0 of the Windows Defender ATP connector on FortiSOAR™ version 6.4.1, then the Data Ingestion Wizard does not work. This is because version 2.1.0 of the Windows Defender ATP connector has more than 30 sample playbooks and FortiSOAR™ has a UI limitation of being able to load only a maximum of 30 playbooks, causing the data ingestion wizard to fail. If you have upgraded your Windows Defender ATP connector, then this issue does not occur.

Resolution: You need to move a few sample playbooks out of the Windows Defender ATP folder into a different folder. Once the sample playbook count falls below 30, the Data Ingestion Wizard will work.

Important: This issue has been fixed in FortiSOAR™ version 6.4.3.

Previous
Next