About the connector

Microsoft Defender For Endpoints is a unified platform designed to help enterprise networks prevent, detect, investigate, and respond to advanced threats.

This document provides information about the Microsoft Defender For Endpoints connector, which facilitates automated interactions with a Microsoft Defender For Endpoints using FortiSOAR™ playbooks. Add the Microsoft Defender For Endpoints 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 Microsoft Defender For Endpoints. For more information, see the Data Ingestion Support section.

NOTE: The Windows Defender ATP connector has been rebranded to the Microsoft Defender For Endpoints. For more information on earlier versions, see the Windows Defender ATP Connector document.

Version information

Connector Version: 3.0.0

FortiSOAR™ Versions Tested on: 7.3.0-2034

Authored By: Fortinet.

Certified: Yes

Release Notes for version 3.0.0

The following enhancements have been made to the Microsoft Defender For Endpoints connector in version 3.0.0:

• Windows Defender ATP connector has been rebranded to the Microsoft Defender For Endpoints connector.
• Added support for authorization using the 'On behalf of User - Delegated Permission'. Now both 'Without a User - Application Permission' and the 'On behalf of User - Delegated Permission' are supported for authorization.
• Updated the following input parameters for the 'Get Alert List' action as follows:
  • Added the following input parameters:
    • Status
    • Severity
    • Category
    • Incident ID
    • Alert Creation Time
      Also, updated the 'Search Query' parameter such that if users specify a query, then the operation ignores the other filter parameters.
  • The "Include more Details of" is renamed to "Include more Details of Evidence" and its field type is changed from a multi-select field to a checkbox.
• Updated the options for the "Classification" and "Determination" input parameters for the 'Update Alert' action.
• Updated the following input parameters for the 'Submit Indicator' action as follows:
  • The "Indicator Type" parameter's options are changed, i.e., the 'File Md5' and 'Certificate Thumbprint' options are added.
  • The "Action" parameter's options are changed, i.e., the 'Warn', 'Block', 'Audit' and 'Block and Remediate' options are added.
  • The "Alert Title" and "Description" parameters have been made mandatory.
  • The "Expiration Time" parameter has been made optional.
• Removed a python dependency package named 'adal'.
• Updated the names of the sample playbooks included for data ingestion and removed the '>> Microsoft Defender For Endpoints > Handle Macros' playbook.

Getting Access Tokens

You can get authentication tokens to access the security graph APIs using two methods:

• On behalf of the User – Delegate Permission. For more information see, Accessing Microsoft Defender For Endpoints on behalf of a user
• Without a User - Application Permission. For more information see, Accessing Microsoft Defender For Endpoint without a user

Getting Access Tokens using the On behalf of the User – Delegate Permission method

1. Ensure that the required permissions are granted for the registration of the application. Select API Permissions > Add permission > APIs my organization uses > WindowsDefenderATP.
   Note: The API Permission that should be granted to the registered application is mentioned in the Minimum permissions required for the 'Delegate-type' permission table.
2. The Redirect URL can be directed to any web application in which you want to receive responses from Azure AD. If you are unsure about what to set as a redirect URL, you can use https://localhost/myapp.
3. Copy the following URL and replace the TENANT_ID, CLIENT_ID, and REDIRECT_URI with your own tenant ID, client ID, and redirect URI: https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize?response_type=code&scope=offline_access https://api.security.microsoft.com/.default&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
4. Enter the above link with the replaced values and you will be prompted to grant permissions for your Azure Service Management. You will be automatically redirected to a link with the following structure: REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE
5. Enter the following details in the Connector Configuration dialog in your FortiSOAR instance:
   1. Copy the AUTH_CODE (without the "code=" prefix) and paste it in the 'Authorization Code' parameter.
   2. Enter your client ID in the 'Client ID' parameter field.
   3. Enter your client secret in the 'Client Secret' parameter field.
   4. Enter your tenant ID in the 'Tenant ID' parameter field.
   5. Enter your redirect URI in the 'Redirect URI' parameter field. By default, it is set to https://localhost/myapp.

Getting Access Tokens using the Without a User - Application Permission method

1. Ensure that the required permissions are granted for the registration of the application. Select API Permissions > Add permission > APIs my organization uses > WindowsDefenderATP.
   Note: The API Permission that should be granted to the registered application is mentioned in the Minimum permissions required for the 'Application-type' permission table.
2. Enter the following details in the Connector Configuration dialog in your FortiSOAR instance:
   1. Enter your client ID in the 'Client ID' parameter field.
   2. Enter your client secret in the 'Client Secret' parameter field.
   3. Enter your tenant ID in the 'Tenant ID' parameter field.

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.

Minimum Permissions Required

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

Minimum permissions required for the 'Application-type' permission

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

Minimum permissions required for the 'Delegate-type' permission

Permission	Permission display name
Machine.Read	'Read machine information'
Machine.ReadWrite	'Read and write machine information'
User.Read.All	'Read user profiles'
Alert.Read	'Read alerts'
Alert.ReadWrite	'Read and write alerts'
Machine.CollectForensics	'Collect forensics'
Machine.Isolate	'Isolate machine'
Machine.RestrictExecution	'Restrict code execution'
Machine.Scan	'Scan machine
Machine.Offboard	'Offboard machine'
File.Read	'Read file profiles'
URL.Read.All	'Read URLs'
Ip.Read.All	'Read IP address profiles'
Ti.ReadWrite	'Read and write Indicators'
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 Microsoft Defender For Endpoints connector card. On the connector popup, click the Configurations tab to enter the required configuration details:

Parameter	Description
Get Access Token	Select the method using which you will get authentication tokens used to access the security graph APIs. You can choose between On behalf of User – Delegate Permission or Without a User - Application Permission. For more information, see the Getting Access Tokens section.
Server URL	Service-based URI to which you will connect and perform the automated operations.
Directory (tenant) ID	The ID of the tenant that you have been provided for your Azure Active Directory instance.
Application (client ID)	Unique ID of the Azure Active Directory application that is used to create an authentication token required to access the API.
Application (client) Secret	Unique Client Secret of the Azure Active Directory application that is used to create an authentication token required to access the API
Authorization Code	(Only Applicable to On behalf of User – Delegate Permission) The authorization code that you acquired during the authorization step. For more information, see the Getting Access Tokens using the On behalf of the user – Delegate Permission method section.
Redirect URI	(Only Applicable to On behalf of User – Delegate Permission) The redirect_uri of your app, where authentication responses can be sent and received by your app. The redirect URL that you specify here must exactly match one of the redirect_uri's you have registered in your app registration portal.
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:

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	For Application-type permission: Machine.Read.All Machine.ReadWrite.All For Delegate-type permission: Machine.Read Machine.ReadWrite
Find Machine Information By IP	Searches for and retrieves information about a machine from Microsoft Defender For Endpoints, based on the requested internal IP in the time range of 15 minutes prior to and after a given timestamp.	get_endpoints Investigation	For Application-type permission: Machine.Read.All Machine.ReadWrite.All For Delegate-type permission: Machine.Read Machine.ReadWrite
Get Machine Logged on Users	Retrieves a list of users logged on a specified machine, based on the machine ID you have specified, from Microsoft Defender For Endpoints.	get_logged_users Investigation	For both Application-type and Delegate-type permissions: User.Read.All
Get Machine Alerts	Retrieves the collection of alerts related to the specified machine, based on the machine ID you have specified, from Microsoft Defender For Endpoints.	get_alerts Investigation	For Application-type permission: Alert.Read.All Alert.ReadWrite.All For Delegate-type permission: Alert.Read Alert.ReadWrite
Isolate Machine	Isolates a specified machine, based on the machine ID you have specified, from accessing an external network.	isolate_machine Investigation	For both Application-type and Delegate-type permissions: Machine.Isolate
Remove Isolation	Removes the Isolation of a specified machine, based on the machine ID you have specified.	unisolate_machine Investigation	For both Application-type and Delegate-type permissions: Machine.Isolate
Restrict Application Execution	Restricts application execution on a specified machine, based on the machine ID you have specified.	restrict_app Investigation	For both Application-type and Delegate-type permissions: Machine.RestrictExecution
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	For both Application-type and Delegate-type permissions: Machine.RestrictExecution
Run Antivirus Scan	Initiates a Microsoft Defender scan on a machine, based on the machine ID, comment, and scan type you have specified.	run_antivirus Investigation	For both Application-type and Delegate-type permissions: Machine.Scan
Get File Information	Retrieves a file, based on the file identifier (SHA1, SHA256, or MD5) you have specified, from Microsoft Defender For Endpoints.	get_file_info Investigation	For both Application-type and Delegate-type permissions: File.Read.All
Get File Statistics	Retrieves the prevalence (statistics) about a specific file, based on the SHA1 of the file you have specified, from Microsoft Defender For Endpoints.	get_file_statistics Investigation	For both Application-type and Delegate-type permissions: File.Read.All
Get File Related Machines	Retrieves the collection of machines associated with the filehash (SHA1 only) you have specified, from Microsoft Defender For Endpoints.	get_endpoints Investigation	For Application-type permission: Machine.Read.All Machine.ReadWrite.All For Delegate-type permission: Machine.Read Machine.ReadWrite
Get File Related Alerts	Retrieves the collection of alerts associated with the filehash (SHA1 only) you have specified, from Microsoft Defender For Endpoints.	get_alerts Investigation	For Application-type permission: Alert.Read.All Alert.ReadWrite.All For Delegate-type permission: Alert.Read Alert.ReadWrite
Get Domain Related Alerts	Retrieves the collection of alerts associated with the domain you have specified, from Microsoft Defender For Endpoints.	get_alerts Investigation	For Application-type permission: Alert.Read.All Alert.ReadWrite.All For Delegate-type permission: Alert.Read Alert.ReadWrite
Get Domain Related Machines	Retrieves the collection of machines associated with the domain you have specified, from Microsoft Defender For Endpoints.	get_endpoints Investigation	For Application-type permission: Machine.Read.All Machine.ReadWrite.All For Delegate-type permission: Machine.Read Machine.ReadWrite
Get Domain Statistics	Retrieves the prevalence (statistics) about a specific domain, based on the domain name you have specified, from Microsoft Defender For Endpoints.	get_domain_statistics Investigation	For both Application-type and Delegate-type permissions: URL.Read.All
Get IP Related Alerts	Retrieves the collection of alerts associated with the IP address you have specified, from Microsoft Defender For Endpoints.	get_alerts Investigation	For Application-type permission: Alert.Read.All Alert.ReadWrite.All For Delegate-type permission: Alert.Read Alert.ReadWrite
Get IP Statistics	Retrieves the prevalence (statistics) about a specific IP, based on the IP address you have specified, from Microsoft Defender For Endpoints.	get_ip_statistics Investigation	For both Application-type and Delegate-type permissions: Ip.Read.All
Get Alert By ID	Retrieves details for a specific alert from Microsoft Defender For Endpoints, based on the alert ID you have specified.	get_alerts Investigation	For Application-type permission: Alert.Read.All Alert.ReadWrite.All For Delegate-type permission: Alert.Read Alert.ReadWrite
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	For Application-type permission: Alert.Read.All Alert.ReadWrite.All For Delegate-type permission: Alert.Read Alert.ReadWrite
Get Domains by Alert	Retrieves domains that are related to a specific alert, based on the alert ID you have specified, from Microsoft Defender For Endpoints.	get_domain Investigation	For both Application-type and Delegate-type permissions: URL.Read.All
Get Files by Alert	Retrieves files that are related to a specific alert, based on the alert ID you have specified, from Microsoft Defender For Endpoints.	get_file Investigation	For both Application-type and Delegate-type permissions: File.Read.All
Get IPs by Alert	Retrieves IP addresses that are related to a specific alert, based on the alert ID you have specified, from Microsoft Defender For Endpoints.	get_ip Investigation	For both Application-type and Delegate-type permissions: Ip.Read.All
Get Machines by Alert	Retrieves machines that are related to a specific alert from Microsoft Defender For Endpoints, based on the alert ID you have specified.	get_endpoints Investigation	For Application-type permission: Machine.Read.All Machine.ReadWrite.All For Delegate-type permission: Machine.Read Machine.ReadWrite
Update Alert	Updates properties such as the status, classification, etc. of a specific alert, based on the alert ID, classification, status, and other input parameters you have specified.	update_alert Investigation	For Application-type permission: Alert.ReadWrite.All For Delegate-type permission: Alert.ReadWrite
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	For Application-type permission: Machine.Read.All Machine.ReadWrite.All For Delegate-type permission: Machine.Read Machine.ReadWrite
Get Machine Action	Retrieves details of the machine action object from Microsoft Defender For Endpoints, based on the machine action object ID you have specified.	get_machine_collection Investigation	For Application-type permission: Machine.Read.All Machine.ReadWrite.All For Delegate-type permission: Machine.Read Machine.ReadWrite
Submit Indicator	Submits or updates a new Indicator entity to Microsoft Defender For Endpoints based on the indicator value and type, expiration time, action, and other input parameters you have specified.	submit_indicator Investigation	For Application-type permission: Ti.ReadWrite Ti.ReadWrite.All For Delegate-type permission: Ti.ReadWrite
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	For Application-type permission: Ti.ReadWrite Ti.ReadWrite.All For Delegate-type permission: Ti.ReadWrite
Delete Indicator	Deletes an indicator entity from Microsoft Defender For Endpoints based on the indicator ID you have specified.	delete_indicator Investigation	For Application-type permission: Ti.ReadWrite Ti.ReadWrite.All For Delegate-type permission: Ti.ReadWrite
Collect Investigation Package	Initiates forensics collection on a specific machine based on the machine ID you have specified.	collect_investigation_package Investigation	For both Application-type and Delegate-type permissions: Machine.CollectForensics
Offboard Machine	Offboards a machine from Microsoft Defender For Endpoints, based on the machine ID you have specified.	restrict_app Investigation	For both Application-type and Delegate-type permissions: Machine.Offboard
Get Investigation Package SAS URI	Retrieves a URI from Microsoft Defender For Endpoints that allows downloading of an investigation package, based on the machine action ID you have specified.	download_investigation_package Investigation	For Application-type permission: Machine.Read.All Machine.ReadWrite.All For Delegate-type permission: Machine.Read Machine.ReadWrite
Get Machine by ID	Retrieves the details of a specific machine from Microsoft Defender For Endpoints, based on the machine ID you have specified.	get_endpoints Investigation	For Application-type permission: Machine.Read.All Machine.ReadWrite.All For Delegate-type permission: Machine.Read Machine.ReadWrite
Run Advanced Hunting Query	Advanced hunting lets you explore raw data from Microsoft Defender For Endpoints, 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	For Application-type permission: AdvancedQuery.Read.All For Delegate-type permission: AdvancedQuery.Read

* 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 Microsoft Defender For Endpoints. 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	The maximum number of machines that this operation should return from Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"id": "",
"mergedIntoMachineId": "",
"isPotentialDuplication": "",
"computerDnsName": "",
"firstSeen": "",
"lastSeen": "",
"osPlatform": "",
"osVersion": "",
"osProcessor": "",
"version": "",
"lastIpAddress": "",
"lastExternalIpAddress": "",
"agentVersion": "",
"osBuild": "",
"healthStatus": "",
"deviceValue": "",
"rbacGroupId": "",
"rbacGroupName": "",
"riskScore": "",
"exposureLevel": "",
"isAadJoined": "",
"aadDeviceId": "",
"machineTags": [],
"defenderAvStatus": "",
"onboardingStatus": "",
"osArchitecture": "",
"managedBy": "",
"managedByStatus": "",
"ipAddresses": [
{
"ipAddress": "",
"macAddress": "",
"type": "",
"operationalStatus": ""
}
],
"vmMetadata": ""
}
]
}

operation: Find Machine Information By IP

Input parameters

Parameter	Description
Time	Timestamp, based on which you want to find the machine entity in Microsoft Defender For Endpoints. 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	The IP address that you want to lookup on Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"id": "",
"mergedIntoMachineId": "",
"isPotentialDuplication": "",
"computerDnsName": "",
"firstSeen": "",
"lastSeen": "",
"osPlatform": "",
"osVersion": "",
"osProcessor": "",
"version": "",
"lastIpAddress": "",
"lastExternalIpAddress": "",
"agentVersion": "",
"osBuild": "",
"healthStatus": "",
"deviceValue": "",
"rbacGroupId": "",
"rbacGroupName": "",
"riskScore": "",
"exposureLevel": "",
"isAadJoined": "",
"aadDeviceId": "",
"machineTags": [],
"defenderAvStatus": "",
"onboardingStatus": "",
"osArchitecture": "",
"managedBy": "",
"managedByStatus": "",
"ipAddresses": [
{
"ipAddress": "",
"macAddress": "",
"type": "",
"operationalStatus": ""
}
],
"vmMetadata": ""
}
]
}

operation: Get Machine Logged on Users

Input parameters

Parameter	Description
Machine ID	The ID of the machine whose logged-on users' list you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get Machine Alerts

Input parameters

Parameter	Description
Machine ID	The ID of the machine whose related alerts collection you want to retrieve from Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.count": "",
"@odata.context": "",
"value": [
{
"id": "",
"incidentId": "",
"investigationId": "",
"assignedTo": "",
"severity": "",
"status": "",
"classification": "",
"determination": "",
"investigationState": "",
"detectionSource": "",
"detectorId": "",
"category": "",
"threatFamilyName": "",
"title": "",
"description": "",
"alertCreationTime": "",
"firstEventTime": "",
"lastEventTime": "",
"lastUpdateTime": "",
"resolvedTime": "",
"machineId": "",
"computerDnsName": "",
"rbacGroupName": "",
"aadTenantId": "",
"threatName": "",
"mitreTechniques": [],
"relatedUser": "",
"loggedOnUsers": [
{
"accountName": "",
"domainName": ""
}
],
"comments": [],
"evidence": [
{
"entityType": "",
"evidenceCreationTime": "",
"sha1": "",
"sha256": "",
"fileName": "",
"filePath": "",
"processId": "",
"processCommandLine": "",
"processCreationTime": "",
"parentProcessId": "",
"parentProcessCreationTime": "",
"parentProcessFileName": "",
"parentProcessFilePath": "",
"ipAddress": "",
"url": "",
"registryKey": "",
"registryHive": "",
"registryValueType": "",
"registryValue": "",
"registryValueName": "",
"accountName": "",
"domainName": "",
"userSid": "",
"aadUserId": "",
"userPrincipalName": "",
"detectionStatus": ""
}
],
"domains": []
}
]
}

operation: Isolate Machine

Input parameters

Parameter	Description
Machine ID	The ID of the machine that you want to isolate.
Comment	The 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:
{
"@odata.context": "",
"id": "",
"type": "",
"title": "",
"requestor": "",
"requestorComment": "",
"status": "",
"machineId": "",
"computerDnsName": "",
"creationDateTimeUtc": "",
"lastUpdateDateTimeUtc": "",
"cancellationRequestor": "",
"cancellationComment": "",
"cancellationDateTimeUtc": "",
"errorHResult": "",
"scope": "",
"externalId": "",
"requestSource": "",
"relatedFileInfo": "",
"commands": [],
"troubleshootInfo": ""
}

operation: Remove Isolation

Input parameters

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

Output

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

operation: Restrict Application Execution

Input parameters

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

Output

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

operation: Remove Application Restriction

Input parameters

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

Output

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

operation: Run Antivirus Scan

Input parameters

Parameter	Description
Machine ID	The ID of the machine on which you want to initiate a Microsoft Defender Antivirus scan.
Comment	The comment that you want to associate with initiating a Microsoft Defender Antivirus scan.
Scan Type	Type of Microsoft 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:
{
"@odata.context": "",
"id": "",
"type": "",
"title": "",
"requestor": "",
"requestorComment": "",
"status": "",
"machineId": "",
"computerDnsName": "",
"creationDateTimeUtc": "",
"lastUpdateDateTimeUtc": "",
"cancellationRequestor": "",
"cancellationComment": "",
"cancellationDateTimeUtc": "",
"errorHResult": "",
"scope": "",
"externalId": "",
"requestSource": "",
"relatedFileInfo": "",
"commands": [],
"troubleshootInfo": ""
}

operation: Get File Information

Input parameters

Parameter	Description
Filehash	SHA1, SHA256, or MD5D of the file that you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get File Statistics

Input parameters

Parameter	Description
Filehash	SHA1 of the file whose prevalence (statistics) you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get File Related Machines

Input parameters

Parameter	Description
Filehash	SHA1 of the file whose related collection of machines you want to retrieve from Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"id": "",
"mergedIntoMachineId": "",
"isPotentialDuplication": "",
"computerDnsName": "",
"firstSeen": "",
"lastSeen": "",
"osPlatform": "",
"osVersion": "",
"osProcessor": "",
"version": "",
"lastIpAddress": "",
"lastExternalIpAddress": "",
"agentVersion": "",
"osBuild": "",
"healthStatus": "",
"deviceValue": "",
"rbacGroupId": "",
"rbacGroupName": "",
"riskScore": "",
"exposureLevel": "",
"isAadJoined": "",
"aadDeviceId": "",
"machineTags": [],
"defenderAvStatus": "",
"onboardingStatus": "",
"osArchitecture": "",
"managedBy": "",
"managedByStatus": "",
"ipAddresses": [
{
"ipAddress": "",
"macAddress": "",
"type": "",
"operationalStatus": ""
}
],
"vmMetadata": ""
}
]
}

operation: Get File Related Alerts

Input parameters

Parameter	Description
Filehash	SHA1 of the file whose related collection of alerts you want to retrieve from Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.count": "",
"@odata.context": "",
"value": [
{
"id": "",
"incidentId": "",
"investigationId": "",
"assignedTo": "",
"severity": "",
"status": "",
"classification": "",
"determination": "",
"investigationState": "",
"detectionSource": "",
"detectorId": "",
"category": "",
"threatFamilyName": "",
"title": "",
"description": "",
"alertCreationTime": "",
"firstEventTime": "",
"lastEventTime": "",
"lastUpdateTime": "",
"resolvedTime": "",
"machineId": "",
"computerDnsName": "",
"rbacGroupName": "",
"aadTenantId": "",
"threatName": "",
"mitreTechniques": [],
"relatedUser": {
"userName": "",
"domainName": ""
},
"loggedOnUsers": [
{
"accountName": "",
"domainName": ""
}
],
"comments": [
{
"comment": "",
"createdBy": "",
"createdTime": ""
}
],
"evidence": [
{
"entityType": "",
"evidenceCreationTime": "",
"sha1": "",
"sha256": "",
"fileName": "",
"filePath": "",
"processId": "",
"processCommandLine": "",
"processCreationTime": "",
"parentProcessId": "",
"parentProcessCreationTime": "",
"parentProcessFileName": "",
"parentProcessFilePath": "",
"ipAddress": "",
"url": "",
"registryKey": "",
"registryHive": "",
"registryValueType": "",
"registryValue": "",
"registryValueName": "",
"accountName": "",
"domainName": "",
"userSid": "",
"aadUserId": "",
"userPrincipalName": "",
"detectionStatus": ""
}
],
"domains": []
}
]
}

operation: Get Domain Related Alerts

Input parameters

Parameter	Description
Domain	Name of the domain whose related collection of alerts you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get Domain Related Machines

Input parameters

Parameter	Description
Domain	Name of the domain whose related collection of machines you want to retrieve from Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"id": "",
"mergedIntoMachineId": "",
"isPotentialDuplication": "",
"computerDnsName": "",
"firstSeen": "",
"lastSeen": "",
"osPlatform": "",
"osVersion": "",
"osProcessor": "",
"version": "",
"lastIpAddress": "",
"lastExternalIpAddress": "",
"agentVersion": "",
"osBuild": "",
"healthStatus": "",
"deviceValue": "",
"rbacGroupId": "",
"rbacGroupName": "",
"riskScore": "",
"exposureLevel": "",
"isAadJoined": "",
"aadDeviceId": "",
"machineTags": [],
"defenderAvStatus": "",
"onboardingStatus": "",
"osArchitecture": "",
"managedBy": "",
"managedByStatus": "",
"ipAddresses": [
{
"ipAddress": "",
"macAddress": "",
"type": "",
"operationalStatus": ""
}
],
"vmMetadata": ""
}
]
}

operation: Get Domain Statistics

Input parameters

Parameter	Description
Domain	Name of the domain whose prevalence (statistics) you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get IP Related Alerts

Input parameters

Parameter	Description
IP Address	IP address whose related collection of alerts you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get IP Statistics

Input parameters

Parameter	Description
IP Address	IP address whose prevalence (statistics) you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get Alert By ID

Input parameters

Parameter	Description
Alert ID	The ID of the alert whose details you want to retrieve from Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"id": "",
"incidentId": "",
"investigationId": "",
"assignedTo": "",
"severity": "",
"status": "",
"classification": "",
"determination": "",
"investigationState": "",
"detectionSource": "",
"detectorId": "",
"category": "",
"threatFamilyName": "",
"title": "",
"description": "",
"alertCreationTime": "",
"firstEventTime": "",
"lastEventTime": "",
"lastUpdateTime": "",
"resolvedTime": "",
"machineId": "",
"computerDnsName": "",
"rbacGroupName": "",
"aadTenantId": "",
"threatName": "",
"mitreTechniques": [],
"relatedUser": {
"userName": "",
"domainName": ""
},
"loggedOnUsers": [
{
"accountName": "",
"domainName": ""
}
],
"comments": [
{
"comment": "",
"createdBy": "",
"createdTime": ""
}
],
"evidence": [
{
"entityType": "",
"evidenceCreationTime": "",
"sha1": "",
"sha256": "",
"fileName": "",
"filePath": "",
"processId": "",
"processCommandLine": "",
"processCreationTime": "",
"parentProcessId": "",
"parentProcessCreationTime": "",
"parentProcessFileName": "",
"parentProcessFilePath": "",
"ipAddress": "",
"url": "",
"registryKey": "",
"registryHive": "",
"registryValueType": "",
"registryValue": "",
"registryValueName": "",
"accountName": "",
"domainName": "",
"userSid": "",
"aadUserId": "",
"userPrincipalName": "",
"detectionStatus": ""
}
],
"domains": []
}

operation: Get Alert 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
Status	Select the current status of the alerts that you want to retrieve from Microsoft Defender For Endpoints. You can choose from the following options: 'Unknown', 'New', 'In progress', or 'Resolved'.
Severity	Select the severity of the alerts that you want to retrieve from Microsoft Defender For Endpoints. You can choose from the following options: 'Informational', 'Low', 'Medium', 'UnSpecified', or 'High'.
Category	Select the category of the alerts that you want to retrieve from Microsoft Defender For Endpoints. You can choose from the following options: 'Execution', 'Initial Access', 'Suspicious Activity', or 'Threat Management'.
Incident ID	Specify the Incident ID based on which you want to retrieve the alerts from Microsoft Defender For Endpoints.
Alert Creation Time	Select the time when the alerts were first created based on which you want to retrieve the alerts from Microsoft Defender For Endpoints.
Search Query	Query using which you want to search for alerts in Microsoft Defender For Endpoints. The OData's Filter query is supported on: 'alertCreationTime', 'lastUpdateTime', 'incidentId', 'InvestigationId', 'id', 'asssignedTo', 'detectionSource', 'lastEventTime', 'status', 'severity', 'category'. For example, the [alertCreationTime gt 2019-09-22T00:00:00Z] query retrieves all the alerts that were created after 2019-09-22T00:00:00Z NOTE: If you specify a 'Search Query', then all the other filter parameters are ignored.
Number of Alerts to Fetch	The maximum number of alerts that this operation should return from Microsoft Defender For Endpoints.
Include more Details of Evidence	Select this option to fetch additional information, such as associated IPs, Domains, Files, etc for the retrieved alerts.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"id": "",
"incidentId": "",
"investigationId": "",
"assignedTo": "",
"severity": "",
"status": "",
"classification": "",
"determination": "",
"investigationState": "",
"detectionSource": "",
"detectorId": "",
"category": "",
"threatFamilyName": "",
"title": "",
"description": "",
"alertCreationTime": "",
"firstEventTime": "",
"lastEventTime": "",
"lastUpdateTime": "",
"resolvedTime": "",
"machineId": "",
"computerDnsName": "",
"rbacGroupName": "",
"aadTenantId": "",
"threatName": "",
"mitreTechniques": [],
"relatedUser": "",
"loggedOnUsers": [
{
"accountName": "",
"domainName": ""
}
],
"comments": [],
"evidence": [
{
"entityType": "",
"evidenceCreationTime": "",
"sha1": "",
"sha256": "",
"fileName": "",
"filePath": "",
"processId": "",
"processCommandLine": "",
"processCreationTime": "",
"parentProcessId": "",
"parentProcessCreationTime": "",
"parentProcessFileName": "",
"parentProcessFilePath": "",
"ipAddress": "",
"url": "",
"registryKey": "",
"registryHive": "",
"registryValueType": "",
"registryValue": "",
"registryValueName": "",
"accountName": "",
"domainName": "",
"userSid": "",
"aadUserId": "",
"userPrincipalName": "",
"detectionStatus": ""
}
],
"domains": []
}
]
}

operation: Get Domains by Alert

Input parameters

Parameter	Description
Alert ID	The ID of the alert whose related domains you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get Files by Alert

Input parameters

Parameter	Description
Alert ID	The ID of the alert whose related files you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get IPs by Alert

Input parameters

Parameter	Description
Alert ID	The ID of the alert whose related IP addresses you want to retrieve from Microsoft Defender For Endpoints.

Output

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

operation: Get Machines by Alert

Input parameters

Parameter	Description
Alert ID	The ID of the alert whose related machines you want to retrieve from Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"id": "",
"mergedIntoMachineId": "",
"isPotentialDuplication": "",
"computerDnsName": "",
"firstSeen": "",
"lastSeen": "",
"osPlatform": "",
"osVersion": "",
"osProcessor": "",
"version": "",
"lastIpAddress": "",
"lastExternalIpAddress": "",
"agentVersion": "",
"osBuild": "",
"healthStatus": "",
"deviceValue": "",
"rbacGroupId": "",
"rbacGroupName": "",
"riskScore": "",
"exposureLevel": "",
"isAadJoined": "",
"aadDeviceId": "",
"machineTags": [],
"defenderAvStatus": "",
"onboardingStatus": "",
"osArchitecture": "",
"managedBy": "",
"managedByStatus": "",
"ipAddresses": [
{
"ipAddress": "",
"macAddress": "",
"type": "",
"operationalStatus": ""
}
],
"vmMetadata": ""
}

operation: Update Alert

Input parameters

Parameter	Description
Alert ID	The ID of the alert that you want to update in Microsoft Defender For Endpoints.
Classification	The classification that you want to assign to the specified alert. You can choose from the following options: 'TruePositive', 'Informational, expected activity', or 'FalsePositive'. 'TruePositive' specifies that the alert was a malicious activity. 'Informational, expected activity' specifies that the activity related to the alert was expected. For example, a security test. 'FalsePositive' specifies that the activity was non-malicious. Based on the selected "Classification", select the "Determination" that you want to assign to the specified alert. If you choose the "Classification" as 'TruePositive', then you can choose from the following "Determination" options: Multistage attack, Malicious user activity, Compromised account, Malware, Phishing, Unwanted software, or Other. If you choose the "Classification" as 'Informational, expected activity', then you can choose from the following Security test, Line-of-business-application, Confirmed activity, or Other. If you choose the "Classification" as 'FalsePositive', then you can choose from the following "Determination" options: Not malicious, Not enough data to validate, or Other.
Status	The 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.
Comment	(Optional) The comment that you want to add to the alert that you want to update in Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"id": "",
"incidentId": "",
"investigationId": "",
"assignedTo": "",
"severity": "",
"status": "",
"classification": "",
"determination": "",
"investigationState": "",
"detectionSource": "",
"detectorId": "",
"category": "",
"threatFamilyName": "",
"title": "",
"description": "",
"alertCreationTime": "",
"firstEventTime": "",
"lastEventTime": "",
"lastUpdateTime": "",
"resolvedTime": "",
"machineId": "",
"computerDnsName": "",
"rbacGroupName": "",
"aadTenantId": "",
"threatName": "",
"mitreTechniques": [],
"relatedUser": "",
"loggedOnUsers": [
{
"accountName": "",
"domainName": ""
}
],
"comments": [
{
"comment": "",
"createdBy": "",
"createdTime": ""
}
],
"evidence": [
{
"entityType": "",
"sha1": "",
"sha256": "",
"fileName": "",
"filePath": "",
"processId": "",
"processCommandLine": "",
"processCreationTime": "",
"parentProcessId": "",
"parentProcessCreationTime": "",
"ipAddress": "",
"url": "",
"registryKey": "",
"registryHive": "",
"registryValueType": "",
"registryValue": "",
"accountName": "",
"domainName": "",
"userSid": "",
"aadUserId": "",
"userPrincipalName": ""
}
],
"domains": []
}

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 Microsoft Defender For Endpoints. The OData's filter query is supported on: "Id", "Status", "MachineId", "Type", "Requestor", and "CreationDateTimeUtc".
Number of Machine Actions to Fetch	The maximum number of collection actions that this operation should return from Microsoft Defender For Endpoints.

Output

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

operation: Get Machine Action

Input parameters

Parameter	Description
Machine Action ID	The ID of the machine action object whose details you want to retrieve from Microsoft Defender For Endpoints. 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:
{
"@odata.context": "",
"id": "",
"type": "",
"title": "",
"requestor": "",
"requestorComment": "",
"status": "",
"machineId": "",
"computerDnsName": "",
"creationDateTimeUtc": "",
"lastUpdateDateTimeUtc": "",
"cancellationRequestor": "",
"cancellationComment": "",
"cancellationDateTimeUtc": "",
"errorHResult": "",
"scope": "",
"externalId": "",
"requestSource": "",
"relatedFileInfo": "",
"commands": [],
"troubleshootInfo": ""
}

operation: Submit Indicator

Input parameters

Parameter	Description
Indicator Value	Indicator value or identity of the indicator entity that you want to submit to Microsoft Defender For Endpoints.
Indicator Type	Type of the indicator that you want to submit to Microsoft Defender For Endpoints. You can choose from the following options: FileSha1, Filemd5, Certificate Thumbprint, FileSha256, IP Address, Domain Name, or URL.
Action	Action to be taken if the indicator is discovered in the organization. You can choose from the following options: Allow, Alert only, Alert and block, Warn, Block, Audit, or Block And Remediate.
Expiration Time	(Optional) Duration after which the indicator will expire in Microsoft Defender For Endpoints.
Alert Title	Title of the alert associated with the indicator.
Alert Severity	(Optional) The severity of the alert associated with the indicator. You can choose from the following options: Informational, Low, Medium, or High.
Description	Description of the indicator that you want to submit to Microsoft Defender For Endpoints.
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:
{
"@odata.context": "",
"id": "",
"indicatorValue": "",
"indicatorType": "",
"action": "",
"createdBy": "",
"severity": "",
"category": "",
"application": "",
"educateUrl": "",
"bypassDurationHours": "",
"title": "",
"description": "",
"recommendedActions": "",
"creationTimeDateTimeUtc": "",
"expirationTime": "",
"lastUpdateTime": "",
"lastUpdatedBy": "",
"rbacGroupNames": [],
"rbacGroupIds": [],
"notificationId": "",
"notificationBody": "",
"version": "",
"mitreTechniques": [],
"historicalDetection": "",
"lookBackPeriod": "",
"generateAlert": "",
"additionalInfo": "",
"createdByDisplayName": "",
"externalId": "",
"createdBySource": "",
"certificateInfo": ""
}

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 Microsoft Defender For Endpoints. 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	The maximum number of indicators that this operation should return from Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"id": "",
"indicatorValue": "",
"indicatorType": "",
"action": "",
"createdBy": "",
"severity": "",
"category": "",
"application": "",
"educateUrl": "",
"bypassDurationHours": "",
"title": "",
"description": "",
"recommendedActions": "",
"creationTimeDateTimeUtc": "",
"expirationTime": "",
"lastUpdateTime": "",
"lastUpdatedBy": "",
"rbacGroupNames": [],
"rbacGroupIds": [],
"notificationId": "",
"notificationBody": "",
"version": "",
"mitreTechniques": [],
"historicalDetection": "",
"lookBackPeriod": "",
"generateAlert": "",
"additionalInfo": "",
"createdByDisplayName": "",
"externalId": "",
"createdBySource": "",
"certificateInfo": ""
}
]
}

operation: Delete Indicator

Input parameters

Parameter	Description
Indicator ID	The ID of the indicator that you want to delete from the Microsoft Defender For Endpoints.

Output

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

operation: Collect Investigation Package

Input parameters

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

Output

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

operation: Offboard Machine

Input parameters

Parameter	Description
Machine ID	The ID of the machine that you want to offboard from Microsoft Defender For Endpoints.
Comment	The comment that you want to associate with the action.

Output

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

operation: Get Investigation Package SAS URI

Input parameters

Parameter	Description
Machine Action ID	The ID of the machine action whose SAS URI you want so that you can download the investigation package from Microsoft Defender For Endpoints.

Output

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

operation: Get Machine by ID

Input parameters

Parameter	Description
Machine ID	The ID of the machine whose details you want to retrieve from Microsoft Defender For Endpoints.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"id": "",
"mergedIntoMachineId": "",
"isPotentialDuplication": "",
"computerDnsName": "",
"firstSeen": "",
"lastSeen": "",
"osPlatform": "",
"osVersion": "",
"osProcessor": "",
"version": "",
"lastIpAddress": "",
"lastExternalIpAddress": "",
"agentVersion": "",
"osBuild": "",
"healthStatus": "",
"deviceValue": "",
"rbacGroupId": "",
"rbacGroupName": "",
"riskScore": "",
"exposureLevel": "",
"isAadJoined": "",
"aadDeviceId": "",
"machineTags": [],
"defenderAvStatus": "",
"onboardingStatus": "",
"osArchitecture": "",
"managedBy": "",
"managedByStatus": "",
"ipAddresses": [
{
"ipAddress": "",
"macAddress": "",
"type": "",
"operationalStatus": ""
}
],
"vmMetadata": ""
}

operation: Run Advanced Hunting Query

Input parameters

Parameter	Description
Query	The custom query to identify and investigate breach activity in Microsoft Defender For Endpoints. 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:
{
"Stats": {
"ExecutionTime": "",
"resource_usage": {
"cache": {
"memory": {
"hits": "",
"misses": "",
"total": ""
},
"disk": {
"hits": "",
"misses": "",
"total": ""
}
},
"cpu": {
"user": "",
"kernel": "",
"total cpu": ""
},
"memory": {
"peak_per_node": ""
}
},
"dataset_statistics": [
{
"table_row_count": "",
"table_size": ""
}
]
},
"Schema": [
{
"Name": "",
"Type": ""
}
],
"Results": [
{
"Timestamp": "",
"DeviceId": "",
"DeviceName": "",
"ActionType": "",
"FileName": "",
"FolderPath": "",
"SHA1": "",
"SHA256": "",
"MD5": "",
"FileSize": "",
"ProcessVersionInfoCompanyName": "",
"ProcessVersionInfoProductName": "",
"ProcessVersionInfoProductVersion": "",
"ProcessVersionInfoInternalFileName": "",
"ProcessVersionInfoOriginalFileName": "",
"ProcessVersionInfoFileDescription": "",
"ProcessId": "",
"ProcessCommandLine": "",
"ProcessIntegrityLevel": "",
"ProcessTokenElevation": "",
"ProcessCreationTime": "",
"AccountDomain": "",
"AccountName": "",
"AccountSid": "",
"AccountUpn": "",
"AccountObjectId": "",
"LogonId": "",
"InitiatingProcessAccountDomain": "",
"InitiatingProcessAccountName": "",
"InitiatingProcessAccountSid": "",
"InitiatingProcessAccountUpn": "",
"InitiatingProcessAccountObjectId": "",
"InitiatingProcessLogonId": "",
"InitiatingProcessIntegrityLevel": "",
"InitiatingProcessTokenElevation": "",
"InitiatingProcessSHA1": "",
"InitiatingProcessSHA256": "",
"InitiatingProcessMD5": "",
"InitiatingProcessFileName": "",
"InitiatingProcessFileSize": "",
"InitiatingProcessVersionInfoCompanyName": "",
"InitiatingProcessVersionInfoProductName": "",
"InitiatingProcessVersionInfoProductVersion": "",
"InitiatingProcessVersionInfoInternalFileName": "",
"InitiatingProcessVersionInfoOriginalFileName": "",
"InitiatingProcessVersionInfoFileDescription": "",
"InitiatingProcessId": "",
"InitiatingProcessCommandLine": "",
"InitiatingProcessCreationTime": "",
"InitiatingProcessFolderPath": "",
"InitiatingProcessParentId": "",
"InitiatingProcessParentFileName": "",
"InitiatingProcessParentCreationTime": "",
"InitiatingProcessSignerType": "",
"InitiatingProcessSignatureStatus": "",
"ReportId": "",
"AppGuardContainerId": "",
"AdditionalFields": ""
}
]
}

Included playbooks

The Sample - Microsoft Defender For Endpoints - 3.0.0 playbook collection comes bundled with the Microsoft Defender For Endpoints 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 Microsoft Defender For Endpoints connector.

• Collect Investigation Package
• 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 Investigation Package SAS URI
• 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
• Isolate Machine
• Offboard Machine
• Remove Application Restriction
• Remove Isolation
• Restrict Application Execution
• Run Advanced Hunting Query
• Run Antivirus Scan
• Submit Indicator
• Update Alert
• > Microsoft Defender For Endpoints > Create and Link Asset
• > Microsoft Defender For Endpoints > Fetch and Create
• Microsoft Defender For Endpoints > 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 Microsoft Defender For Endpoints. Currently, "alerts" in Microsoft Defender For Endpoints 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 Microsoft Defender For Endpoints "Alerts" to FortiSOAR™ "Alerts".

The Data Ingestion Wizard enables you to configure scheduled pulling of data from Microsoft Defender For Endpoints into FortiSOAR™. It also lets you pull some sample data from Microsoft Defender For Endpoints using which you can define the mapping of data between Microsoft Defender For Endpoints 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 Microsoft Defender For Endpoints alert.

1. To begin configuring data ingestion, click Configure Data Ingestion on the Microsoft Defender For Endpoints 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 Microsoft Defender For Endpoints 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 Microsoft Defender For Endpoints data.
   Users can choose to pull data from Microsoft Defender For Endpoints by specifying various filter criteria such as
   "Status", Severity, Category, or Incident ID. You could also specify a Search Query that will be used to pull alerts from Microsoft Defender For Endpoints. You can use the OData's Filter query to pull alerts from Microsoft Defender For Endpoints. The OData's Filter query is supported on the "alertCreationTime", "lastUpdateTime", "incidentId", "InvestigationId", "id", "asssignedTo", "detectionSource", "lastEventTime", "status", "severity" and "category" fields.
   Note: If you specify the 'Search Query', then all the other filter parameters are ignored.
   In the Fetch Alerts in last X Min field, specify the last X minutes from when you want to fetch alerts that have been updated in Microsoft Defender For Endpoints. Additionally, in the Number of Alerts to Fetch field, you can also specify the maximum number of alerts to be fetched in a single request:
   
   Once you have completed specifying the configurations, click Fetch Data.

3. On the Field Mapping screen, map the fields of a Microsoft Defender For Endpoints 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 Microsoft Defender For Endpoints 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 Microsoft Defender For Endpoints, so that the content gets pulled from the Microsoft Defender For Endpoints 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 Microsoft Defender For Endpoints every morning at 5 am, click Daily, and in the hour box enter 5 , and in the minute box enter 0:
   
   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.