diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-list.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-list.md index aaf42956c2..101b345a77 100644 --- a/windows/security/threat-protection/windows-defender-atp/exposed-apis-list.md +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-list.md @@ -38,7 +38,7 @@ ms.date: 30/07/2018 > To use a specific version, use this format: https://api.securitycenter.windows.com/api/{Version}. For example: https://api.securitycenter.windows.com/api/v1.0/alerts -> If you don't specify any version ( without /v1.0/ ) you will get to the latest version. +> If you don't specify any version (e.g., https://api.securitycenter.windows.com/api/alerts ) you will get to the latest version. Learn more about the individual supported entities where you can run API calls to and details such as HTTP request values, request headers and expected responses. diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-odata-samples.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-odata-samples.md index a7384d989f..dfc82df1d8 100644 --- a/windows/security/threat-protection/windows-defender-atp/exposed-apis-odata-samples.md +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-odata-samples.md @@ -10,7 +10,7 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: medium -ms.date: 09/24/2018 +ms.date: 11/15/2018 --- # OData queries with Windows Defender ATP @@ -19,14 +19,58 @@ ms.date: 09/24/2018 [!include[Prerelease information](prerelease.md)] -> If you are not familiar with OData queries, please see: [OData V4 queries](https://www.odata.org/documentation/) +- If you are not familiar with OData queries, see: [OData V4 queries](https://www.odata.org/documentation/) -> ** Currently, [Machine](machine-windows-defender-advanced-threat-protection-new.md) and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entities supports all OData queries.** -> ** [Alert](alerts-windows-defender-advanced-threat-protection-new.md) entity support all OData queries except $filter.** +- Currently, [Machine](machine-windows-defender-advanced-threat-protection-new.md) and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entities supports all OData queries. +- [Alert](alerts-windows-defender-advanced-threat-protection-new.md) entity support all OData queries except $filter. ### Example 1 -**Get all the machines with 'High' 'RiskScore'** +**Get all the machines with the tag 'ExampleTag'** + +``` +HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=machineTags/any(tag: tag eq 'ExampleTag') +``` + +**Response:** + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "b9d4c51123327fb2a25db29ff1b8f3b64888e7ba", + "computerDnsName": "examples.dev.corp.Contoso.com", + "firstSeen": "2018-03-07T11:19:11.7234147Z", + "lastSeen": "2018-11-15T11:23:38.3196947Z", + "osPlatform": "Windows10", + "osVersion": "10.0.0.0", + "lastIpAddress": "123.17.255.241", + "lastExternalIpAddress": "123.220.196.180", + "agentVersion": "10.6400.18282.1001", + "osBuild": 18282, + "healthStatus": "Active", + "isAadJoined": true, + "machineTags": [ + "ExampleTag" + ], + "rbacGroupId": 5, + "rbacGroupName": "Developers", + "riskScore": "North", + "aadDeviceId": null + }, + . + . + . + ] +} +``` + +### Example 2 + +- Get all the machines with 'High' 'RiskScore' ``` HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=riskScore eq 'High' @@ -42,7 +86,7 @@ Content-type: application/json "value": [ { "id": "e3a77eeddb83d581238792387b1239b01286b2f", - "computerDnsName": "examples.dev.corp.microsoft.com", + "computerDnsName": "examples.dev.corp.Contoso.com", "firstSeen": "2016-11-02T23:26:03.7882168Z", "lastSeen": "2018-11-12T10:27:08.708723Z", "osPlatform": "Windows10", @@ -55,7 +99,7 @@ Content-type: application/json "isAadJoined": true, "machineTags": [], "rbacGroupId": 5, - "rbacGroupName": "North", + "rbacGroupName": "Developers", "riskScore": "High", "aadDeviceId": "d90b0b99-1234-1234-1234-b91d50c6796a" }, @@ -66,9 +110,9 @@ Content-type: application/json } ``` -### Example 2 +### Example 3 -**Get top 100 machines with 'HealthStatus' not equals to 'Active'** +- Get top 100 machines with 'HealthStatus' not equals to 'Active' ``` HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=healthStatus ne 'Active'&$top=100 @@ -84,7 +128,7 @@ Content-type: application/json "value": [ { "id": "1113333ddb83d581238792387b1239b01286b2f", - "computerDnsName": "examples.dev.corp.microsoft.com", + "computerDnsName": "examples.dev.corp.Contoso.com", "firstSeen": "2016-11-02T23:26:03.7882168Z", "lastSeen": "2018-11-12T10:27:08.708723Z", "osPlatform": "Windows10", @@ -97,7 +141,7 @@ Content-type: application/json "isAadJoined": true, "machineTags": [], "rbacGroupId": 5, - "rbacGroupName": "North", + "rbacGroupName": "Developers", "riskScore": "Medium", "aadDeviceId": "d90b0b99-1234-1234-1234-b91d50c6796a" }, @@ -108,9 +152,9 @@ Content-type: application/json } ``` -### Example 3 +### Example 4 -**Get all the machines that last seen after 2018-10-20** +- Get all the machines that last seen after 2018-10-20 ``` HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=lastSeen gt 2018-10-20Z @@ -138,8 +182,8 @@ Content-type: application/json "healthStatus": "Active", "isAadJoined": false, "machineTags": [], - "rbacGroupId": 4, - "rbacGroupName": "East", + "rbacGroupId": 5, + "rbacGroupName": "Developers", "riskScore": "None", "aadDeviceId": null }, @@ -150,9 +194,9 @@ Content-type: application/json } ``` -### Example 4 +### Example 5 -**Get all the Anti-Virus scans that the user Analyst@examples.onmicrosoft.com created using WDATP** +- Get all the Anti-Virus scans that the user Analyst@examples.onmicrosoft.com created using Windows Defender ATP ``` HTTP GET https://api.securitycenter.windows.com/api/machineactions?$filter=requestor eq 'Analyst@WcdTestPrd.onmicrosoft.com' and type eq 'RunAntiVirusScan' diff --git a/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md index e109d17851..df5abdbe22 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md +++ b/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md @@ -41,7 +41,7 @@ Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' GET /api/users/{id}/alerts ``` -**Note that the id is not the Full UPN, its only the user name. For example, for user1@contoso.com you will need to send /api/users/user1/alerts** +**Note that the id is not the full UPN, but only the user name. (e.g., to retrieve alerts for user1@contoso.com use /api/users/user1/alerts) ** ## Request headers @@ -54,7 +54,7 @@ Authorization | String | Bearer {token}. **Required**. Empty ## Response -If successful and user and alert exists - 200 OK. If user or alerts does not exist - 404 Not Found. +If successful and user and alert exist - 200 OK. If user or alerts do not exist - 404 Not Found. ## Example diff --git a/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md index 6ea6b78d52..ec40578526 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md @@ -11,7 +11,7 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: medium -ms.date: 12/08/2017 +ms.date: 11/15/2018 --- # Get user related alerts API (deprecated) diff --git a/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md index 35a87d200a..ecf23df07d 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md +++ b/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md @@ -41,7 +41,7 @@ Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine GET /api/users/{id}/machines ``` -**Note that the id is not the Full UPN, its only the user name. For example, for user1@contoso.com you will need to send /api/users/user1/machines** +**Note that the id is not the full UPN, but only the user name. (e.g., to retrieve machines for user1@contoso.com use /api/users/user1/machines) ** ## Request headers