diff --git a/windows/security/threat-protection/TOC.md b/windows/security/threat-protection/TOC.md index ba67fd3160..52a4a8c499 100644 --- a/windows/security/threat-protection/TOC.md +++ b/windows/security/threat-protection/TOC.md @@ -292,12 +292,6 @@ ######## [Get user related machines](windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md) -####### Windows updates (KB) info -######## [Get KbInfo collection](windows-defender-atp/get-kbinfo-collection-windows-defender-advanced-threat-protection.md) -####### Common Vulnerabilities and Exposures (CVE) to KB map -######## [Get CVE-KB map](windows-defender-atp/get-cvekbmap-collection-windows-defender-advanced-threat-protection.md) - - ###### How to use APIs - Samples ####### Advanced Hunting API ######## [Schedule advanced Hunting using Microsoft Flow](windows-defender-atp/run-advanced-query-sample-ms-flow.md) @@ -306,6 +300,7 @@ ######## [Create custom Power BI reports](windows-defender-atp/run-advanced-query-sample-power-bi-app-token.md) ####### Multiple APIs ######## [PowerShell](windows-defender-atp/exposed-apis-full-sample-powershell.md) +####### [Using OData Queries](windows-defender-atp/exposed-apis-odata-samples.md) ##### [Use the Windows Defender ATP exposed APIs (deprecated)](windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md) ###### [Supported Windows Defender ATP APIs (deprecated)](windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md) diff --git a/windows/security/threat-protection/windows-defender-atp/TOC.md b/windows/security/threat-protection/windows-defender-atp/TOC.md index 1238a4b2af..08e1ecbe5a 100644 --- a/windows/security/threat-protection/windows-defender-atp/TOC.md +++ b/windows/security/threat-protection/windows-defender-atp/TOC.md @@ -293,11 +293,6 @@ ####### [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) -###### Windows updates (KB) info -####### [Get KbInfo collection](get-kbinfo-collection-windows-defender-advanced-threat-protection.md) -###### Common Vulnerabilities and Exposures (CVE) to KB map -####### [Get CVE-KB map](get-cvekbmap-collection-windows-defender-advanced-threat-protection.md) - ##### How to use APIs - Samples ###### Advanced Hunting API ####### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md) @@ -306,6 +301,7 @@ ####### [Create custom Power BI reports](run-advanced-query-sample-power-bi-app-token.md) ###### Multiple APIs ####### [PowerShell](exposed-apis-full-sample-powershell.md) +###### [Using OData Queries](exposed-apis-odata-samples.md) #### [Use the Windows Defender ATP exposed APIs (deprecated)](exposed-apis-windows-defender-advanced-threat-protection.md) ##### [Supported Windows Defender ATP APIs (deprecated)](supported-apis-windows-defender-advanced-threat-protection.md) 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 d8edf97d46..aaf42956c2 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 @@ -22,6 +22,25 @@ ms.date: 30/07/2018 >Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-supportedapis-abovefoldlink) +## End Point URI and Versioning + +### End Point URI: + +> The service base URI is: https://api.securitycenter.windows.com + +> The queries based OData have the '/api' prefix. For example, to get Alerts you can send GET request to https://api.securitycenter.windows.com/api/alerts + +### Versioning: + +> The API supports versioning. + +> The current version is **V1.0**. + +> 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. + + 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. ## In this section 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 new file mode 100644 index 0000000000..a7384d989f --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-odata-samples.md @@ -0,0 +1,188 @@ +--- +title: OData queries with Windows Defender ATP +description: OData queries with Windows Defender ATP +keywords: apis, supported apis, odata, query +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: 09/24/2018 +--- + +# OData queries with Windows Defender ATP +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +> If you are not familiar with OData queries, please 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.** + +### Example 1 + +**Get all the machines with 'High' 'RiskScore'** + +``` +HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=riskScore eq 'High' +``` + +**Response:** + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "e3a77eeddb83d581238792387b1239b01286b2f", + "computerDnsName": "examples.dev.corp.microsoft.com", + "firstSeen": "2016-11-02T23:26:03.7882168Z", + "lastSeen": "2018-11-12T10:27:08.708723Z", + "osPlatform": "Windows10", + "osVersion": "10.0.0.0", + "lastIpAddress": "123.123.10.33", + "lastExternalIpAddress": "124.124.160.172", + "agentVersion": "10.6300.18279.1001", + "osBuild": 18279, + "healthStatus": "ImpairedCommunication", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 5, + "rbacGroupName": "North", + "riskScore": "High", + "aadDeviceId": "d90b0b99-1234-1234-1234-b91d50c6796a" + }, + . + . + . + ] +} +``` + +### Example 2 + +**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 +``` + +**Response:** + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "1113333ddb83d581238792387b1239b01286b2f", + "computerDnsName": "examples.dev.corp.microsoft.com", + "firstSeen": "2016-11-02T23:26:03.7882168Z", + "lastSeen": "2018-11-12T10:27:08.708723Z", + "osPlatform": "Windows10", + "osVersion": "10.0.0.0", + "lastIpAddress": "123.123.10.33", + "lastExternalIpAddress": "124.124.160.172", + "agentVersion": "10.6300.18279.1001", + "osBuild": 18279, + "healthStatus": "ImpairedCommunication", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 5, + "rbacGroupName": "North", + "riskScore": "Medium", + "aadDeviceId": "d90b0b99-1234-1234-1234-b91d50c6796a" + }, + . + . + . + ] +} +``` + +### Example 3 + +**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 +``` + +**Response:** + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "83113465ffceca4a731234e5dcde3357e026e873", + "computerDnsName": "examples-vm10", + "firstSeen": "2018-11-12T16:07:50.1706168Z", + "lastSeen": "2018-11-12T16:07:50.1706168Z", + "osPlatform": "WindowsServer2019", + "osVersion": null, + "lastIpAddress": "10.123.72.35", + "lastExternalIpAddress": "123.220.2.3", + "agentVersion": "10.6300.18281.1000", + "osBuild": 18281, + "healthStatus": "Active", + "isAadJoined": false, + "machineTags": [], + "rbacGroupId": 4, + "rbacGroupName": "East", + "riskScore": "None", + "aadDeviceId": null + }, + . + . + . + ] +} +``` + +### Example 4 + +**Get all the Anti-Virus scans that the user Analyst@examples.onmicrosoft.com created using WDATP** + +``` +HTTP GET https://api.securitycenter.windows.com/api/machineactions?$filter=requestor eq 'Analyst@WcdTestPrd.onmicrosoft.com' and type eq 'RunAntiVirusScan' +``` + +**Response:** + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions", + "value": [ + { + "id": "5c3e3322-d993-1234-1111-dfb136ebc8c5", + "type": "RunAntiVirusScan", + "requestor": "Analyst@examples.onmicrosoft.com", + "requestorComment": "1533", + "status": "Succeeded", + "machineId": "123321c10e44a82877af76b1d0161a17843f688a", + "creationDateTimeUtc": "2018-11-12T13:33:24.5755657Z", + "lastUpdateDateTimeUtc": "2018-11-12T13:34:32.0319826Z", + "relatedFileInfo": null + }, + . + . + . + ] +} +``` + +## Related topic +- [Windows Defender ATP APIs](apis-intro.md) 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 2ff5212e4b..e109d17851 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,6 +41,8 @@ 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** + ## Request headers Name | Type | Description @@ -64,7 +66,7 @@ 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 +GET https://api.securitycenter.windows.com/api/users/user1/alerts ``` **Response** 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 53e0047b39..35a87d200a 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,6 +41,9 @@ 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** + + ## Request headers Name | Type | Description @@ -64,7 +67,7 @@ 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 +GET https://api.securitycenter.windows.com/api/users/user1/machines ``` **Response**