Windows Defender Advanced Threat Protection (ATP) (Preview)

Windows Defender Advanced Threat Protection (ATP) is a unified platform for preventative protection, post-breach detection, automated investigation, and response. Read more about it here: http://aka.ms/wdatp

This connector is available in the following products and regions:

Service Class Regions
Logic Apps Standard All Logic Apps regions except the following:
     -   Azure Government regions
     -   Azure China regions
Flow Premium All Flow regions except the following:
     -   US Government (GCC)
PowerApps Premium All PowerApps regions except the following:
     -   US Government (GCC)

Throttling Limits

Name Calls Renewal Period
API calls per connection10060 seconds

Actions

Actions - Collect investigation package

Collect investigation package from a machine

Actions - Get investigation package download URI

Get a URI that allows downloading of an investigation package

Actions - Get list of machine actions

Retrieve from Windows Defender ATP the most recent machine actions

Actions - Get single machine action

Retrieve from Windows Defender ATP a specific machine action

Actions - Initiate investigation on a machine

Initiate investigation on a machine

Actions - Isolate machine

Isolate a machine from network

Actions - Remove app execution restriction

Enable execution of any application on the machine

Actions - Restrict app execution

Restrict execution of all applications on the machine except a predefined set

Actions - Run antivirus scan

Initiate Windows Defender Antivirus scan on a machine

Actions - Unisolate machine

Unisolate a machine from network

Advanced Hunting

Run a custom query in Windows Defender ATP

Alerts - Create alert

Create Alert based on specific Event

Alerts - Get list of alerts

Retrieve from Windows Defender ATP the most recent alerts

Alerts - Get single alert

Retrieve from Windows Defender ATP a specific alert

Alerts - Update alert

Update a Windows Defender ATP alert

Machines - Get list of machines

Retrieve from Windows Defender ATP the most recent machines

Machines - Get single machine

Retrieve from Windows Defender ATP a specific machine

Machines - Tag machine

Add or remove a tag to/from a machine

Actions - Collect investigation package

Collect investigation package from a machine

Parameters

Name Key Required Type Description
Machine ID
Machine ID True string

The ID of the machine to collect the investigation from

Comment
Comment True string

A comment to associate to the collection

Returns

A single machine action entity

Machine Action
MachineAction

Actions - Get investigation package download URI

Get a URI that allows downloading of an investigation package

Parameters

Name Key Required Type Description
Action ID
Machine action ID True string

The ID of the investigation package collection

Returns

Name Path Type Description
Package SAS URI
value string

The investigation package SAS URI

Actions - Get list of machine actions

Retrieve from Windows Defender ATP the most recent machine actions

Parameters

Name Key Required Type Description
Filters results
$filter string

Filters the results, using OData syntax.

Selects properties
$select string

Selects which properties to include in the response, defaults to all.

Sorts results
$orderby string

Sorts the results.

Returns first results
$top integer

Returns only the first n results.

Skips first results
$skip integer

Skips the first n results.

Includes count
$count boolean

Includes a count of the matching results in the response.

Returns

Name Path Type Description
Machine Actions count
@odata.count integer

The number of available machine actions by this query

Machine Actions
value array of MachineAction

The machine actions returned

Next link
@odata.nextLink string

A link to get the next results in case there are more results than requested

Actions - Get single machine action

Retrieve from Windows Defender ATP a specific machine action

Parameters

Name Key Required Type Description
ID of the machine action
Machine Action ID True string

The identifier of the machine action to retrieve

Returns

A single machine action entity

Machine Action
MachineAction

Actions - Initiate investigation on a machine

Initiate investigation on a machine

Parameters

Name Key Required Type Description
Machine ID
Machine ID True string

The ID of the machine to investigate

Comment
Comment True string

A comment to associate to the investigation

Returns

Name Path Type Description
Investigation ID
value string

The ID of the investigation

Actions - Isolate machine

Isolate a machine from network

Parameters

Name Key Required Type Description
Machine ID
Machine ID True string

The ID of the machine to isolate

Comment
Comment True string

A comment to associate to the isolation

Isolation Type
IsolationType True string

Type of the isolation. Allowed values are 'Full' (for full isolation) or 'Selective' (to restrict only limited set of applications from accessing the network)

Returns

A single machine action entity

Machine Action
MachineAction

Actions - Remove app execution restriction

Enable execution of any application on the machine

Parameters

Name Key Required Type Description
Machine ID
Machine ID True string

The ID of the machine to unrestrict

Comment
Comment True string

A comment to associate to the restriction removal

Returns

A single machine action entity

Machine Action
MachineAction

Actions - Restrict app execution

Restrict execution of all applications on the machine except a predefined set

Parameters

Name Key Required Type Description
Machine ID
Machine ID True string

The ID of the machine to restrict

Comment
Comment True string

A comment to associate to the restriction

Returns

A single machine action entity

Machine Action
MachineAction

Actions - Run antivirus scan

Initiate Windows Defender Antivirus scan on a machine

Parameters

Name Key Required Type Description
Machine ID
Machine ID True string

The ID of the machine to scan

Comment
Comment True string

A comment to associate to the scan request

Scan Type
ScanType True string

Type of scan to perform. Allowed values are 'Quick' or 'Full'

Returns

A single machine action entity

Machine Action
MachineAction

Actions - Unisolate machine

Unisolate a machine from network

Parameters

Name Key Required Type Description
Machine ID
Machine ID True string

The ID of the machine to unisolate

Comment
Comment True string

A comment to associate to the unisolation

Returns

A single machine action entity

Machine Action
MachineAction

Advanced Hunting

Run a custom query in Windows Defender ATP

Parameters

Name Key Required Type Description
Query
Query True string

The query to run

Returns

The outputs of this operation are dynamic.

Alerts - Create alert

Create Alert based on specific Event

Parameters

Name Key Required Type Description
Machine ID
machineId True string

ID of the machine on which the event was identified

Report ID
reportId True integer

Report Id of the event

Event Time
eventTime True date-time

Time of the event as string, e.g. 2018-08-03T16:45:21.7115183Z

Severity
severity True string

Severity of the alert.

Category
category True string

Category of the alert

Title
title True string

Title of the Alert

Description
description True string

Description of the Alert

Recommended Action
recommendedAction True string

Recommended action for the Alert

Returns

A single alert entity

Alert
Alert

Alerts - Get list of alerts

Retrieve from Windows Defender ATP the most recent alerts

Parameters

Name Key Required Type Description
Expands entities
$expand string

Expands related entities inline.

Filters results
$filter string

Filters the results, using OData syntax.

Selects properties
$select string

Selects which properties to include in the response, defaults to all.

Sorts results
$orderby string

Sorts the results.

Returns first results
$top integer

Returns only the first n results.

Skips first results
$skip integer

Skips the first n results.

Includes count
$count boolean

Includes a count of the matching results in the response.

Returns

Name Path Type Description
Alerts count
@odata.count integer

The number of available alerts by this query

Alerts
value array of Alert

The alerts returned

Next link
@odata.nextLink string

A link to get the next results in case there are more results than requested

Alerts - Get single alert

Retrieve from Windows Defender ATP a specific alert

Parameters

Name Key Required Type Description
ID of the alert
Alert ID True string

The identifier of the alert to retrieve

Returns

A single alert entity

Alert
Alert

Alerts - Update alert

Update a Windows Defender ATP alert

Parameters

Name Key Required Type Description
ID of the alert
Alert ID True string

The identifier of the alert to update

Status
status string

Status of the alert. One of 'New', 'InProgress' and 'Resolved'

Assigned to
assignedTo string

Person to assign the alert to

Classification
classification string

Classification of the alert. One of 'Unknown', 'FalsePositive', 'TruePositive'

Determination
determination string

The determination of the alert. One of 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other'

Returns

A single alert entity

Alert
Alert

Machines - Get list of machines

Retrieve from Windows Defender ATP the most recent machines

Parameters

Name Key Required Type Description
Filters results
$filter string

Filters the results, using OData syntax.

Selects properties
$select string

Selects which properties to include in the response, defaults to all.

Sorts results
$orderby string

Sorts the results.

Returns first results
$top integer

Returns only the first n results.

Skips first results
$skip integer

Skips the first n results.

Includes count
$count boolean

Includes a count of the matching results in the response.

Returns

Name Path Type Description
Machines count
@odata.count integer

The number of available machines by this query

Machines
value array of Machine

The machines returned

Next link
@odata.nextLink string

A link to get the next results in case there are more results than requested

Machines - Get single machine

Retrieve from Windows Defender ATP a specific machine

Parameters

Name Key Required Type Description
ID of the machine
Machine ID True string

The identifier of the machine to retrieve

Returns

A single machine entity

Machine
Machine

Machines - Tag machine

Add or remove a tag to/from a machine

Parameters

Name Key Required Type Description
ID of the machine
Machine ID True string

The ID of the machine to which the tag should be added or removed

Value
Value True string

The tag to add or remove

Action
Action True string

The action to perform. Value should be one of 'Add' (to add a tag) or 'Remove' (to remove a tag)

Returns

A single machine entity

Machine
Machine

Triggers

Triggers - Trigger when new WDATP alert occurs

Subscribe for Windows Defender ATP alerts

Triggers - Trigger when new WDATP alert occurs

Subscribe for Windows Defender ATP alerts

Returns

Definitions

Alert

A single alert entity

Name Path Type Description
Alert ID
id string

Alert identifier

Incident ID
incidentId integer

The ID of the incident

Investigation ID
investigationId integer

The Id of the investigation

Alert severity
severity string

Alert severity

Status
status string

Status of the alert

Description
description string

Alert description

Alert creation time
alertCreationTime date-time

The time at which the alert was created

Category
category string

Alert category

Title
title string

Alert title

Threat family name
threatFamilyName string

Threat family name

Detection source
detectionSource string

Detection source

Classification
classification string

Alert classification

Determination
determination string

Alert determination

Assigned to
assignedTo string

Person to whom the alert was assigned

Resolved time
resolvedTime string

The time at which the alert was resolved

Last event time
lastEventTime date-time

The time of the last event related to the alert

First event time
firstEventTime date-time

The time of the first event related to the alert

Machine ID
machineId string

The identifier of the machine related to the alert

Machine

A single machine entity

Name Path Type Description
Machine ID
id string

The machine identifier

Computer name
computerDnsName string

The computer name

First seen
firstSeen date-time

The time of the first event received by the machine

Last seen
lastSeen date-time

The time of the last event received by the machine

OS platform
osPlatform string

The OS platform of the machine

OS version
osVersion string

The OS version of the machine

System product name
systemProductName date-time

systemProductName

Last IP address
lastIpAddress string

The last IP address of the machine

Last external IP address
lastExternalIpAddress string

The last external IP address of the machine

Agent version
agentVersion string

The agent version

OS build
osBuild integer

The OS build of the machine

Health status
healthStatus string

The health status of the machine

Is AAD joined
isAadJoined boolean

A flag indicating whether the machine is joined to AAD

Machine tags
machineTags array of string

The tags associated to the machine

RBAC group ID
rbacGroupId integer

The ID of the RBAC group to which the machine belongs

RBAC group name
rbacGroupName string

The name of the RBAC group to which the machine belongs

Risk score
riskScore string

A score indicating how much the machine is at risk

AAD device ID
aadDeviceId string

aadDeviceId

MachineAction

A single machine action entity

Name Path Type Description
Action ID
id string

The ID of the machine action

Action type
type string

The type of the action (e.g. 'Isolate', 'CollectInvestigationPackage', ...)

Requestor
requestor string

The person that requested the machine action

Comment
requestorComment string

The comment associated to the machine action

Status
status string

The status of the machine action (e.g., 'InProgress')

ID
machineId string

The ID of the machine on which the action has been performed

Creation time
creationDateTimeUtc date-time

The UTC time at which the action has been requested

Last update time
lastUpdateDateTimeUtc date-time

The last UTC time at which the action has been updated

WebHookNotification

Name Path Type Description
Alert Id
id string
Machine Id
machineId string