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

Merge remote-tracking branch 'origin/atp-new-api' into atp-new-api

Browse Source
This commit is contained in:
Joey Caparas
2018-10-02 14:31:27 -07:00
parent 17b92af0cc 9426d979d4
commit e1ec5db9cc
28 changed files with 322 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
windows/security/threat-protection/TOC.md
View File

@ -319,6 +319,8 @@
######## [Get machine by ID](windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection-new.md)
######## [Get machine log on users](windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md)
######## [Get machine related alerts](windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md)
######## [Add or Remove machine tags](windows-defender-atp/add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md)
######## [Find machines by IP](windows-defender-atp/find-machines-by-ip-windows-defender-advanced-threat-protection-new.md)
####### [Machine Action](windows-defender-atp/machineaction-windows-defender-advanced-threat-protection-new.md)
######## [List MachineActions](windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md)
@ -345,7 +347,7 @@
####### Multiple APIs
######## [PowerShell](windows-defender-atp/exposed-apis-full-sample-powershell.md)
##### [Use the Windows Defender ATP exposed APIs](windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md)
##### [TO BE DEPRECATED - Use the Windows Defender ATP exposed APIs](windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md)
###### [Supported Windows Defender ATP APIs](windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md)
#######Actor
######## [Get actor information](windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md)
@ -415,7 +417,7 @@
##### TO BE DEPRECATED - API for custom alerts
##### API for custom alerts
###### [Enable the custom threat intelligence application](windows-defender-atp/enable-custom-ti-windows-defender-advanced-threat-protection.md)
###### [TO BE DEPRECATED Use the Windows Defender ATP exposed APIs](windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md)
####### [Use the threat intelligence API to create custom alerts](windows-defender-atp/use-custom-ti-windows-defender-advanced-threat-protection.md)

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

@ -316,6 +316,8 @@
####### [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)
####### [Add or Remove machine tags](add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md)
####### [Find machines by IP](find-machines-by-ip-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)
@ -342,7 +344,7 @@
###### Multiple APIs
####### [PowerShell](exposed-apis-full-sample-powershell.md)
#### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md)
#### [TO BE DEPRECATED - Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md)
##### [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection.md)
######Actor
####### [Get actor information](get-actor-information-windows-defender-advanced-threat-protection.md)

106
windows/security/threat-protection/windows-defender-atp/add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,106 @@
---
title: Add or Remove Machine Tags API
description: Use this API to Add or Remove machine tags.
keywords: apis, graph api, supported apis, tags, machine tags
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
---
# Add or Remove Machine Tags API
[!include[Prerelease information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
- Adds or remove tag to a specific 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.ReadWrite.All | 'Read and write all machine information'
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
## HTTP request
```
POST https://api.securitycenter.windows.com/api/machines/{id}/tags
```
## 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
:---|:---|:---
Value | String | The tag name. **Required**.
Action | Enum | Add or Remove. Allowed values are: 'Add' or 'Remove'. **Required**.
## Response
If successful, this method returns 200 - Ok response code and the updated Machine in the response body.
## Example
**Request**
Here is an example of a request that adds machine tag.
[!include[Improve request performance](improverequestperformance-new.md)]
```
POST https://api.securitycenter.windows.com/api/machines/863fed4b174465c703c6e412965a31b5e1884cc4/tags
Content-type: application/json
{
"Value" : "Test Tag",
"Action": "Add"
}
```
**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/$entity",
"id": "863fed4b174465c703c6e412965a31b5e1884cc4",
"computerDnsName": "mymachine55.contoso.com",
"firstSeen": "2018-07-31T14:20:55.8223496Z",
"lastSeen": "2018-09-27T08:44:05.6228836Z",
"osPlatform": "Windows10",
"osVersion": null,
"lastIpAddress": "10.248.240.38",
"lastExternalIpAddress": "167.220.2.166",
"agentVersion": "10.3720.16299.98",
"osBuild": 16299,
"healthStatus": "Active",
"isAadJoined": true,
"machineTags": [
"Test Tag"
],
"rbacGroupId": 75,
"riskScore": "Medium",
"aadDeviceId": null
}
```
To remove machine tag, set the Action to 'Remove' instead of 'Add' in the request body.

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

@ -31,9 +31,12 @@ Permission type | Permission | Permission display name
Application | Machine.CollectForensics | 'Collect forensics'
Delegated (work or school account) | Machine.CollectForensics | 'Collect forensics'
>[!IMPORTANT]
> This response action is available for machines on Windows 10, version 1703 or later.
## HTTP request
```
POST /api/machines/{id}/collectInvestigationPackage
POST https://api.securitycenter.windows.com/api/machines/{id}/collectInvestigationPackage
```
## Request headers
@ -84,10 +87,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:09:24.1785079Z",
"lastUpdateTimeUtc": "2018-12-04T12:09:24.1785079Z",
"relatedFileInfo": null
}
```

100
windows/security/threat-protection/windows-defender-atp/find-machines-by-ip-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,100 @@
---
title: Find machines by internal IP API
description: Find machines seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp
keywords: apis, graph api, supported apis, get, machine, IP, find, find machine, by ip, 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
---
# Find machines by internal IP API
[!include[Prerelease<73>information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
- Find machines seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp
- The given timestamp must be in the past 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'
Delegated (work or school account) | Machine.Read | 'Read machine information'
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
## HTTP request
```
GET /api/machines/findbyip(ip='{IP}',timestamp={TimeStamp})
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and machines were found - 200 OK with list of the machines in the response body.
If no machine found - 404 Not Found.
If the timestamp is not in the past 30 days - 400 Bad Request.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
GET https://api.securitycenter.windows.com/api/machines/findbyip(ip='10.248.240.38',timestamp=2018-09-22T08:44:05Z)
```
**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": "863fed4b174465c703c6e412965a31b5e1884cc4",
"computerDnsName": "mymachine33.contoso.com",
"firstSeen": "2018-07-31T14:20:55.8223496Z",
"lastSeen": null,
"osPlatform": "Windows10",
"osVersion": null,
"lastIpAddress": "10.248.240.38",
"lastExternalIpAddress": "167.220.2.166",
"agentVersion": "10.3720.16299.98",
"osBuild": 16299,
"healthStatus": "Active",
"isAadJoined": true,
"machineTags": [],
"rbacGroupId": 75,
"riskScore": "Medium",
"aadDeviceId": null
}
]
}
```

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

@ -76,13 +76,13 @@ Content-type: application/json
"id": "ff0c3800ed8d66738a514971cd6867166809369f",
"computerDnsName": "amazingmachine.contoso.com",
"firstSeen": "2017-12-10T07:47:34.4269783Z",
"lastSeen": "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,

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

@ -78,13 +78,13 @@ Content-type: application/json
"id": "02ea9a24e8bd39c247ed7ca0edae879c321684e5",
"computerDnsName": "testMachine1",
"firstSeen": "2018-07-30T20:12:00.3708661Z",
"lastSeen": "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,
@ -97,13 +97,13 @@ Content-type: application/json
"id": "02efb9a9b85f07749a018fbf3f962b4700b3b949",
"computerDnsName": "testMachine2",
"firstSeen": "2018-07-30T19:50:47.3618349Z",
"lastSeen": "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,

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

@ -79,13 +79,13 @@ Content-type: application/json
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"lasttSeen": "2018-07-09T13:22:45.1250071Z",
"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,
@ -98,13 +98,13 @@ Content-type: application/json
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
"computerDnsName": "mymachine2.contoso.com",
"firstSeen": "2018-07-09T13:22:45.1250071Z",
"lasttSeen": "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,

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

@ -79,13 +79,13 @@ Content-type: application/json
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "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,
@ -98,13 +98,13 @@ Content-type: application/json
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
"computerDnsName": "mymachine2.contoso.com",
"firstSeen": "2018-07-09T13:22:45.1250071Z",
"lastSeen": "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,

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

@ -14,13 +14,12 @@ ms.date: 12/08/2017
---
# Get machine by ID API
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
[!include[Prerelease<73>information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a machine entity by ID.
## Permissions
@ -78,13 +77,13 @@ Content-type: application/json
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "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,

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

@ -14,15 +14,12 @@ ms.date: 12/08/2017
---
# Get machine log on users API
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
[!include[Prerelease<73>information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a collection of logged on users.
## Permissions

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

@ -14,13 +14,12 @@ ms.date: 12/08/2017
---
# Get machine related alerts API
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
[!include[Prerelease<73>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

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

@ -33,7 +33,7 @@ Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine
## HTTP request
```
GET /api/machineactions/{id}
GET https://api.securitycenter.windows.com/api/machineactions/{id}
```
## Request headers
@ -76,10 +76,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
"relatedFileInfo": null
}

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

@ -21,7 +21,8 @@ ms.date: 12/08/2017
- 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).
Gets collection of actions done on machines.
Get MachineAction collection API supports [OData V4 queries](https://www.odata.org/documentation/).
## 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)
@ -35,7 +36,7 @@ Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine
## HTTP request
```
GET /api/machineactions
GET https://api.securitycenter.windows.com/api/machineactions
```
## Request headers
@ -81,10 +82,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z",
"lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z",
"relatedFileInfo": null
},
{
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
@ -92,21 +93,24 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
"relatedFileInfo": null
},
{
"id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e",
"type": "UnrestrictCodeExecution",
"type": "StopAndQuarantineFile",
"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"
"creationDateTimeUtc": "2018-12-04T12:15:40.6052029Z",
"lastUpdateTimeUtc": "2018-12-04T12:16:14.2899973Z",
"relatedFileInfo": {
"fileIdentifier": "a0c659857ccbe457fdaf5fe21d54efdcbf6f6508",
"fileIdentifierType": "Sha1"
}
}
]
}
@ -140,10 +144,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z",
"lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z",
"relatedFileInfo": null
},
{
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
@ -151,10 +155,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
"relatedFileInfo": null
}
]
}

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

@ -14,16 +14,16 @@ ms.date: 12/08/2017
---
# List machines API
[!include[Prerelease<73>information](prerelease.md)]
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
[!include[Prerelease<73>information](prerelease.md)]
Retrieves a collection of machines that have communicated with WDATP cloud on the last 30 days.
Get Machines collection API supports [OData V4 queries](https://www.odata.org/documentation/).
The OData's Filter query is supported on: "Id", "ComputerDnsName", "LastSeen", "LastIpAddress", "HealthStatus", "OsPlatform", "RiskScore" and "RbacGroupId"
## Permissions
@ -36,7 +36,7 @@ Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine
## HTTP request
```
GET /api/machines
GET https://api.securitycenter.windows.com/api/machines
```
## Request headers
@ -80,13 +80,13 @@ Content-type: application/json
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "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,
@ -99,13 +99,13 @@ Content-type: application/json
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
"computerDnsName": "mymachine2.contoso.com",
"firstSeen": "2018-07-09T13:22:45.1250071Z",
"lastSeen": "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,

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

@ -31,7 +31,7 @@ Delegated (work or school account) | Machine.CollectForensics | 'Collect forensi
## HTTP request
```
GET /api/machineactions/{machine action id}/getPackageUri
GET https://api.securitycenter.windows.com/api/machineactions/{machine action id}/getPackageUri
```
## Request headers

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

@ -77,13 +77,13 @@ Content-type: application/json
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "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,
@ -96,13 +96,13 @@ Content-type: application/json
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
"computerDnsName": "mymachine2.contoso.com",
"firstSeen": "2018-07-09T13:22:45.1250071Z",
"lastSeen": "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,

BIN
windows/security/threat-protection/windows-defender-atp/images/ms-flow-define-action.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 40 KiB

BIN
windows/security/threat-protection/windows-defender-atp/images/ms-flow-e2e.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 42 KiB

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

@ -29,9 +29,13 @@ Permission type | Permission | Permission display name
Application | Machine.Isolate | 'Isolate machine'
Delegated (work or school account) | Machine.Isolate | 'Isolate machine'
>[!IMPORTANT]
>- Full isolation is available for machines on Windows 10, version 1703.
>- Selective isolation is available for machines on Windows 10, version 1709 or later.
## HTTP request
```
POST /api/machines/{id}/isolate
POST https://api.securitycenter.windows.com/api/machines/{id}/isolate
```
## Request headers
@ -89,10 +93,10 @@ Content-type: application/json
"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"
"lastUpdateTimeUtc": "2017-12-04T12:12:18.9725659Z",
"relatedFileInfo": null
}
```

8
windows/security/threat-protection/windows-defender-atp/machine-windows-defender-advanced-threat-protection-new.md
View File

@ -20,9 +20,11 @@ ms.date: 12/08/2017
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 machine](get-machine-by-id-windows-defender-advanced-threat-protection-new.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).
[Add or Remove machine tags](add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) | Add or Remove tag to a specific machine.
[Find machines by IP](find-machines-by-ip-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | Find machines seen with IP.
# Properties
Property | Type | Description
@ -30,14 +32,14 @@ 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.
lastSeen | DateTimeOffset | Last 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.
healthStatus | Enum | [machine](machine-windows-defender-advanced-threat-protection-new.md) health status. Possible values are: "Active", "Inactive", "ImpairedCommunication", "NoSensorData" and "NoSensorDataImpairedCommunication"
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.

7
windows/security/threat-protection/windows-defender-atp/machineaction-windows-defender-advanced-threat-protection-new.md
View File

@ -37,11 +37,12 @@ Method|Return Type |Description
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.
type | Enum | Type of the action. Possible values are: "RunAntiVirusScan", "Offboard", "CollectInvestigationPackage", "Isolate", "Unisolate", "StopAndQuarantineFile", "RestrictCodeExecution" and "UnrestrictCodeExecution"
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.
status | Enum | Current status of the command. Possible values are: "InProgress", "Succeeded", "Failed", "TimeOut" and "Cancelled".
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.
relatedFileInfo | Class | Contains two Properties. 1) string 'fileIdentifier' 2) Enum 'fileIdentifierType' with the possible values: "Sha1" ,"Sha256" and "Md5".

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

@ -29,9 +29,12 @@ Permission type | Permission | Permission display name
Application | Machine.Offboard | 'Offboard machine'
Delegated (work or school account) | Machine.Offboard | 'Offboard machine'
>[!IMPORTANT]
> This response action is available for machines on Windows 10, version 1703 or later.
## HTTP request
```
POST /api/machines/{id}/offboard
POST https://api.securitycenter.windows.com/api/machines/{id}/offboard
```
## Request headers
@ -82,10 +85,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:09:24.1785079Z",
"lastUpdateTimeUtc": "2018-12-04T12:09:24.1785079Z",
"relatedFileInfo": null
}
```

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

@ -29,9 +29,13 @@ Permission type | Permission | Permission display name
Application | Machine.RestrictExecution | 'Restrict code execution'
Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code execution'
>[!IMPORTANT]
> - This action is available for machines on Windows 10, version 1709 or later.
> - This action needs to meet the Windows Defender Application Control code integrity policy formats and signing requirements. For more information, see [Code integrity policy formats and signing](https://docs.microsoft.com/en-us/windows/device-security/device-guard/requirements-and-deployment-planning-guidelines-for-device-guard#code-integrity-policy-formats-and-signing).
## HTTP request
```
POST /api/machines/{id}/restrictCodeExecution
POST https://api.securitycenter.windows.com/api/machines/{id}/restrictCodeExecution
```
## Request headers
@ -82,10 +86,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:15:04.3825985Z",
"lastUpdateTimeUtc": "2018-12-04T12:15:04.3825985Z",
"relatedFileInfo": null
}
```

5
windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-ms-flow.md
View File

@ -26,7 +26,8 @@ You first need to [create an app](exposed-apis-intro.md).
## Use case
If you need to schedule an advanced query and use the results for follow up actions and processing, you can use [Microsoft Flow](https://flow.microsoft.com/) (or Logic Apps) for it.
A common scenario is scheduling an advanced query and using the results for follow up actions and processing.
In this section we share sample for this purpose using [Microsoft Flow](https://flow.microsoft.com/) (or [Logic Apps](https://azure.microsoft.com/en-us/services/logic-apps/)).
## Define a flow to run query and parse results
@ -77,7 +78,7 @@ The output in the SQL DB is getting updates and can be used for correlation with
## Full flow definition
You can see the full defintion in the following image:
You can find below the full definition
![Image of E2E flow](images/ms-flow-e2e.png)

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

@ -29,9 +29,13 @@ Permission type | Permission | Permission display name
Application | Machine.Scan | 'Scan machine'
Delegated (work or school account) | Machine.Scan | 'Scan machine'
>[!IMPORTANT]
>- This action is available for machines on Windows 10, version 1709 or later.
>- A Windows Defender Antivirus (Windows Defender AV) scan can run alongside other antivirus solutions, whether Windows Defender AV is the active antivirus solution or not. Windows Defender AV can be in Passive mode. For more information, see [Windows Defender Antivirus compatibility](../windows-defender-antivirus/windows-defender-antivirus-compatibility.md).
## HTTP request
```
POST /api/machines/{id}/runAntiVirusScan
POST https://api.securitycenter.windows.com/api/machines/{id}/runAntiVirusScan
```
## Request headers
@ -91,10 +95,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"relatedFileInfo": null
}
```

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

@ -31,7 +31,7 @@ Delegated (work or school account) | Machine.Isolate | 'Isolate machine'
## HTTP request
```
POST /api/machines/{id}/unisolate
POST https://api.securitycenter.windows.com/api/machines/{id}/unisolate
```
## Request headers
@ -86,10 +86,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:13:15.0104931Z",
"lastUpdateTimeUtc": "2018-12-04T12:13:15.0104931Z",
"relatedFileInfo": null
}
```

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

@ -33,7 +33,7 @@ Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code
## HTTP request
```
POST /api/machines/{id}/unrestrictCodeExecution
POST https://api.securitycenter.windows.com/api/machines/{id}/unrestrictCodeExecution
```
## Request headers
@ -84,10 +84,10 @@ Content-type: application/json
"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"
"creationDateTimeUtc": "2018-12-04T12:15:40.6052029Z",
"lastUpdateTimeUtc": "2018-12-04T12:15:40.6052029Z",
"relatedFileInfo": null
}
```