Partilhar via


Microsoft Defender ATP

Microsoft Defender 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 China regions
Power Automate Premium All Power Automate regions except the following:
     -   China Cloud operated by 21Vianet
Power Apps Premium All Power Apps regions except the following:
     -   China Cloud operated by 21Vianet
Contact
Name Microsoft
URL Microsoft LogicApps Support
Microsoft Power Automate Support
Microsoft Power Apps Support
Connector Metadata
Publisher Microsoft
Website https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp

Creating a connection

The connector supports the following authentication types:

Default Parameters for creating connection. All regions Not shareable

Default

Applicable: All regions

Parameters for creating connection.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Throttling Limits

Name Calls Renewal Period
API calls per connection 100 60 seconds

Actions

Actions - Cancel a single machine action

Cancel a specific machine action

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 investigation

Retrieve from Microsoft Defender ATP the most recent investigations

Actions - Get list of machine actions

Retrieve from Windows Defender ATP the most recent machine actions

Actions - Get live response command result download URI

Get result download URI for a completed live response command

Actions - Get single investigation

Retrieve from Microsoft Defender ATP a specific investigation

Actions - Get single machine action

Retrieve from Windows Defender ATP a specific machine action

Actions - Initiate investigation on a machine (to be deprecated)

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 - Run live response

Run live response api commands for a single machine

Actions - Start automated investigation on a machine (Preview)

Start automated investigation 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

Domains - Get the statistics for the given domain name

Retrieve from Windows Defender ATP statistics related to a given domain name

Files - Get the statistics for the given file

Retrieve from Windows Defender ATP statistics for the given file to a given file by identifier Sha1, or Sha256

Ips - Get the statistics for the given ip address

Retrieve from Windows Defender ATP statistics related to a given ip address - given in ipv4 or ipv6 format.

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

Remediation activities - Get list of related machines (Preview)

Retrieve from Windows Defender ATP the related machines to a specific remediation activity

Remediation tasks - Get list of remediation activities (Preview)

Retrieve from Windows Defender ATP the remdiation activities

RemediationActivities - Get single remediation activity (Preview)

Retrieve from Windows Defender ATP a specific remediation activity

Actions - Cancel a single machine action

Cancel 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 cancel

Comment
Comment True string

A comment to associate to the machine action cancellation

Returns

A single machine action entity

Machine Action
MachineAction

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 investigation

Retrieve from Microsoft Defender ATP the most recent investigations

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
Investigations count
@odata.count integer

The number of available investigations by this query

Investigations
value array of Investigation

The investigations returned

Next link
@odata.nextLink string

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

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 live response command result download URI

Get result download URI for a completed live response command

Parameters

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

The identifier of the machine action

Index of the live response command
Command Index True integer

The index of the live response command to get the results download URI for

Returns

Name Path Type Description
Download URI
value string

The live response command download URI

Actions - Get single investigation

Retrieve from Microsoft Defender ATP a specific investigation

Parameters

Name Key Required Type Description
ID of the investigation
Investigation ID True string

The identifier of the investigation to retrieve

Returns

A single investigation entity

Investigation
Investigation

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 (to be deprecated)

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 - Run live response

Run live response api commands for a single machine

Parameters

Name Key Required Type Description
Machine ID
Machine ID True string

The ID of the machine to run live response session on

Comment
Comment True string

A comment to associate to the isolation

Command type
type True string

The type of the command

Command parameter key
key string

The key of the command parameter

Command parameter value
value string

The value of the command parameter

Returns

A single machine action entity

Machine Action
MachineAction

Actions - Start automated investigation on a machine (Preview)

Start automated 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

A single investigation entity

Investigation
Investigation

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 string

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

Domains - Get the statistics for the given domain name

Retrieve from Windows Defender ATP statistics related to a given domain name

Parameters

Name Key Required Type Description
The domain name
Domain Name True string

The domain name

The look back period in hours to look by, the default is 24 hours.
lookBackHours integer

The look back period in hours to look by, the default is 24 hours.

Returns

A single ip address statistics entity

Domain Statistics
DomainStats

Files - Get the statistics for the given file

Retrieve from Windows Defender ATP statistics for the given file to a given file by identifier Sha1, or Sha256

Parameters

Name Key Required Type Description
The file identifier - Sha1, or Sha256
File ID True string

The file identifier - Sha1, or Sha256

The look back period in hours to look by, the default is 24 hours.
lookBackHours integer

The look back period in hours to look by, the default is 24 hours.

Returns

A single file statistics entity

File Statistics
FileStats

Ips - Get the statistics for the given ip address

Retrieve from Windows Defender ATP statistics related to a given ip address - given in ipv4 or ipv6 format.

Parameters

Name Key Required Type Description
The ip address
Ip Address True string

The ip address

The look back period in hours to look by, the default is 24 hours.
lookBackHours integer

The look back period in hours to look by, the default is 24 hours.

Returns

A single ip address statistics entity

Ip Statistics
IpStats

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

Retrieve from Windows Defender ATP the related machines to a specific remediation activity

Parameters

Name Key Required Type Description
ID of the remediation activity
RemediationID True string

The identifier of the remediation activity to retrieve

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

Remediation tasks - Get list of remediation activities (Preview)

Retrieve from Windows Defender ATP the remdiation activities

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
Remediation activities count
@odata.count integer

The number of remediation activities by this query

Remediation activities
value array of RemediationActivity

The remediation activities returned

Next link
@odata.nextLink string

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

RemediationActivities - Get single remediation activity (Preview)

Retrieve from Windows Defender ATP a specific remediation activity

Parameters

Name Key Required Type Description
ID of the remediation activity
RemediationID True string

The identifier of the remediation activity to retrieve

Returns

A single remediation activity entity

Remediation Activity
RemediationActivity

Triggers

Triggers - Trigger when new WDATP alert occurs

Subscribe for Windows Defender ATP alerts

Triggers when a new remediation activity is created (Preview)

Triggers when a new remediation activity is created

Triggers - Trigger when new WDATP alert occurs

Subscribe for Windows Defender ATP alerts

Returns

Triggers when a new remediation activity is created (Preview)

Triggers when a new remediation activity is created

Returns

Name Path Type Description
Remediation activities count
@odata.count integer

The number of remediation activities by this query

Remediation activities
value array of RemediationActivity

The remediation activities returned

Next link
@odata.nextLink string

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

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 Microsoft Entra ID joined
isAadJoined boolean

A flag indicating whether the machine is joined to Microsoft Entra ID

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

Microsoft Entra ID device ID
aadDeviceId string

aadDeviceId

RemediationActivity

A single remediation activity entity

Name Path Type Description
Remediation activity ID
id string

The remediation activity identifier

Title of the remediation activity
title string

The title of the remediation activit

Created on
createdOn date-time

The time when the remediation activity was created

Status last modified on
statusLastModifiedOn date-time

The time when the status was last modified

Creator id
requesterId string

The remediation activity creator id

Creator email
requesterEmail string

The remediation activity creator email address

Status
status string

the remediation activity status

Description
description string

The description of the remediation activity

Related component
relatedComponent string

The remediation activity related component

Target devices
targetDevices integer

The number of the remediation activity target machines

Rbac group names
rbacGroupNames array of string

The rbac group names associated to the remediation activity

Fixed devices
fixedDevices integer

The number of the remediation activity fixed machines

creator notes
requesterNotes string

The remeidation activity creator notes

Due on
dueOn date-time

The due time for the remediation activity

Category
category string

the remediation activity category

Productivity impact remediation type
productivityImpactRemediationType string

the remediation Productivity impact type

Priority
priority string

The remediation activity priority

Completion method
completionMethod string

The remediation activity completion method

Completer id
completerId string

The remediation activity completer object id

Completer email
completerEmail string

The remediation activity completer email address

Security configuration id
scid string

The remediation activity security configuration id

Type
type string

The remediation activity type

Product id
productId string

Product Id

Vendor id
vendorId string

Vendor id

Name id
nameId string

Name id

Recommended version
recommendedVersion string

Recommended version

Recommended vendor
recommendedVendor string

Recommended vendor

Recommended program
recommendedProgram string

Recommended program

Recommendation reference
RecommendationReference string

Recommendation reference

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

Commands
commands array of LiveResponseCommandStatus

Live response machine action commands

LiveResponseCommandStatus

A single command in Live Response machine action entity

Name Path Type Description
Command index
index integer

The index of the command

The command execution start time
startTime date-time

The command execution start time UTC

The command execution end time
endTime date-time

The command execution end time UTC

Command status
commandStatus string

The status of the command execution (e.g., 'Completed')

Command errors
errors array of string

List of command execution errors. In case no errors reported this will be an empty list.

command
command LiveResponseCommand

LiveResponseCommand

Name Path Type Description
Command type
type string

The type of the command

Command params
params array of object

List of command parameters.

Command parameter key
params.key string

The key of the command parameter

Command parameter value
params.value string

The value of the command parameter

FileStats

A single file statistics entity

Name Path Type Description
Sha1
sha1 string

The sha1 of the file

Global Prevalence
globallyPrevalence integer

The file global prevalence.

Globally First Observed
globalFirstObserved date-time

The first time the file was observed globally.

Globally Last Observed
globalLastObserved date-time

The Last time the file was observed.

Org Prevalence
organizationPrevalence integer

The file prevalence across organization

Org First Observed
orgFirstSeen date-time

The first time the file was observed in the organization.

Org Last Observed
orgLastSeen date-time

The last time the file was observed in the organization.

Top File Names
topFileNames array of string

The file names that this file has been presented.

IpStats

A single ip address statistics entity

Name Path Type Description
Ip Adress
ipAddress string

The ip adress

Org Prevalence
organizationPrevalence integer

The ip address prevalence across organization

Org First Observed
orgFirstSeen date-time

The first time the ip address was observed in the organization.

Org Last Observed
orgLastSeen date-time

The last time the ip address was observed in the organization.

DomainStats

A single ip address statistics entity

Name Path Type Description
Host
host string

The domain host.

Org Prevalence
organizationPrevalence integer

The domain prevalence across organization

Org First Observed
orgFirstSeen date-time

The first time the domain was observed in the organization.

Org Last Observed
orgLastSeen date-time

The last time the domain was observed in the organization.

Investigation

A single investigation entity

Name Path Type Description
ID
id string

The ID of the investigation

Investigation state
state string

The state of the investigation (e.g. 'Benign', 'Running', etc..)

Status details
statusDetails string

Details on the status

Computer name
computerDnsName string

The computer name

Machine ID
machineId string

The machine ID

Start time
startTime date-time

The UTC time at which investigation was started

End time
endTime date-time

The UTC time at which investigation was completed

WebHookNotification

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