Fortinet Document Library

Version:


Table of Contents

Windows Defender ATP

1.0.0
Copy Link

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 isolate a specified machine from accessing an external network, retrieves a list of logged on users, and preventing a file from being executed in the organization.

Version information

Connector Version: 1.0.0

FortiSOAR™ Versions Tested on: 4.11.0-1161

Authored By: Fortinet

Certified: Yes

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-windows-defender-atp

For the detailed procedure to install a connector, click here.

Prerequisites to configuring the connector

  • You must have the Resource URL that will be used to validate the credentials (username-password pair) that is used to log onto Windows Defender ATP.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Windows Defender ATP connector row, and in the Configuration tab enter the required configuration details.

Parameter Description
Resource URL Resource URL that will be used to validate the credentials (username-password pair) that is used to log onto to Windows Defender ATP.
Username Username to login to Windows Defender ATP and perform automated operations.
Password Password to login to Windows Defender ATP and perform automated operations.
Client ID ID of the Azure application client.
Tenant ID ID of the Azure application tenant.
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 from FortiSOAR™ release 4.10.0 onwards:

Function Description Annotation and Category
Get Machines List Retrieves the collection of all recently seen machines or specific machine details, based on the machine ID you have specified, from Window Defender ATP. get_endpoints
Investigation
Find Machine Information By IP Searches for and retrieves information about a machine from Window Defender ATP, based on the timestamp and FQDN or IP address that you have specified. get_endpoints
Investigation
Get File-Machine Actions Collection Retrieves the collection of all file and machine actions or a specific object of file and machine actions, based on the object ID you have specified, from Window Defender ATP. get_file_machine_collection
Investigation
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
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
Get Machine Action Collection Retrieves the collection machine actions or a specific object of machine actions, based on the object ID you have specified, from Window Defender ATP. get_machine_collection
Investigation
Isolate Machine Isolates a specified machine, based on the machine ID you have specified, from accessing an external network. isolate_machine
Investigation
Remove Isolation Removes the Isolation of a specified machine, based on the machine ID you have specified. unisolate_machine
Investigation
Restrict Application Execution Restricts application execution on a specified machine, based on the machine ID you have specified. restrict_app
Investigation
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
Request Sample From Machine Requests a sample of a file from a specific machine, based on the machine ID you have specified. This operation also uploads the sample to a secure storage, based on the SHA1 of the file. collect_sample
Investigation
Run Antivirus Scan Initiates a Windows Defender Antivirus scan on a machine, based on the machine ID you have specified. run_antivirus
Investigation
Get Actor Information Retrieves the actor information report about a specific actor, based on the actor name or ID you have specified, from Window Defender ATP. get_actor
Investigation
Get Actor Related Alerts Retrieves alerts associated with the specified actor, based on the actor name or ID you have specified, from Window Defender ATP. get_alerts
Investigation
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
Block File Prevents a file, based on the SHA1 of the file that you have specified, from being executed in the organization. block_file
Investigation
Unblock File Allows a file, based on the SHA1 of the file that you have specified, to be executed in the organization. unblock_file
Investigation
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
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
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
Get File Actions Retrieves the collection of actions performed on files, from Window Defender ATP. get_file_collection
Investigation
Get Domain Related Alerts Retrieves the collection of alerts associated with the domain you have specified, from Window Defender ATP. get_alerts
Investigation
Get Domain Related Machines Retrieves the collection of machines associated with the domain you have specified, from Window Defender ATP. get_endpoints
Investigation
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
Is Domain Seen in Organisation Looks up or hunts for the specified domain in the organization, based on the domain name you have specified. domain_seen_organisation
Investigation
Get IP Related Alerts Retrieves the collection of alerts associated with the IP address you have specified, from Window Defender ATP. get_alerts
Investigation
Get IP Related Machines Retrieves the collection of machines associated with the IP address you have specified, from Window Defender ATP. get_endpoints
Investigation
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
Is IP Seen in Organisation Looks up or hunts for the specified IP in the organization, based on the IP address you have specified. ip_seen_organisation
Investigation
Get Alerts Retrieves details for the top recent alerts or alert details for a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_alerts
Investigation
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
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
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
Get Machines by Alert Retrieves machines that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_endpoints
Investigation
Get Actor by Alert Retrieves actors that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_actor
Investigation

operation: Get Machines List

Input parameters

Parameter Description
Machine ID (Optional) ID of the machine whose details you want to retrieve from Windows Defender ATP.
Note: If you do not specify any machine ID, then this operation will retrieve the collection of all recently seen machines 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 or FQDN within sixteen minutes before and after the timestamp.
FQDN/IP FQDN or 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 File-Machine Actions Collection

Input parameters

Parameter Description
Object ID (Optional) ID of the FileMachineAction object whose details you want to retrieve from Windows Defender ATP. You can generate a FileMachineAction object ID when you run Block file, Stop And Quarantine, and Request Sample from Machine actions.
Note: If you do not specify any FileMachineAction object ID, then this operation will retrieve the collection of all file and machine actions from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
     "value": [
         {
             "lastUpdateDateTimeUtc": "",
             "id": "",
             "requestorComment": "",
             "requestor": "",
             "creationDateTimeUtc": "",
             "status": "",
             "machineId": "",
             "fileInstances": [],
             "sha1": "",
             "type": ""
         }
     ],
     "@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: Get Machine Action Collection

Input parameters

Parameter Description
Object ID (Optional) ID of the MachineAction object whose details you want to retrieve from Windows Defender ATP. You can generate a MachineAction object ID when you run Restrict Apps and Run Antivirus Scan actions.
Note: If you do not specify any MachineAction object ID, then this operation will retrieve the collection of all machine actions from Windows Defender ATP.

Output

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

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: Request Sample From Machine

Input parameters

Parameter Description
Machine ID ID of the machine that contains the file whose sample you want to retrieve.
Filehash SHA1 of the file that you want to upload to the secure storage.
Comment Comment that you want to associate with requesting a file sample to be uploaded to the secure storage.

Output

The output contains the following populated JSON schema:
{
     "requestorComment": "",
     "requestor": "",
     "fileInstances": [
         {
             "status": "",
             "filePath": ""
         }
     ],
     "machineId": "",
     "sha1": "",
     "id": "",
     "creationDateTimeUtc": "",
     "fileId": "",
     "status": "",
     "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 Actor Information

Input parameters

Parameter Description
Actor ID or name of the actor for which you want to retrieve the actor information report from Windows Defender ATP.

Output

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

operation: Get Actor Related Alerts

Input parameters

Parameter Description
Actor ID or name of the actor whose associated alerts 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 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: Block File

Input parameters

Parameter Description
Filehash SHA1 of the file that you want to prevent from being executed in the organization.
Comment Comment that you want to associate with blocking a file using Windows Defender ATP.  

Output

The output contains the following populated JSON schema:
{
     "result": ""
}

operation: Unblock File

Input parameters

Parameter Description
Filehash SHA1 of the file whose execution you want to allow in the organization.
Comment Comment that you want to associate with unblocking a file using Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
     "result": ""
}

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 File Actions

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "fileIdentifierType": "",
             "actionType": "",
             "fileStatus": "",
             "creationDateTimeUtc": "",
             "requestor": "",
             "requestorComment": "",
             "cancellationDateTimeUtc": "",
             "cancellationRequestor": "",
             "cancellationComment": "",
             "lastUpdateDateTimeUtc": ""
         }
     ],
     "@odata.count": "", 
     "@odata.context": "" 
}

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: Is Domain Seen in Organisation

Input parameters

Parameter Description
Domain Name of the domain that you want to look up or hunt in the organization.

Output

The output contains the following populated JSON schema:

     "@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 Related Machines

Input parameters

Parameter Description
IP Address IP address 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": "",
             "id": "",
             "rbacGroupId": "",
             "isAadJoined": "",
             "computerDnsName": "",
             "lastIpAddress": "",
             "osBuild": "",
             "systemProductName": "",
             "osVersion": "",
             "agentVersion": "",
             "machineTags": [],
             "groupName": "",
             "osPlatform": ""
         }
     ],
     "@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: Is IP Seen in Organisation

Input parameters

Parameter Description
IP Address IP address that you want to look up or hunt in the organization.

Output

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

operation: Get Alerts

Input parameters

Parameter Description
Alert ID (Optional) ID of the alert whose details you want to retrieve from Windows Defender ATP.
Note: If you do not specify any alert ID, then this operation will retrieve the top recent alerts 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 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: Get Actors by Alert

Input parameters

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

Output

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

Included playbooks

The Sample - Windows Defender ATP - 1.0.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.

  • Block File
  • Find Machine Information By IP
  • Get Actor by Alert
  • Get Actor Information
  • Get Actor Related Alerts
  • Get Alerts
  • Get Domain Related Alerts
  • Get Domain Related Machines
  • Get Domains by Alert
  • Get Domain Statistics
  • Get File Actions
  • Get File Information
  • Get File-Machine Actions Collection
  • Get File Related Alerts
  • Get File Related Machines
  • Get Files by Alert
  • Get File Statistics
  • Get IP Related Alerts
  • Get IP Related Machines
  • Get IPs by Alert
  • Get IP Statistics
  • Get Machine Action Collection
  • Get Machine Logged on Users
  • Get Machines by Alert
  • Get Machines List
  • Is Domain Seen in Organization
  • Is IP Seen in Organization
  • Isolate Machine
  • Remove Application Restriction
  • Remove Isolation
  • Request Sample From Machine
  • Restrict Application Execution
  • Run Antivirus Scan
  • Unblock File

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 connector upgrade and delete.

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 isolate a specified machine from accessing an external network, retrieves a list of logged on users, and preventing a file from being executed in the organization.

Version information

Connector Version: 1.0.0

FortiSOAR™ Versions Tested on: 4.11.0-1161

Authored By: Fortinet

Certified: Yes

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-windows-defender-atp

For the detailed procedure to install a connector, click here.

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Windows Defender ATP connector row, and in the Configuration tab enter the required configuration details.

Parameter Description
Resource URL Resource URL that will be used to validate the credentials (username-password pair) that is used to log onto to Windows Defender ATP.
Username Username to login to Windows Defender ATP and perform automated operations.
Password Password to login to Windows Defender ATP and perform automated operations.
Client ID ID of the Azure application client.
Tenant ID ID of the Azure application tenant.
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 from FortiSOAR™ release 4.10.0 onwards:

Function Description Annotation and Category
Get Machines List Retrieves the collection of all recently seen machines or specific machine details, based on the machine ID you have specified, from Window Defender ATP. get_endpoints
Investigation
Find Machine Information By IP Searches for and retrieves information about a machine from Window Defender ATP, based on the timestamp and FQDN or IP address that you have specified. get_endpoints
Investigation
Get File-Machine Actions Collection Retrieves the collection of all file and machine actions or a specific object of file and machine actions, based on the object ID you have specified, from Window Defender ATP. get_file_machine_collection
Investigation
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
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
Get Machine Action Collection Retrieves the collection machine actions or a specific object of machine actions, based on the object ID you have specified, from Window Defender ATP. get_machine_collection
Investigation
Isolate Machine Isolates a specified machine, based on the machine ID you have specified, from accessing an external network. isolate_machine
Investigation
Remove Isolation Removes the Isolation of a specified machine, based on the machine ID you have specified. unisolate_machine
Investigation
Restrict Application Execution Restricts application execution on a specified machine, based on the machine ID you have specified. restrict_app
Investigation
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
Request Sample From Machine Requests a sample of a file from a specific machine, based on the machine ID you have specified. This operation also uploads the sample to a secure storage, based on the SHA1 of the file. collect_sample
Investigation
Run Antivirus Scan Initiates a Windows Defender Antivirus scan on a machine, based on the machine ID you have specified. run_antivirus
Investigation
Get Actor Information Retrieves the actor information report about a specific actor, based on the actor name or ID you have specified, from Window Defender ATP. get_actor
Investigation
Get Actor Related Alerts Retrieves alerts associated with the specified actor, based on the actor name or ID you have specified, from Window Defender ATP. get_alerts
Investigation
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
Block File Prevents a file, based on the SHA1 of the file that you have specified, from being executed in the organization. block_file
Investigation
Unblock File Allows a file, based on the SHA1 of the file that you have specified, to be executed in the organization. unblock_file
Investigation
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
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
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
Get File Actions Retrieves the collection of actions performed on files, from Window Defender ATP. get_file_collection
Investigation
Get Domain Related Alerts Retrieves the collection of alerts associated with the domain you have specified, from Window Defender ATP. get_alerts
Investigation
Get Domain Related Machines Retrieves the collection of machines associated with the domain you have specified, from Window Defender ATP. get_endpoints
Investigation
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
Is Domain Seen in Organisation Looks up or hunts for the specified domain in the organization, based on the domain name you have specified. domain_seen_organisation
Investigation
Get IP Related Alerts Retrieves the collection of alerts associated with the IP address you have specified, from Window Defender ATP. get_alerts
Investigation
Get IP Related Machines Retrieves the collection of machines associated with the IP address you have specified, from Window Defender ATP. get_endpoints
Investigation
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
Is IP Seen in Organisation Looks up or hunts for the specified IP in the organization, based on the IP address you have specified. ip_seen_organisation
Investigation
Get Alerts Retrieves details for the top recent alerts or alert details for a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_alerts
Investigation
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
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
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
Get Machines by Alert Retrieves machines that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_endpoints
Investigation
Get Actor by Alert Retrieves actors that are related to a specific alert, based on the alert ID you have specified, from Window Defender ATP. get_actor
Investigation

operation: Get Machines List

Input parameters

Parameter Description
Machine ID (Optional) ID of the machine whose details you want to retrieve from Windows Defender ATP.
Note: If you do not specify any machine ID, then this operation will retrieve the collection of all recently seen machines 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 or FQDN within sixteen minutes before and after the timestamp.
FQDN/IP FQDN or 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 File-Machine Actions Collection

Input parameters

Parameter Description
Object ID (Optional) ID of the FileMachineAction object whose details you want to retrieve from Windows Defender ATP. You can generate a FileMachineAction object ID when you run Block file, Stop And Quarantine, and Request Sample from Machine actions.
Note: If you do not specify any FileMachineAction object ID, then this operation will retrieve the collection of all file and machine actions from Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
     "value": [
         {
             "lastUpdateDateTimeUtc": "",
             "id": "",
             "requestorComment": "",
             "requestor": "",
             "creationDateTimeUtc": "",
             "status": "",
             "machineId": "",
             "fileInstances": [],
             "sha1": "",
             "type": ""
         }
     ],
     "@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: Get Machine Action Collection

Input parameters

Parameter Description
Object ID (Optional) ID of the MachineAction object whose details you want to retrieve from Windows Defender ATP. You can generate a MachineAction object ID when you run Restrict Apps and Run Antivirus Scan actions.
Note: If you do not specify any MachineAction object ID, then this operation will retrieve the collection of all machine actions from Windows Defender ATP.

Output

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

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: Request Sample From Machine

Input parameters

Parameter Description
Machine ID ID of the machine that contains the file whose sample you want to retrieve.
Filehash SHA1 of the file that you want to upload to the secure storage.
Comment Comment that you want to associate with requesting a file sample to be uploaded to the secure storage.

Output

The output contains the following populated JSON schema:
{
     "requestorComment": "",
     "requestor": "",
     "fileInstances": [
         {
             "status": "",
             "filePath": ""
         }
     ],
     "machineId": "",
     "sha1": "",
     "id": "",
     "creationDateTimeUtc": "",
     "fileId": "",
     "status": "",
     "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 Actor Information

Input parameters

Parameter Description
Actor ID or name of the actor for which you want to retrieve the actor information report from Windows Defender ATP.

Output

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

operation: Get Actor Related Alerts

Input parameters

Parameter Description
Actor ID or name of the actor whose associated alerts 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 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: Block File

Input parameters

Parameter Description
Filehash SHA1 of the file that you want to prevent from being executed in the organization.
Comment Comment that you want to associate with blocking a file using Windows Defender ATP.  

Output

The output contains the following populated JSON schema:
{
     "result": ""
}

operation: Unblock File

Input parameters

Parameter Description
Filehash SHA1 of the file whose execution you want to allow in the organization.
Comment Comment that you want to associate with unblocking a file using Windows Defender ATP.

Output

The output contains the following populated JSON schema:
{
     "result": ""
}

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 File Actions

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "@odata.context": "",
     "value": [
         {
             "fileIdentifierType": "",
             "actionType": "",
             "fileStatus": "",
             "creationDateTimeUtc": "",
             "requestor": "",
             "requestorComment": "",
             "cancellationDateTimeUtc": "",
             "cancellationRequestor": "",
             "cancellationComment": "",
             "lastUpdateDateTimeUtc": ""
         }
     ],
     "@odata.count": "", 
     "@odata.context": "" 
}

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: Is Domain Seen in Organisation

Input parameters

Parameter Description
Domain Name of the domain that you want to look up or hunt in the organization.

Output

The output contains the following populated JSON schema:

     "@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 Related Machines

Input parameters

Parameter Description
IP Address IP address 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": "",
             "id": "",
             "rbacGroupId": "",
             "isAadJoined": "",
             "computerDnsName": "",
             "lastIpAddress": "",
             "osBuild": "",
             "systemProductName": "",
             "osVersion": "",
             "agentVersion": "",
             "machineTags": [],
             "groupName": "",
             "osPlatform": ""
         }
     ],
     "@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: Is IP Seen in Organisation

Input parameters

Parameter Description
IP Address IP address that you want to look up or hunt in the organization.

Output

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

operation: Get Alerts

Input parameters

Parameter Description
Alert ID (Optional) ID of the alert whose details you want to retrieve from Windows Defender ATP.
Note: If you do not specify any alert ID, then this operation will retrieve the top recent alerts 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 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: Get Actors by Alert

Input parameters

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

Output

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

Included playbooks

The Sample - Windows Defender ATP - 1.0.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 connector upgrade and delete.