deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-05-19 08:47:22 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'atp-api-danm' of https://cpubwin.visualstudio.com/_git/it-client into atp-api-danm

Browse Source
This commit is contained in:
Joey Caparas 2018-08-21 10:16:07 -07:00
commit d3f59e5a62
48 changed files with 4155 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.openpublishing.publish.config.json
View File

@ -508,6 +508,10 @@
"master": [ "master": [
"Publish", "Publish",
"Pdf" "Pdf"
],
"atp-api-danm": [
"Publish",
"Pdf"
] ]
}, },
"need_generate_pdf_url_template": true, "need_generate_pdf_url_template": true,

54
windows/security/threat-protection/windows-defender-atp/TOC.md
View File

@ -39,8 +39,6 @@
#### [Investigate a user account](investigate-user-windows-defender-advanced-threat-protection.md) #### [Investigate a user account](investigate-user-windows-defender-advanced-threat-protection.md)
###Machines list ###Machines list
#### [View and organize the Machines list](machines-view-overview-windows-defender-advanced-threat-protection.md) #### [View and organize the Machines list](machines-view-overview-windows-defender-advanced-threat-protection.md)
#### [Manage machine group and tags](investigate-machines-windows-defender-advanced-threat-protection.md) #### [Manage machine group and tags](investigate-machines-windows-defender-advanced-threat-protection.md)
@ -103,6 +101,58 @@
##### [Get access without a user](exposed-apis-create-app-webapp.md) ##### [Get access without a user](exposed-apis-create-app-webapp.md)
#### [Supported Windows Defender ATP APIs](exposed-apis-list.md) #### [Supported Windows Defender ATP APIs](exposed-apis-list.md)
##### [Advanced Hunting](run-advanced-query-api.md) ##### [Advanced Hunting](run-advanced-query-api.md)
##### [Alert](alerts-windows-defender-advanced-threat-protection-new.md)
###### [List alerts](get-alerts-windows-defender-advanced-threat-protection-new.md)
###### [Create alert](create-alert-by-reference-windows-defender-advanced-threat-protection-new.md)
###### [Update Alert](update-alert-windows-defender-advanced-threat-protection-new.md)
###### [Get alert information by ID](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md)
###### [Get alert related domains information](get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md)
###### [Get alert related file information](get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md)
###### [Get alert related IPs information](get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md)
###### [Get alert related machine information](get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md)
###### [Get alert related user information](get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md)
##### Domain
###### [Get domain related alerts](get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md)
###### [Get domain related machines](get-domain-related-machines-windows-defender-advanced-threat-protection-new.md)
###### [Get domain statistics](get-domain-statistics-windows-defender-advanced-threat-protection-new.md)
###### [Is domain seen in organization](is-domain-seen-in-org-windows-defender-advanced-threat-protection-new.md)
##### [File](files-windows-defender-advanced-threat-protection-new.md)
###### [Get file information](get-file-information-windows-defender-advanced-threat-protection-new.md)
###### [Get file related alerts](get-file-related-alerts-windows-defender-advanced-threat-protection-new.md)
###### [Get file related machines](get-file-related-machines-windows-defender-advanced-threat-protection-new.md)
###### [Get file statistics](get-file-statistics-windows-defender-advanced-threat-protection-new.md)
##### IP
###### [Get IP related alerts](get-ip-related-alerts-windows-defender-advanced-threat-protection-new.md)
###### [Get IP related machines](get-ip-related-machines-windows-defender-advanced-threat-protection-new.md)
###### [Get IP statistics](get-ip-statistics-windows-defender-advanced-threat-protection-new.md)
###### [Is IP seen in organization](is-ip-seen-org-windows-defender-advanced-threat-protection-new.md)
##### [Machine](machine-windows-defender-advanced-threat-protection-new.md)
###### [Get machines](get-machines-windows-defender-advanced-threat-protection-new.md)
###### [Get machine by ID](get-machine-by-id-windows-defender-advanced-threat-protection-new.md)
###### [Get machine log on users](get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md)
###### [Get machine related alerts](get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md)
##### [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md)
###### [List MachineActions](get-machineactions-collection-windows-defender-advanced-threat-protection-new.md)
###### [Get MachineAction](get-machineaction-object-windows-defender-advanced-threat-protection-new.md)
###### [Collect investigation package](collect-investigation-package-windows-defender-advanced-threat-protection-new.md)
###### [Get investigation package SAS URI](get-package-sas-uri-windows-defender-advanced-threat-protection-new.md)
###### [Isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md)
###### [Release machine from isolation](unisolate-machine-windows-defender-advanced-threat-protection-new.md)
###### [Restrict app execution](restrict-code-execution-windows-defender-advanced-threat-protection-new.md)
###### [Remove app restriction](unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md)
###### [Run antivirus scan](run-av-scan-windows-defender-advanced-threat-protection-new.md)
###### [Offboard machine](offboard-machine-api-windows-defender-advanced-threat-protection-new.md)
##### [User](user-windows-defender-advanced-threat-protection-new.md)
###### [Get user related alerts](get-user-related-alerts-windows-defender-advanced-threat-protection-new.md)
###### [Get user related machines](get-user-related-machines-windows-defender-advanced-threat-protection-new.md)
#### How to use APIs - Samples #### How to use APIs - Samples
##### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md) ##### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md)
##### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) ##### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)

79
windows/security/threat-protection/windows-defender-atp/alerts-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,79 @@
---
title: Get alerts API
description: Retrieves top recent alerts.
keywords: apis, graph api, supported apis, get, alerts, recent
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Alert resource type
[!include[Prerelease information](prerelease.md)]
Represents an alert entity in WDATP.
# Methods
Method|Return Type |Description
:---|:---|:---
[Get alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) | Get a single [alert](alerts-windows-defender-advanced-threat-protection-new.md) object.
[List alerts](get-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | List [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection.
[Create alert](create-alert-by-reference-windows-defender-advanced-threat-protection-new.md)|[alert](alerts-windows-defender-advanced-threat-protection-new.md)|Create an alert based on event data obtained from [Advanced Hunting](run-advanced-query-api.md)
[List related domains](get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md)|Domain collection|List Urls associated with the alert.
[List related files](get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md) | [file](files-windows-defender-advanced-threat-protection-new.md) collection | List the [file](files-windows-defender-advanced-threat-protection-new.md) entities that are associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md).
[List related IPs](get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md) | IP collection | List IPs that are associated witht the alert.
[Get related machines](get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) | The [machine](machine-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md).
[Get related users](get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md) | [user](user-windows-defender-advanced-threat-protection-new.md) | The [user](user-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md).
# Properties
Property | Type | Description
:---|:---|:---
id | String | alert id.
severity | String | severity of the alert. Allowed values are: 'Low', 'Medium' and 'High'.
status | String | Specifies the current status of the alert. The property values are: 'New', 'InProgress' and 'Resolved'.
description | String | Description of the threat, identified by the alert.
recommendedAction | String | Action recommended for handling the suspected threat.
alertCreationTime | DateTimeOffset | The date and time (in UTC) the alert was created.
category| String | Category of the alert. The property values are: 'None', 'SuspiciousActivity', 'Malware', 'CredentialTheft', 'Exploit', 'WebExploit', 'DocumentExploit', 'PrivilegeEscalation', 'Persistence', 'RemoteAccessTool', 'CommandAndControl', 'SuspiciousNetworkTraffic', 'Ransomware', 'MalwareDownload', 'Reconnaissance', 'WebFingerprinting', 'Weaponization', 'Delivery', 'SocialEngineering', 'CredentialStealing', 'Installation', 'Backdoor', 'Trojan', 'TrojanDownloader', 'LateralMovement', 'ExplorationEnumeration', 'NetworkPropagation', 'Exfiltration', 'NotApplicable', 'EnterprisePolicy' and 'General'.
title | string | Alert title.
threatFamilyName | string | Threat family.
detectionSource | string | detection source
assignedTo | String | Owner of the alert
classification | String | Speficies the specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'.
determination | String | Specifies the determination of the alert. The property values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other'
resolvedTime | DateTimeOffset | The date and time in which the status of the alert was changed to 'Resolved'.
lastEventTime | DateTimeOffset | The last occurance of the event that triggered the alert on the same machine.
firstEventTime | DateTimeOffset | The first occurance of the event that triggered the alert on that machine.
machineId | String | id of a [machine](machine-windows-defender-advanced-threat-protection-new.md) entity that is associated with the alert.
# JSON representation
```
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"id": "636688558380765161_2136280442",
"severity": "Informational",
"status": "InProgress",
"description": "Some alert description 1",
"recommendedAction": "Some recommended action 1",
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
"category": "General",
"title": "Some alert title 1",
"threatFamilyName": null,
"detectionSource": "WindowsDefenderAtp",
"classification": "TruePositive",
"determination": null,
"assignedTo": "best secop ever",
"resolvedTime": null,
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
"actorName": null,
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
}
```

94
windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,94 @@
---
title: Collect investigation package API
description: Use this API to create calls related to the collecting an investigation package from a machine.
keywords: apis, graph api, supported apis, collect investigation package
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Collect investigation package API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Collect investigation package from a machine.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.CollectForensics | 'Collect forensics'
## HTTP request
```
POST /api/machines/{id}/collectInvestigationPackage
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | string | application/json. **Required**.
## Request body
In the request body, supply a JSON object with the following parameters:
Parameter | Type | Description
:---|:---|:---
Comment | String | Comment to associate with the action. **Required**.
## Response
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/collectInvestigationPackage
Content-type: application/json
{
"Comment": "Collect forensics due to alert 1234"
}
```
**Response**
Here is an example of the response.
```
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
"id": "c9042f9b-8483-4526-87b5-35e4c2532223",
"type": "CollectInvestigationPackage",
"requestor": "Analyst@contoso.com",
"requestorComment": " Collect forensics due to alert 1234",
"status": "InProgress",
"error": "None",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"creationDateTimeUtc": "2017-12-04T12:09:24.1785079Z",
"lastUpdateTimeUtc": "2017-12-04T12:09:24.1785079Z"
}
```

87
windows/security/threat-protection/windows-defender-atp/create-alert-by-reference-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,87 @@
---
title: Create alert from event API
description: Creates an alert using event details
keywords: apis, graph api, supported apis, get, alert, information, id
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Create alert from event API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Enables using event data, as obtained from the [Advanced Hunting](run-advanced-query-api.md) for creating a new alert entity.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alerts.ReadWrite.All | 'Read and write all alerts'
## HTTP request
```
POST /api/CreateAlertByReference
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | String | application/json. **Required**.
## Request body
In the request body, supply the following values (all are required):
Property | Type | Description
:---|:---|:---
machineId | String | Id of the machine on which the event was identified. **Required**.
severity | String | Severity of the alert. The property values are: 'Low', 'Medium' and 'High'. **Required**.
title | String | Title for the alert. **Required**.
description | String | Description of the alert. **Required**.
recommendedAction| String | Action that is recommended to be taken by security officer when analyzing the alert.
eventTime | DateTime(UTC) | The time of the event, as obtained from the advanced query. **Required**.
reportId | String | The reportId, as obtained from the advanced query. **Required**.
category| String | Category of the alert. The property values are: 'None', 'SuspiciousActivity', 'Malware', 'CredentialTheft', 'Exploit', 'WebExploit', 'DocumentExploit', 'PrivilegeEscalation', 'Persistence', 'RemoteAccessTool', 'CommandAndControl', 'SuspiciousNetworkTraffic', 'Ransomware', 'MalwareDownload', 'Reconnaissance', 'WebFingerprinting', 'Weaponization', 'Delivery', 'SocialEngineering', 'CredentialStealing', 'Installation', 'Backdoor', 'Trojan', 'TrojanDownloader', 'LateralMovement', 'ExplorationEnumeration', 'NetworkPropagation', 'Exfiltration', 'NotApplicable', 'EnterprisePolicy' and 'General'.
## Response
If successful, this method returns 200 OK, and a new [alert](alerts-windows-defender-advanced-threat-protection-new.md) object in the response body. If event with the specified properties (_reportId_, _eventTime_ and _machineId_) was not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
POST https://api.securitycenter.windows.com/api/CreateAlertByReference
Content-Length: application/json
{
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"severity": "Low",
"title": "test alert",
"description": "redalert",
"recommendedAction": "white alert",
"eventTime": "2018-08-03T16:45:21.7115183Z",
"reportId": "20776",
"category": "None"
}
```

49
windows/security/threat-protection/windows-defender-atp/files-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,49 @@
---
title: File resource type
description: Retrieves top recent alerts.
keywords: apis, graph api, supported apis, get, alerts, recent
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# File resource type
[!include[Prerelease information](prerelease.md)]
Represent a file entity in WDATP.
# Methods
Method|Return Type |Description
:---|:---|:---
[Get file](get-file-information-windows-defender-advanced-threat-protection-new.md) | [file](files-windows-defender-advanced-threat-protection-new.md) | Get a single file
[List file related alerts](get-file-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | Get the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities that are associated with the file.
[List file related machines](get-file-related-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | Get the [machine](machine-windows-defender-advanced-threat-protection-new.md) entities associated with the alert.
[file statistics](get-file-statistics-windows-defender-advanced-threat-protection-new.md) | Statistics summary | Retrieves the prevalence for the given file.
# Properties
Property | Type | Description
:---|:---|:---
sha1 | String | Sha1 hash of the file content
sha256 | String | Sha256 hash of the file content
md5 | String | md5 hash of the file content
globalPrevalence | Integer | File prevalence accross organization
globalFirstObserved | DateTimeOffset | First time the file was observed.
globalLastObserved | DateTimeOffset | Last time the file was observed.
size | Integer | Size of the file.
fileType | String | Type of the file.
isPeFile | Boolean | true if the file is portable executable (e.g. "DLL", "EXE", etc.)
filePublisher | String | File publisher.
fileProductName | String | Product name.
signer | String | File signer.
issuer | String | File issuer.
signerHash | String | Hash of the signing certificate.
isValidCertificate | Boolean | Was signing certificate successfully verified by WDATP agent.

88
windows/security/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,88 @@
---
title: Find machine information by internal IP API
description: Use this API to create calls related to finding a machine entry around a specific timestamp by internal IP.
keywords: ip, apis, graph api, supported apis, find machine, machine information
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: high
ms.date: 07/25/2018
---
# Find machine information by internal IP API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Find a machine by internal IP.
>[!NOTE]
>The timestamp must be within the last 30 days.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/machines/find(timestamp={time},key={IP})
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and machine exists - 200 OK.
If no machine found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
```
GET https://graph.microsoft.com/testwdatppreview/machines/find(timestamp=2018-06-19T10:00:00Z,key='10.166.93.61')
Content-type: application/json
```
**Response**
Here is an example of the response.
The response will return a list of all machines that reported this IP address within sixteen minutes prior and after the timestamp.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#Machines",
"value": [
{
"id": "04c99d46599f078f1c3da3783cf5b95f01ac61bb",
"computerDnsName": "",
"firstSeen": "2017-07-06T01:25:04.9480498Z",
"osPlatform": "Windows10",
…
}
```

94
windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,94 @@
---
title: Get alert information by ID API
description: Retrieves an alert by its ID.
keywords: apis, graph api, supported apis, get, alert, information, id
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get alert information by ID API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves an alert by its ID.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alert.Read.All | 'Read all alerts'
Application | Alert.ReadWrite.All | 'Read and write all alerts'
## HTTP request
```
GET /api/alerts/{id}
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful, this method returns 200 OK, and the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entity in the response body. If alert with the specified id was not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442
```
**Response**
Here is an example of the response.
```
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"id": "636688558380765161_2136280442",
"severity": "Informational",
"status": "InProgress",
"description": "Some alert description 1",
"recommendedAction": "Some recommended action 1",
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
"category": "General",
"title": "Some alert title 1",
"threatFamilyName": null,
"detectionSource": "WindowsDefenderAtp",
"classification": "TruePositive",
"determination": null,
"assignedTo": "best secop ever",
"resolvedTime": null,
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
"actorName": null,
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
}
```

84
windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,84 @@
---
title: Get alert related domains information
description: Retrieves all domains related to a specific alert.
keywords: apis, graph api, supported apis, get alert information, alert information, related domain
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get alert related domain information API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves all domains related to a specific alert.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | URL.Read.All | 'Read URLs'
## HTTP request
```
GET /api/alerts/{id}/domains
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and alert and domain exist - 200 OK.
If alert not found or domain not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/alerts/636688558380765161_2136280442/domains
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/$metadata#Domains",
"value": [
{
"host": "www.example.com"
}
]
}
```

97
windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,97 @@
---
title: Get alert related files information
description: Retrieves all files related to a specific alert.
keywords: apis, graph api, supported apis, get alert information, alert information, related files
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get alert related files information API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves all files related to a specific alert.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | File.Read.All | 'Read file profiles'
## HTTP request
```
GET /api/alerts/{id}/files
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and alert and files exist - 200 OK.
If alert not found or files not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/files
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files",
"value": [
{
"sha1": "654f19c41d9662cf86be21bf0af5a88c38c56a9d",
"sha256": "2f905feec2798cee6f63da2c26758d86bfeaab954c01e20ac7085bf55fedde87",
"md5": "82849dc81d94056224445ea73dc6153a",
"globalPrevalence": 33,
"globalFirstObserved": "2018-07-17T18:17:27.5909748Z",
"globalLastObserved": "2018-08-06T16:07:12.9414137Z",
"windowsDefenderAVThreatName": null,
"size": 801112,
"fileType": "PortableExecutable",
"isPeFile": true,
"filePublisher": null,
"fileProductName": null,
"signer": "Microsoft Windows",
"issuer": "Microsoft Development PCA 2014",
"signerHash": "9e284231a4d1c53fc8d4492b09f65116bf97447f",
"isValidCertificate": true
}
]
}
```

86
windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,86 @@
---
title: Get alert related IPs information
description: Retrieves all IPs related to a specific alert.
keywords: apis, graph api, supported apis, get alert information, alert information, related ip
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get alert related IP information API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves all IPs related to a specific alert.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Ip.Read.All | 'Read IP address profiles'
## HTTP request
```
GET /api/alerts/{id}/ips
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and alert and an IP exist - 200 OK. If alert not found or IPs not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/alerts/636688558380765161_2136280442/ips
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/$metadata#Ips",
"value": [
{
"id": "104.80.104.128"
},
{
"id": "23.203.232.228
}
]
}
```

96
windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,96 @@
---
title: Get alert related machine information
description: Retrieves all machines related to a specific alert.
keywords: apis, graph api, supported apis, get alert information, alert information, related machine
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get alert related machine information API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves machine that is related to a specific alert.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/alerts/{id}/machine
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and alert and machine exist - 200 OK.
If alert not found or machine not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/machine
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines/$entity",
"id": "ff0c3800ed8d66738a514971cd6867166809369f",
"computerDnsName": "amazingmachine.contoso.com",
"firstSeen": "2017-12-10T07:47:34.4269783Z",
"osPlatform": "Windows10",
"osVersion": "10.0.0.0",
"systemProductName": null,
"lastIpAddress": "172.17.0.0",
"lastExternalIpAddress": "167.220.0.0",
"agentVersion": "10.5830.17732.1001",
"groupName": "ContosoGroup",
"osBuild": 17732,
"healthStatus": "Active",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 75,
"riskScore": "Low",
"aadDeviceId": "80fe8ff8-0000-0000-9591-41f0491218f9"
}
```

88
windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,88 @@
---
title: Get alert related user information
description: Retrieves the user associated to a specific alert.
keywords: apis, graph api, supported apis, get, alert, information, related, user
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get alert related user information API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves the user associated to a specific alert.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | User.Read.All | 'Read user profiles'
## HTTP request
```
GET /api/alerts/{id}/user
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and alert and a user exists - 200 OK with user in the body.
If alert not found or user not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/user
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users/$entity",
"id": "contoso\\user1",
"firstSeen": "2018-08-02T00:00:00Z",
"lastSeen": "2018-08-04T00:00:00Z",
"mostPrevalentMachineId": null,
"leastPrevalentMachineId": null,
"logonTypes": "Network",
"logOnMachinesCount": 3,
"isDomainAdmin": false,
"isOnlyNetworkUser": null
}
```

125
windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,125 @@
---
title: List alerts API
description: Retrieves top recent alerts.
keywords: apis, graph api, supported apis, get, alerts, recent
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# List alerts API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves top recent alerts.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alert.Read.All | 'Read all alerts'
Application | Alert.ReadWrite.All | 'Read and write all alerts'
## HTTP request
```
GET /api/alerts
```
## Optional query parameters
Method supports $skip and $top query parameters.
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful, this method returns 200 OK, and a list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) objects in the response body. If no recent alerts found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/alerts
```
**Response**
Here is an example of the response.
>[!NOTE]
>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.
```
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"value": [
{
"id": "636688558380765161_2136280442",
"severity": "Informational",
"status": "InProgress",
"description": "Some alert description 1",
"recommendedAction": "Some recommended action 1",
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
"category": "General",
"title": "Some alert title 1",
"threatFamilyName": null,
"detectionSource": "WindowsDefenderAtp",
"classification": "TruePositive",
"determination": null,
"assignedTo": "best secop ever",
"resolvedTime": null,
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
"actorName": null,
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
},
{
"id": "636688558380765161_2136280442",
"severity": "Informational",
"status": "InProgress",
"description": "Some alert description 2",
"recommendedAction": "Some recommended action 2",
"alertCreationTime": "2018-08-04T01:17:17.9516179Z",
"category": "General",
"title": "Some alert title 2",
"threatFamilyName": null,
"detectionSource": "WindowsDefenderAtp",
"classification": "TruePositive",
"determination": null,
"assignedTo": "best secop ever",
"resolvedTime": null,
"lastEventTime": "2018-08-03T07:02:52.0894451Z",
"firstEventTime": "2018-08-03T07:02:52.0894451Z",
"actorName": null,
"machineId": "ff0c3800ed8d66738a514971cd6867166809369d"
}
]
}
```

121
windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,121 @@
---
title: Get domain related alerts API
description: Retrieves a collection of alerts related to a given domain address.
keywords: apis, graph api, supported apis, get, domain, related, alerts
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get domain related alerts API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of alerts related to a given domain address.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alert.Read.All | 'Read all alerts'
Application | Alert.ReadWrite.All | 'Read and write all alerts'
## HTTP request
```
GET /api/domains/{domain}/alerts
```
## Request headers
Header | Value
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and domain and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities. If domain or alert does not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/domains/client.wns.windows.com/alerts
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
"value": [
{
"id": "636688558380765161_2136280442",
"severity": "Informational",
"status": "InProgress",
"description": "Some alert description 1",
"recommendedAction": "Some recommended action 1",
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
"category": "General",
"title": "Some alert title 1",
"threatFamilyName": null,
"detectionSource": "WindowsDefenderAtp",
"classification": "TruePositive",
"determination": null,
"assignedTo": "best secop ever",
"resolvedTime": null,
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
"actorName": null,
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
},
{
"id": "636688558380765161_2136280442",
"severity": "Informational",
"status": "InProgress",
"description": "Some alert description 2",
"recommendedAction": "Some recommended action 2",
"alertCreationTime": "2018-08-04T01:17:17.9516179Z",
"category": "General",
"title": "Some alert title 2",
"threatFamilyName": null,
"detectionSource": "WindowsDefenderAtp",
"classification": "TruePositive",
"determination": null,
"assignedTo": "best secop ever",
"resolvedTime": null,
"lastEventTime": "2018-08-03T07:02:52.0894451Z",
"firstEventTime": "2018-08-03T07:02:52.0894451Z",
"actorName": null,
"machineId": "ff0c3800ed8d66738a514971cd6867166809369d"
}
]
}
```

119
windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,119 @@
---
title: Get domain related machines API
description: Retrieves a collection of machines related to a given domain address.
keywords: apis, graph api, supported apis, get, domain, related, machines
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get domain related machines API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of machines that have communicated to or from a given domain address.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/domains/{domain}/machines
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and domain and machine exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities. If domain or machines do not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/domains/api.securitycenter.windows.com/machines
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
"value": [
{
"id": "02ea9a24e8bd39c247ed7ca0edae879c321684e5",
"computerDnsName": "testMachine1",
"firstSeen": "2018-07-30T20:12:00.3708661Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "10.209.67.177",
"lastExternalIpAddress": "167.220.1.210",
"agentVersion": "10.5830.18208.1000",
"groupName": null,
"osBuild": 18208,
"healthStatus": "Inactive",
"isAadJoined": false,
"machineTags": [],
"rbacGroupId": 75,
"riskScore": "Low",
"aadDeviceId": null
},
{
"id": "02efb9a9b85f07749a018fbf3f962b4700b3b949",
"computerDnsName": "testMachine2",
"firstSeen": "2018-07-30T19:50:47.3618349Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "10.209.70.231",
"lastExternalIpAddress": "167.220.0.28",
"agentVersion": "10.5830.18208.1000",
"groupName": null,
"osBuild": 18208,
"healthStatus": "Inactive",
"isAadJoined": false,
"machineTags": [],
"rbacGroupId": 75,
"riskScore": "None",
"aadDeviceId": null
}
]
}
```

82
windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,82 @@
---
title: Get domain statistics API
description: Retrieves the prevalence for the given domain.
keywords: apis, graph api, supported apis, get, domain, domain related machines
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get domain statistics API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves the prevalence for the given domain.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | URL.Read.All | 'Read all machine profiles'
## HTTP request
```
GET /api/domains/{domain}/stats
```
## Request headers
Header | Value
:---|:---
Authorization | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and domain exists - 200 OK, with statistics object in the response body.
If domain does not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/domains/example.com/stats
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgDomainStats",
"host": "example.com",
"orgPrevalence": "4070",
"orgFirstSeen": "2017-07-30T13:23:48Z",
"orgLastSeen": "2017-08-29T13:09:05Z"
}
```

95
windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,95 @@
---
title: Get file information API
description: Retrieves a file by identifier Sha1, Sha256, or MD5.
keywords: apis, graph api, supported apis, get, file, information, sha1, sha256, md5
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get file information API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a file by identifier Sha1, Sha256, or MD5.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | File.Read.All | 'Read all file profiles'
## HTTP request
```
GET /api/files/{id}
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and file exists - 200 OK with the [file](files-windows-defender-advanced-threat-protection-new.md) entity in the body.
If file does not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files/$entity",
"sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1",
"sha256": "d4447dffdbb2889b4b4e746b0bc882df1b854101614b0aa83953ef3cb66904cf",
"md5": "7f05a371d2beffb3784fd2199f81d730",
"globalPrevalence": 7329,
"globalFirstObserved": "2018-04-08T05:50:29.4459725Z",
"globalLastObserved": "2018-08-07T23:35:11.1361328Z",
"windowsDefenderAVThreatName": null,
"size": 391680,
"fileType": "PortableExecutable",
"isPeFile": true,
"filePublisher": null,
"fileProductName": null,
"signer": null,
"issuer": null,
"signerHash": null,
"isValidCertificate": null
}
```

101
windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,101 @@
---
title: Get file related alerts API
description: Retrieves a collection of alerts related to a given file hash.
keywords: apis, graph api, supported apis, get, file, hash
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get file related alerts API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of alerts related to a given file hash.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alert.Read.All | 'Read all alerts'
Application | Alert.ReadWrite.All | 'Read and write all alerts'
## HTTP request
```
GET /api/files/{id}/alerts
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and file and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body.
If file or alerts do not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/alerts
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"value": [
{
"id": "636692391408655573_2010598859",
"severity": "Low",
"status": "New",
"description": "test alert",
"recommendedAction": "do this and that",
"alertCreationTime": "2018-08-07T11:45:40.0199932Z",
"category": "None",
"title": "test alert",
"threatFamilyName": null,
"detectionSource": "CustomerTI",
"classification": null,
"determination": null,
"assignedTo": null,
"resolvedTime": null,
"lastEventTime": "2018-08-03T16:45:21.7115182Z",
"firstEventTime": "2018-08-03T16:45:21.7115182Z",
"actorName": null,
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07"
}
]
}
```

119
windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,119 @@
---
title: Get file related machines API
description: Retrieves a collection of machines related to a given file hash.
keywords: apis, graph api, supported apis, get, machines, hash
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get file related machines API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of machines related to a given file hash.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/files/{id}/machines
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and file and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body.
If file or machines do not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/files/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/machines
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "172.17.230.209",
"lastExternalIpAddress": "167.220.196.71",
"agentVersion": "10.5830.18209.1001",
"groupName": null,
"osBuild": 18209,
"healthStatus": "Active",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 140,
"riskScore": "Low",
"aadDeviceId": null
},
{
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
"computerDnsName": "mymachine2.contoso.com",
"firstSeen": "2018-07-09T13:22:45.1250071Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "192.168.12.225",
"lastExternalIpAddress": "79.183.65.82",
"agentVersion": "10.5820.17724.1000",
"groupName": "WDATPClientTeam",
"osBuild": 17724,
"healthStatus": "Inactive",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 140,
"riskScore": "Low",
"aadDeviceId": null
}
]
}
```

87
windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,87 @@
---
title: Get file statistics API
description: Retrieves the prevalence for the given file.
keywords: apis, graph api, supported apis, get, file, statistics
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get file statistics API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves the prevalence for the given file.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | File.Read.All | 'Read file profiles'
## HTTP request
```
GET /api/files/{id}/stats
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and file exists - 200 OK with statistical data in the body.
If file do not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/stats
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgFileStats",
"sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1",
"orgPrevalence": "3",
"orgFirstSeen": "2018-07-15T06:13:59Z",
"orgLastSeen": "2018-08-03T16:45:21Z",
"topFileNames": [
"chrome_1.exe",
"chrome_2.exe"
]
}
```

102
windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,102 @@
---
title: Get IP related alerts API
description: Retrieves a collection of alerts related to a given IP address.
keywords: apis, graph api, supported apis, get, ip, related, alerts
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get IP related alerts API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of alerts related to a given IP address.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alert.Read.All | 'Read all alerts'
Application | Alert.ReadWrite.All | 'Read and write all alerts'
## HTTP request
```
GET /api/ips/{ip}/alerts
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and IP and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body.
If IP and alerts do not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/alerts
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"value": [
{
"id": "636692391408655573_2010598859",
"severity": "Low",
"status": "New",
"description": "test alert",
"recommendedAction": "do this and that",
"alertCreationTime": "2018-08-07T11:45:40.0199932Z",
"category": "None",
"title": "test alert",
"threatFamilyName": null,
"detectionSource": "CustomerTI",
"classification": null,
"determination": null,
"assignedTo": null,
"resolvedTime": null,
"lastEventTime": "2018-08-03T16:45:21.7115182Z",
"firstEventTime": "2018-08-03T16:45:21.7115182Z",
"actorName": null,
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07"
}
]
}
```

116
windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,116 @@
---
title: Get IP related machines API
description: Retrieves a collection of machines related to a given IP address.
keywords: apis, graph api, supported apis, get, ip, related, machines
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get IP related machines API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of machines that communicated with or from a particular IP.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/ips/{ip}/machines
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and IP and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body.
If IP or machines do not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/machines
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "172.17.230.209",
"lastExternalIpAddress": "167.220.196.71",
"agentVersion": "10.5830.18209.1001",
"groupName": null,
"osBuild": 18209,
"healthStatus": "Active",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 140,
"riskScore": "Low",
"aadDeviceId": null
},
{
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
"computerDnsName": "mymachine2.contoso.com",
"firstSeen": "2018-07-09T13:22:45.1250071Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "192.168.12.225",
"lastExternalIpAddress": "79.183.65.82",
"agentVersion": "10.5820.17724.1000",
"groupName": "WDATPClientTeam",
"osBuild": 17724,
"healthStatus": "Inactive",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 140,
"riskScore": "Low",
"aadDeviceId": null
}
]
}
```

3
windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md
View File

@ -36,8 +36,7 @@ Content type | application/json
Empty Empty
## Response ## Response
If successful and IP and machines exists - 200 OK. If successful and IP and machines exists - 200 OK. If IP or machines do not exist - 404 Not Found.
If IP or machines do not exist - 404 Not Found.
## Example ## Example

79
windows/security/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,79 @@
---
title: Get IP statistics API
description: Retrieves the prevalence for the given IP.
keywords: apis, graph api, supported apis, get, ip, statistics, prevalence
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get IP statistics API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves the prevalence for the given IP.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Ip.Read.All | 'Read IP address profiles'
## HTTP request
```
GET /api/ips/{ip}/stats
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and ip exists - 200 OK with statistical data in the body. IP do not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/stats
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgIPStats",
"ipAddress": "10.209.67.177",
"orgPrevalence": "63515",
"orgFirstSeen": "2017-07-30T13:36:06Z",
"orgLastSeen": "2017-08-29T13:32:59Z"
}
```

95
windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,95 @@
---
title: Get machine by ID API
description: Retrieves a machine entity by ID.
keywords: apis, graph api, supported apis, get, machines, entity, id
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get machine by ID API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a machine entity by ID.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/machines/{id}
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and machine exists - 200 OK with the [machine](machine-windows-defender-advanced-threat-protection-new.md) entity in the body.
If machine with the specified id was not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machine",
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "172.17.230.209",
"lastExternalIpAddress": "167.220.196.71",
"agentVersion": "10.5830.18209.1001",
"groupName": null,
"osBuild": 18209,
"healthStatus": "Active",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 140,
"riskScore": "Low",
"aadDeviceId": null
}
```

101
windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,101 @@
---
title: Get machine log on users API
description: Retrieves a collection of logged on users.
keywords: apis, graph api, supported apis, get, machine, log on, users
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get machine log on users API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of logged on users.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | User.Read.All | 'Read user profiles'
## HTTP request
```
GET /api/machines/{id}/logonusers
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and machine and user exist - 200 OK with list of [user](user-windows-defender-advanced-threat-protection-new.md) entities in the body
If no machine found or no users found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/logonusers
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users",
"value": [
{
"id": "contoso\\user1",
"firstSeen": "2018-08-02T00:00:00Z",
"lastSeen": "2018-08-04T00:00:00Z",
"mostPrevalentMachineId": null,
"leastPrevalentMachineId": null,
"logonTypes": "Network",
"logOnMachinesCount": 3,
"isDomainAdmin": false,
"isOnlyNetworkUser": null
},
{
"id": "contoso\\user2",
"firstSeen": "2018-08-02T00:00:00Z",
"lastSeen": "2018-08-05T00:00:00Z",
"mostPrevalentMachineId": null,
"leastPrevalentMachineId": null,
"logonTypes": "Network",
"logOnMachinesCount": 3,
"isDomainAdmin": false,
"isOnlyNetworkUser": null
}
]
}
```

99
windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,99 @@
---
title: Get machine related alerts API
description: Retrieves a collection of alerts related to a given machine ID.
keywords: apis, graph api, supported apis, get, machines, related, alerts
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get machine related alerts API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of alerts related to a given machine ID.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alert.Read.All | 'Read all alerts'
Application | Alert.ReadWrite.All | 'Read and write all alerts'
## HTTP request
```
GET /api/machines/{id}/alerts
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and machine and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body. If no machine or no alerts found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/alerts
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"value": [
{
"id": "636692391408655573_2010598859",
"severity": "Low",
"status": "New",
"description": "test alert",
"recommendedAction": "do this and that",
"alertCreationTime": "2018-08-07T11:45:40.0199932Z",
"category": "None",
"title": "test alert",
"threatFamilyName": null,
"detectionSource": "CustomerTI",
"classification": null,
"determination": null,
"assignedTo": null,
"resolvedTime": null,
"lastEventTime": "2018-08-03T16:45:21.7115182Z",
"firstEventTime": "2018-08-03T16:45:21.7115182Z",
"actorName": null,
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07"
}
]
}
```

86
windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,86 @@
---
title: Get MachineAction object API
description: Use this API to create calls related to get machineaction object
keywords: apis, graph api, supported apis, machineaction object
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get machineAction API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Get action performed on a machine.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/machineactions/{id}
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful, this method returns 200, Ok response code with a [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity. If machine action entity with the specified id was not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/machineactions/2e9da30d-27f6-4208-81f2-9cd3d67893ba
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 Ok
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan",
"requestor": "Analyst@contoso.com",
"requestorComment": "Check machine for viruses due to alert 3212",
"status": "Succeeded",
"error": "None",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2017-12-04T12:18:57.5511934Z"
}
```

159
windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,159 @@
---
title: List machineActions API
description: Use this API to create calls related to get machineactions collection
keywords: apis, graph api, supported apis, machineaction collection
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# List machineActions API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Gets collection of actions done on machines. Get MachineAction collection API supports [OData V4 queries](https://www.odata.org/documentation/odata-version-2-0/uri-conventions/#FilterSystemQueryOption).
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/machineactions
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful, this method returns 200, Ok response code with a collection of [machineAction](machineaction-windows-defender-advanced-threat-protection-new.md) entities.
## Example 1
**Request**
Here is an example of the request on an organization that has three MachineActions.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/machineactions
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 Ok
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions",
"value": [
{
"id": "69dc3630-1ccc-4342-acf3-35286eec741d",
"type": "CollectInvestigationPackage",
"requestor": "Analyst@contoso.com",
"requestorComment": "test",
"status": "Succeeded",
"error": "None",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"creationDateTimeUtc": "2017-12-04T12:43:57.2011911Z",
"lastUpdateTimeUtc": "2017-12-04T12:45:25.4049122Z"
},
{
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan",
"requestor": "Analyst@contoso.com",
"requestorComment": "Check machine for viruses due to alert 3212",
"status": "Succeeded",
"error": "None",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2017-12-04T12:18:57.5511934Z"
},
{
"id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e",
"type": "UnrestrictCodeExecution",
"requestor": "Analyst@contoso.com",
"requestorComment": "test",
"status": "Succeeded",
"error": "None",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"creationDateTimeUtc": "2017-12-04T12:15:40.6052029Z",
"lastUpdateTimeUtc": "2017-12-04T12:16:14.2899973Z"
}
]
}
```
## Example 2
**Request**
Here is an example of a request that filters the MachineActions by machine ID and shows the latest two MachineActions.
```
GET https://api.securitycenter.windows.com/api/machineactions?$filter=machineId eq 'f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f'&$top=2
```
**Response**
Here is an example of the response.
[!include[Improve request performance](improverequestperformance-new.md)]
```
HTTP/1.1 200 Ok
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/testwdatppreview/$metadata#MachineActions",
"value": [
{
"id": "69dc3630-1ccc-4342-acf3-35286eec741d",
"type": "CollectInvestigationPackage",
"requestor": "Analyst@contoso.com",
"requestorComment": "test",
"status": "Succeeded",
"error": "None",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"creationDateTimeUtc": "2017-12-04T12:43:57.2011911Z",
"lastUpdateTimeUtc": "2017-12-04T12:45:25.4049122Z"
},
{
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan",
"requestor": "Analyst@contoso.com",
"requestorComment": "Check machine for viruses due to alert 3212",
"status": "Succeeded",
"error": "None",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2017-12-04T12:18:57.5511934Z"
}
]
}
```

115
windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,115 @@
---
title: List machines API
description: Retrieves a collection of recently seen machines.
keywords: apis, graph api, supported apis, get, machines
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# List machines API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of machines that have communicated with WDATP cloud on the last 30 days.
## Permissions
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/machines
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. If no recent machines - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/machines
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "172.17.230.209",
"lastExternalIpAddress": "167.220.196.71",
"agentVersion": "10.5830.18209.1001",
"groupName": null,
"osBuild": 18209,
"healthStatus": "Active",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 140,
"riskScore": "Low",
"aadDeviceId": null
},
{
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
"computerDnsName": "mymachine2.contoso.com",
"firstSeen": "2018-07-09T13:22:45.1250071Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "192.168.12.225",
"lastExternalIpAddress": "79.183.65.82",
"agentVersion": "10.5820.17724.1000",
"groupName": "WDATPClientTeam",
"osBuild": 17724,
"healthStatus": "Inactive",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 140,
"riskScore": "Low",
"aadDeviceId": null
}
]
}
```

80
windows/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,80 @@
---
title: Get package SAS URI API
description: Use this API to get a URI that allows downloading an investigation package.
keywords: apis, graph api, supported apis, get package, sas, uri
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get package SAS URI API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Get a URI that allows downloading of an [investigation package](collect-investigation-package-windows-defender-advanced-threat-protection-new.md).
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.CollectForensics | 'Collect forensics'
## HTTP request
```
GET /api/machineactions/{machine action id}/getPackageUri
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful, this method returns 200, Ok response code with object that holds the link to the package in the “value” parameter. This link is valid for a very short time and should be used immediately for downloading the package to a local storage.
## Example
**Request**
Here is an example of the request.
```
GET https://api.securitycenter.windows.com/api/machineactions/7327b54fd718525cbca07dacde913b5ac3c85673/GetPackageUri
```
**Response**
Here is an example of the response.
[!include[Improve request performance](improverequestperformance-new.md)]
```
HTTP/1.1 200 Ok
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Edm.String",
"value": "\"https://userrequests-us.securitycenter.windows.com:443/safedownload/WDATP_Investigation_Package.zip?token=gbDyj7y%2fbWGAZjn2sFiZXlliBTXOCVG7yiJ6mXNaQ9pLByC2Wxeno9mENsPFP3xMk5l%2bZiJXjLvqAyNEzUNROxoM2I1er9dxzfVeBsxSmclJjPsAx%2btiNyxSz1Ax%2b5jaT5cL5bZg%2b8wgbwY9urXbTpGjAKh6FB1e%2b0ypcWkPm8UkfOwsmtC%2biZJ2%2bPqnkkeQk7SKMNoAvmh9%2fcqDIPKXGIBjMa0D9auzypOqd8bQXp7p2BnLSH136BxST8n9IHR4PILvRjAYW9kvtHkBpBitfydAsUW4g2oDZSPN3kCLBOoo1C4w4Lkc9Bc3GNU2IW6dfB7SHcp7G9p4BDkeJl3VuDs6esCaeBorpn9FKJ%2fXo7o9pdcI0hUPZ6Ds9hiPpwPUtz5J29CBE3QAopCK%2fsWlf6OW2WyXsrNRSnF1tVE5H3wXpREzuhD7S4AIA3OIEZKzC4jIPLeMu%2bazZU9xGwuc3gICOaokbwMJiZTqcUuK%2fV9YdBdjdg8wJ16NDU96Pl6%2fgew2KYuk6Wo7ZuHotgHI1abcsvdlpe4AvixDbqcRJthsg2PpLRaFLm5av44UGkeK6TJpFvxUn%2f9fg6Zk5yM1KUTHb8XGmutoCM8U9er6AzXZlY0gGc3D3bQOg41EJZkEZLyUEbk1hXJB36ku2%2bW01cG71t7MxMBYz7%2bdXobxpdo%3d%3bRWS%2bCeoDfTyDcfH5pkCg6hYDmCOPr%2fHYQuaUWUBNVnXURYkdyOzVHqp%2fe%2f1BNyPdVoVkpQHpz1pPS3b5g9h7IMmNKCk5gFq5m2nPx6kk9EYtzx8Ndoa2m9Yj%2bSaf8zIFke86YnfQL4AYewsnQNJJh4wc%2bXxGlBq7axDcoiOdX91rKzVicH3GSBkFoLFAKoegWWsF%2fEDZcVpF%2fXUA1K8HvB6dwyfy4y0sAqnNPxYTQ97mG7yHhxPt4Pe9YF2UPPAJVuEf8LNlQ%2bWHC9%2f7msF6UUI4%2fca%2ftpjFs%2fSNeRE8%2fyQj21TI8YTF1SowvaJuDc1ivEoeopNNGG%2bGI%2fX0SckaVxU9Hdkh0zbydSlT5SZwbSwescs0IpzECitBbaLUz4aT8KTs8T0lvx8D7Te3wVsKAJ1r3iFMQZrlk%2bS1WW8rvac7oHRx2HKURn1v7fDIQWgJr9aNsNlFz4fLJ50T2qSHuuepkLVbe93Va072aMGhvr09WVKoTpAf1j2bcFZZU6Za5PxI32mr0k90FgiYFJ1F%2f1vRDrGwvWVWUkR3Z33m4g0gHa52W1FMxQY0TJIwbovD6FaSNDx7xhKZSd5IJ7r6P91Gez49PaZRcAZPjd%2bfbul3JNm1VqQPTLohT7wa0ymRiXpSST74xtFzuEBzNSNATdbngj3%2fwV4JesTjZjIj5Dc%3d%3blumqauVlFuuO8MQffZgs0tLJ4Fq6fpeozPTdDf8Ll6XLegi079%2b4mSPFjTK0y6eohstxdoOdom2wAHiZwk0u4KLKmRkfYOdT1wHY79qKoBQ3ZDHFTys9V%2fcwKGl%2bl8IenWDutHygn5IcA1y7GTZj4g%3d%3d\""
}
```

85
windows/security/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,85 @@
---
title: Get user information API
description: Retrieve a User entity by key such as user name or domain.
keywords: apis, graph api, supported apis, get, user, user information
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get user information API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieve a User entity by key (user name or domain\user).
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | User.Read.All | 'Read all user profiles'
## HTTP request
```
GET /api/users/{id}/
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and user exists - 200 OK with [user](user-windows-defender-advanced-threat-protection-new.md) entity in the body. If user does not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/users/user1@contoso.com
Content-type: application/json
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users/$entity",
"id": "user1@contoso.com",
"firstSeen": "2018-08-02T00:00:00Z",
"lastSeen": "2018-08-04T00:00:00Z",
"mostPrevalentMachineId": null,
"leastPrevalentMachineId": null,
"logonTypes": "Network",
"logOnMachinesCount": 3,
"isDomainAdmin": false,
"isOnlyNetworkUser": null
}
```

118
windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,118 @@
---
title: Get user related alerts API
description: Retrieves a collection of alerts related to a given user ID.
keywords: apis, graph api, supported apis, get, user, related, alerts
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get user related alerts API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of alerts related to a given user ID.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alert.Read.All | 'Read all alerts'
Application | Alert.ReadWrite.All | 'Read and write all alerts'
## HTTP request
```
GET /api/users/{id}/alerts
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and user and alert exists - 200 OK. If user or alerts does not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/users/user1@contoso.com/alerts
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"value": [
{
"id": "636688558380765161_2136280442",
"severity": "Informational",
"status": "InProgress",
"description": "Some alert description 1",
"recommendedAction": "Some recommended action 1",
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
"category": "General",
"title": "Some alert title 1",
"threatFamilyName": null,
"detectionSource": "WindowsDefenderAtp",
"classification": "TruePositive",
"determination": null,
"assignedTo": "best secop ever",
"resolvedTime": null,
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
"actorName": null,
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
},
{
"id": "636688558380765161_2136280442",
"severity": "Informational",
"status": "InProgress",
"description": "Some alert description 2",
"recommendedAction": "Some recommended action 2",
"alertCreationTime": "2018-08-04T01:17:17.9516179Z",
"category": "General",
"title": "Some alert title 2",
"threatFamilyName": null,
"detectionSource": "WindowsDefenderAtp",
"classification": "TruePositive",
"determination": null,
"assignedTo": "best secop ever",
"resolvedTime": null,
"lastEventTime": "2018-08-03T07:02:52.0894451Z",
"firstEventTime": "2018-08-03T07:02:52.0894451Z",
"actorName": null,
"machineId": "ff0c3800ed8d66738a514971cd6867166809369d"
}
]
}
```

116
windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,116 @@
---
title: Get user related machines API
description: Retrieves a collection of machines related to a given user ID.
keywords: apis, graph api, supported apis, get, user, user related alerts
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Get user related machines API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of machines related to a given user ID.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Read.All | 'Read all machine profiles'
Application | Machine.ReadWrite.All | 'Read and write all machine information'
## HTTP request
```
GET /api/users/{id}/machines
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. If user or machines does not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/users/user1@contoso.com/machines
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "172.17.230.209",
"lastExternalIpAddress": "167.220.196.71",
"agentVersion": "10.5830.18209.1001",
"groupName": null,
"osBuild": 18209,
"healthStatus": "Active",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 140,
"riskScore": "Low",
"aadDeviceId": null
},
{
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
"computerDnsName": "mymachine2.contoso.com",
"firstSeen": "2018-07-09T13:22:45.1250071Z",
"osPlatform": "Windows10",
"osVersion": null,
"systemProductName": null,
"lastIpAddress": "192.168.12.225",
"lastExternalIpAddress": "79.183.65.82",
"agentVersion": "10.5820.17724.1000",
"groupName": "WDATPClientTeam",
"osBuild": 17724,
"healthStatus": "Inactive",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 140,
"riskScore": "Low",
"aadDeviceId": null
}
]
}
```

9
windows/security/threat-protection/windows-defender-atp/improverequestperformance-new.md Normal file
View File

@ -0,0 +1,9 @@
---
ms.date: 08/28/2017
author: zavidor
---
>[!NOTE]
>For better performance, you can use server closer to your geo location:
> - api-us.securitycenter.windows.com
> - api-eu.securitycenter.windows.com
> - api-uk.securitycenter.windows.com

76
windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,76 @@
---
title: Is domain seen in org API
description: Use this API to create calls related to checking whether a domain was seen in the organization.
keywords: apis, graph api, supported apis, domain, domain seen
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 04/24/2018
---
# Was domain seen in org
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Answers whether a domain was seen in the organization.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Url.Read.All | 'Read URLs'
## HTTP request
```
GET /api/domains/{domain}
```
## Request headers
Header | Value
:---|:---
Authorization | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and domain exists - 200 OK. If domain does not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/domains/example.com
Content-type: application/json
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Domains/$entity",
"host": "example.com"
}
```

76
windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,76 @@
---
title: Is IP seen in org API
description: Answers whether an IP was seen in the organization.
keywords: apis, graph api, supported apis, is, ip, seen, org, organization
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Was IP seen in org
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Answers whether an IP was seen in the organization.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Ip.Read.All | 'Read IP address profiles'
## HTTP request
```
GET /api/ips/{ip}
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and IP exists - 200 OK. If IP do not exist - 404 Not Found.
## Example
**Request**
Here is an example of the request.
```
GET https://api.securitycenter.windows.com/api/ips/10.209.67.177
```
**Response**
Here is an example of the response.
[!include[Improve request performance](improverequestperformance-new.md)]
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Ips/$entity",
"id": "10.209.67.177"
}
```

101
windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,101 @@
---
title: Isolate machine API
description: Use this API to create calls related isolating a machine.
keywords: apis, graph api, supported apis, isolate machine
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Isolate machine API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Isolates a machine from accessing external network.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Isolate | 'Isolate machine'
## HTTP request
```
POST /api/machines/{id}/isolate
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | string | application/json. **Required**.
## Request body
In the request body, supply a JSON object with the following parameters:
Parameter | Type | Description
:---|:---|:---
Comment | String | Comment to associate with the action. **Required**.
IsolationType | String | Type of the isolation. Allowed values are: 'Full' or 'Selective'.
**IsolationType** controls the type of isolation to perform and can be one of the following:
- Full – Full isolation
- Selective – Restrict only limited set of applications from accessing the network
## Response
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/isolate
Content-type: application/json
{
"Comment": "Isolate machine due to alert 1234",
“IsolationType”: “Full”
}
```
**Response**
Here is an example of the response.
```
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
"id": "b89eb834-4578-496c-8be0-03f004061435",
"type": "Isolate",
"requestor": "Analyst@contoso.com ",
"requestorComment": "Isolate machine due to alert 1234",
"status": "InProgress",
"error": "None",
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"creationDateTimeUtc": "2017-12-04T12:12:18.9725659Z",
"lastUpdateTimeUtc": "2017-12-04T12:12:18.9725659Z"
}
```
To unisolate a machine, see [Release machine from isolation](unisolate-machine-windows-defender-advanced-threat-protection-new.md).

45
windows/security/threat-protection/windows-defender-atp/machine-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,45 @@
---
title: machine resource type
description: Retrieves top machines.
keywords: apis, supported apis, get, machines
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# machine resource type
# Methods
Method|Return Type |Description
:---|:---|:---
[List machines](get-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | List set of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the org.
[Get machine](get-machine-by-id-windows-defender-advanced-threat-protection.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) | Get a [machine](machine-windows-defender-advanced-threat-protection-new.md) by its identity.
[Get logged on users](get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md) | [user](user-windows-defender-advanced-threat-protection-new.md) collection | Get the set of [User](user-windows-defender-advanced-threat-protection-new.md) that logged on to the [machine](machine-windows-defender-advanced-threat-protection-new.md).
[Get related alerts](get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | Get the set of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities that were raised on the [machine](machine-windows-defender-advanced-threat-protection-new.md).
# Properties
Property | Type | Description
:---|:---|:---
id | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) identity.
computerDnsName | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) fully qualified name.
firstSeen | DateTimeOffset | First date and time where the [machine](machine-windows-defender-advanced-threat-protection-new.md) was observed by WDATP.
osPlatform | String | OS platform.
osVersion | String | OS Version.
lastIpAddress | Ip | Last IP on local NIC on the [machine](machine-windows-defender-advanced-threat-protection-new.md).
lastExternalIpAddress | Ip | Last IP through which the [machine](machine-windows-defender-advanced-threat-protection-new.md) accessed the internet.
agentVersion | String | Version of WDATP agent.
groupName | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) group name (when defined).
osBuild | Int | OS build number.
healthStatus | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) health status.
isAadJoined | Boolean | Is [machine](machine-windows-defender-advanced-threat-protection-new.md) AAD joined.
machineTags | String collection | Set of [machine](machine-windows-defender-advanced-threat-protection-new.md) tags.
rbacGroupId | Int | Group ID.
riskScore | String | Risk score as evaludated by WDATP. Possible values are: 'None', 'Low', 'Medium' and 'High'.
aadDeviceId | String | AAD Device ID (when [machine](machine-windows-defender-advanced-threat-protection-new.md) is Aad Joined).

42
windows/security/threat-protection/windows-defender-atp/machineaction-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,42 @@
---
title: machineAction resource type
description: Retrieves top recent machineActions.
keywords: apis, supported apis, get, machineaction, recent
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# MachineAction resource type
Method|Return Type |Description
:---|:---|:---
[List MachineActions](get-machineactions-collection-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | List [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entities.
[Get MachineAction](get-machineaction-object-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Get a single [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity.
[Collect investigation package](collect-investigation-package-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Collect investigation package from a [machine](machine-windows-defender-advanced-threat-protection-new.md).
[Get investigation package SAS URI](get-package-sas-uri-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Get URI for downloading the investigation package.
[Isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Isolate [machine](machine-windows-defender-advanced-threat-protection-new.md) from network.
[Release machine from isolation](unisolate-machine-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Release [machine](machine-windows-defender-advanced-threat-protection-new.md) from Isolation.
[Restrict app execution](restrict-code-execution-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Restrict application execution.
[Remove app restriction](unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Remove application execution restriction.
[Run antivirus scan](run-av-scan-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Run an AV scan using Windows Defender (when applicable).
[Offboard machine](offboard-machine-api-windows-defender-advanced-threat-protection-new.md)|[Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Offboard [machine](machine-windows-defender-advanced-threat-protection-new.md) from WDATP.
# Properties
Property | Type | Description
:---|:---|:---
id | Guid | Identity of the [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity.
type | String | Type of the action.
requestor | String | Identity of the person that executed the action.
requestorComment | String | Comment that was written when issuing the action.
status | String | Current status of the command. Possible values are: "InProgress", "Succeeded", "Failed" and "Cancelled".
error | String | Error code providing more insight as to what have caused the command to fail.
machineId | String | Id of the machine on which the action was executed.
creationDateTimeUtc | DateTimeOffset | The date and time when the action was created.
lastUpdateTimeUtc | DateTimeOffset | The last date and time when the action status was updated.

92
windows/security/threat-protection/windows-defender-atp/offboard-machine-api-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,92 @@
---
title: Offboard machine API
description: Use this API to offboard a machine from WDATP.
keywords: apis, graph api, supported apis, collect investigation package
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Offboard machine API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Offboard machine from WDATP.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Offboard | 'Offboard machine'
## HTTP request
```
POST /api/machines/{id}/offboard
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | string | application/json. **Required**.
## Request body
In the request body, supply a JSON object with the following parameters:
Parameter | Type | Description
:---|:---|:---
Comment | String | Comment to associate with the action. **Required**.
## Response
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/offboard
Content-type: application/json
{
"Comment": "Offboard machine by automation"
}
```
**Response**
Here is an example of the response.
```
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
"id": "c9042f9b-8483-4526-87b5-35e4c2532223",
"type": "OffboardMachine",
"requestor": "Analyst@contoso.com",
"requestorComment": "offboard machine by automation",
"status": "InProgress",
"error": "None",
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"creationDateTimeUtc": "2017-12-04T12:09:24.1785079Z",
"lastUpdateTimeUtc": "2017-12-04T12:09:24.1785079Z"
}
```

95
windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,95 @@
---
title: Restrict app execution API
description: Use this API to create calls related to restricting an application from executing.
keywords: apis, graph api, supported apis, collect investigation package
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Restrict app execution API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Restrict execution of all applications on the machine except a predefined set (see [Response machine alerts](respond-machine-alerts-windows-defender-advanced-threat-protection.md) for more information)
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.RestrictExecution | 'Restrict code execution'
## HTTP request
```
POST /api/machines/{id}/restrictCodeExecution
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | string | application/json. **Required**.
## Request body
In the request body, supply a JSON object with the following parameters:
Parameter | Type | Description
:---|:---|:---
Comment | String | Comment to associate with the action. **Required**.
## Response
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
## Example
**Request**
Here is an example of the request.
```
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/restrictCodeExecution
Content-type: application/json
{
"Comment": "Restrict code execution due to alert 1234"
}
```
**Response**
Here is an example of the response.
[!include[Improve request performance](improverequestperformance-new.md)]
```
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
"id": "78d408d1-384c-4c19-8b57-ba39e378011a",
"type": "RestrictCodeExecution",
"requestor": "Analyst@contoso.com ",
"requestorComment": "Restrict code execution due to alert 1234",
"status": "InProgress",
"error": "None",
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"creationDateTimeUtc": "2017-12-04T12:15:04.3825985Z",
"lastUpdateTimeUtc": "2017-12-04T12:15:04.3825985Z"
}
```
To remove code execution restriction from a machine, see [Remove app restriction](unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md).

101
windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,101 @@
---
title: Run antivirus scan API
description: Use this API to create calls related to running an antivirus scan on a machine.
keywords: apis, graph api, supported apis, remove machine from isolation
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Run antivirus scan API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Initiate Windows Defender Antivirus scan on a machine.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Scan | 'Scan machine'
## HTTP request
```
POST /api/machines/{id}/runAntiVirusScan
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | string | application/json
## Request body
In the request body, supply a JSON object with the following parameters:
Parameter | Type | Description
:---|:---|:---
Comment | String | Comment to associate with the action. **Required**.
ScanType| String | Defines the type of the Scan. **Required**.
**ScanType** controls the type of scan to perform and can be one of the following:
- **Quick** – Perform quick scan on the machine
- **Full** – Perform full scan on the machine
## Response
If successful, this method returns 201, Created response code and _MachineAction_ object in the response body.
## Example
**Request**
Here is an example of the request.
```
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runAntiVirusScan
Content-type: application/json
{
"Comment": "Check machine for viruses due to alert 3212",
“ScanType”: “Full”
}
```
**Response**
Here is an example of the response.
[!include[Improve request performance](improverequestperformance-new.md)]
```
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan",
"requestor": "Analyst@contoso.com",
"requestorComment": "Check machine for viruses due to alert 3212",
"status": "InProgress",
"error": "None",
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2017-12-04T12:18:27.1293487Z"
}
```

99
windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,99 @@
---
title: Release machine from isolation API
description: Use this API to create calls related to release a machine from isolation.
keywords: apis, graph api, supported apis, remove machine from isolation
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Release machine from isolation API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Undo isolation of a machine.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.Isolate | 'Isolate machine'
## HTTP request
```
POST /api/machines/{id}/unisolate
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | string | application/json. **Required**.
## Request body
In the request body, supply a JSON object with the following parameters:
Parameter | Type | Description
:---|:---|:---
Comment | String | Comment to associate with the action. **Required**.
## Response
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/unisolate
Content-type: application/json
{
"Comment": "Unisolate machine since it was clean and validated"
}
```
**Response**
Here is an example of the response.
>[!NOTE]
>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.
```
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
"id": "09a0f91e-a2eb-409d-af33-5577fe9bd558",
"type": "Unisolate",
"requestor": "Analyst@contoso.com ",
"requestorComment": "Unisolate machine since it was clean and validated ",
"status": "InProgress",
"error": "None",
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"creationDateTimeUtc": "2017-12-04T12:13:15.0104931Z",
"lastUpdateTimeUtc": "2017-12-04T12:13:15.0104931Z"
}
```
To isolate a machine, see [Isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md).

94
windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,94 @@
---
title: Remove app restriction API
description: Use this API to create calls related to removing a restriction from applications from executing.
keywords: apis, graph api, supported apis, remove machine from isolation
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Remove app restriction API
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Enable execution of any application on the machine.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Machine.RestrictExecution | 'Restrict code execution'
## HTTP request
```
POST /api/machines/{id}/unrestrictCodeExecution
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | string | application/json. **Required**.
## Request body
In the request body, supply a JSON object with the following parameters:
Parameter | Type | Description
:---|:---|:---
Comment | String | Comment to associate with the action. **Required**.
## Response
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/unrestrictCodeExecution
Content-type: application/json
{
"Comment": "Unrestrict code execution since machine was cleaned and validated"
}
```
**Response**
Here is an example of the response.
```
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
"id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e",
"type": "UnrestrictCodeExecution",
"requestor": "Analyst@contoso.com",
"requestorComment": "Unrestrict code execution since machine was cleaned and validated ",
"status": "InProgress",
"error": "None",
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"creationDateTimeUtc": "2017-12-04T12:15:40.6052029Z",
"lastUpdateTimeUtc": "2017-12-04T12:15:40.6052029Z"
}
```
To restrict code execution on a machine, see [Restrict app execution](restrict-code-execution-windows-defender-advanced-threat-protection-new.md).

103
windows/security/threat-protection/windows-defender-atp/update-alert-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,103 @@
---
title: Get alert information by ID API
description: Retrieves an alert by its ID.
keywords: apis, graph api, supported apis, get, alert, information, id
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# Update alert
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Update the properties of an alert entity.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alerts.ReadWrite.All | 'Read and write all alerts'
## HTTP request
```
PATCH /api/alerts/{id}
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | String | application/json. **Required**.
## Request body
In the request body, supply the values for the relevant fields that should be updated.Existing properties that are not included in the request body will maintain their previous values or be recalculated based on tchanges to other property values. For best performance you shouldn't include existing values that haven't change.
Property | Type | Description
:---|:---|:---
status | String | Specifies the current status of the alert. The property values are: 'New', 'InProgress' and 'Resolved'.
assignedTo | String | Owner of the alert
classification | String | Speficies the specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'.
determination | String | Specifies the determination of the alert. The property values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other'
## Response
If successful, this method returns 200 OK, and the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entity in the response body with the updated properties. If alert with the specified id was not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
PATCH https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442
Content-Type: application/json
{
"assignedTo": "Our designated secop"
}
```
**Response**
Here is an example of the response.
```
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts/$entity",
"id": "636688558380765161_2136280442",
"severity": "Medium",
"status": "InProgress",
"description": "An anomalous memory operation appears to be tampering with a process associated with the Windows Defender EDR sensor.",
"recommendedAction": "A. Validate the alert.\n1. Examine the process involved in the memory operation to determine whether the process and the observed activities are normal. \n2. Check for other suspicious activities in the machine timeline.\n3. Locate unfamiliar processes in the process tree. Check files for prevalence, their locations, and digital signatures.\n4. Submit relevant files for deep analysis and review file behaviors. \n5. Identify unusual system activity with system owners. \n\nB. Scope the incident. Find related machines, network addresses, and files in the incident graph. \n\nC. Contain and mitigate the breach. Stop suspicious processes, isolate affected machines, decommission compromised accounts or reset passwords, block IP addresses and URLs, and install security updates.\n\nD. Contact your incident response team, or contact Microsoft support for investigation and remediation services.",
"alertCreationTime": "2018-08-07T10:18:04.2665329Z",
"category": "Installation",
"title": "Possible sensor tampering in memory",
"threatFamilyName": null,
"detectionSource": "WindowsDefenderAtp",
"classification": null,
"determination": null,
"assignedTo": "Our designated secop",
"resolvedTime": null,
"lastEventTime": "2018-08-07T10:14:35.470671Z",
"firstEventTime": "2018-08-07T10:14:35.470671Z",
"actorName": null,
"machineId": "a2250e1cd215af1ea2818ef8d01a564f67542857"
}
```

23
windows/security/threat-protection/windows-defender-atp/user-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,23 @@
---
title: File resource type
description: Retrieves top recent alerts.
keywords: apis, graph api, supported apis, get, alerts, recent
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
ms.sitesec: library
ms.pagetype: security
ms.author: macapara
author: mjcaparas
ms.localizationpriority: medium
ms.date: 12/08/2017
---
# User resource type
Method|Return Type |Description
:---|:---|:---
[List User related alerts](get-user-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | List all the alerts that are associated with a [user](user-windows-defender-advanced-threat-protection-new.md).
[List User related machines](get-user-related-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | List all the machines that were logged on by a [user](user-windows-defender-advanced-threat-protection-new.md).