From 6b129e368cc8e97a8680dbbed15979b112de427b Mon Sep 17 00:00:00 2001 From: Ben Alfasi Date: Thu, 21 Jan 2021 20:52:24 +0200 Subject: [PATCH 1/6] 1 --- .../find-machine-info-by-ip.md | 95 ------------------- .../find-machines-by-tag.md | 82 ++++++++++++++++ 2 files changed, 82 insertions(+), 95 deletions(-) delete mode 100644 windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md create mode 100644 windows/security/threat-protection/microsoft-defender-atp/find-machines-by-tag.md diff --git a/windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md b/windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md deleted file mode 100644 index b94742b61d..0000000000 --- a/windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Find device information by internal IP API -description: Use this API to create calls related to finding a device entry around a specific timestamp by internal IP. -keywords: ip, apis, graph api, supported apis, find device, device 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 -manager: dansimp -audience: ITPro -ms.collection: M365-security-compliance -ms.topic: article ---- - -# Find device information by internal IP API - -[!INCLUDE [Microsoft 365 Defender rebranding](../../includes/microsoft-defender.md)] - - -**Applies to:** [Microsoft Defender for Endpoint](https://go.microsoft.com/fwlink/p/?linkid=2146631) - -- Want to experience Microsoft Defender for Endpoint? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) - -[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)] - -[!include[Improve request performance](../../includes/improve-request-performance.md)] - -Find a device 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 Microsoft Defender for Endpoint APIs](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 devices 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", -… -} -``` diff --git a/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-tag.md b/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-tag.md new file mode 100644 index 0000000000..d076dc226e --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-tag.md @@ -0,0 +1,82 @@ +--- +title: Find devices by tag API +description: Find all devices that contain specifc tag +keywords: apis, supported apis, get, device, find, find device, by tag, tag +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Find devices by tag API + +[!INCLUDE [Microsoft 365 Defender rebranding](../../includes/microsoft-defender.md)] + + +**Applies to:** [Microsoft Defender for Endpoint](https://go.microsoft.com/fwlink/p/?linkid=2146631) + +- Want to experience Microsoft Defender for Endpoint? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + +[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)] + +[!include[Improve request performance](../../includes/improve-request-performance.md)] + + +## API description +Find [Machines](machine.md) by [Tag](machine-tags.md). + + +## Limitations +1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour. + + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender for Endpoint APIs](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' + +>[!Note] +> When obtaining a token using user credentials: +> - Response will include only devices that the user have access to based on device group settings (See [Create and manage device groups](machine-groups.md) for more information) +> - The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles.md) for more information) +> - Response will include only devices that the user have access to based on device group settings (See [Create and manage device groups](machine-groups.md) for more information) + +## HTTP request +``` +GET /api/machines/findbytag(tag='{tag}') +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + +## Request body +Empty + +## Response +If successful - 200 OK with list of the machines in the response body. + +## Example + +**Request** + +Here is an example of the request. + +``` +GET https://api.securitycenter.microsoft.com/api/machines/findbytag(tag='testTag') +``` From ac2d63462d8d096c5e9fd0aeead6a1839214af29 Mon Sep 17 00:00:00 2001 From: Ben Alfasi Date: Thu, 21 Jan 2021 21:48:12 +0200 Subject: [PATCH 2/6] 1 --- .../find-machines-by-tag.md | 2 +- .../import-ti-indicators.md | 141 ++++++++++++++++++ .../post-ti-indicator.md | 5 +- 3 files changed, 145 insertions(+), 3 deletions(-) create mode 100644 windows/security/threat-protection/microsoft-defender-atp/import-ti-indicators.md diff --git a/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-tag.md b/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-tag.md index d076dc226e..c077f850b8 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-tag.md +++ b/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-tag.md @@ -79,4 +79,4 @@ Here is an example of the request. ``` GET https://api.securitycenter.microsoft.com/api/machines/findbytag(tag='testTag') -``` +``` \ No newline at end of file diff --git a/windows/security/threat-protection/microsoft-defender-atp/import-ti-indicators.md b/windows/security/threat-protection/microsoft-defender-atp/import-ti-indicators.md new file mode 100644 index 0000000000..acc7328e9d --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/import-ti-indicators.md @@ -0,0 +1,141 @@ +--- +title: Import Indicators API +description: Learn how to use the Import batch of Indicator API in Microsoft Defender Advanced Threat Protection. +keywords: apis, supported apis, submit, ti, indicator, update +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Import Indicators API + +[!INCLUDE [Microsoft 365 Defender rebranding](../../includes/microsoft-defender.md)] + + +**Applies to:** [Microsoft Defender for Endpoint](https://go.microsoft.com/fwlink/p/?linkid=2146631) + +- Want to experience Microsoft Defender for Endpoint? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + +[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)] + +[!include[Improve request performance](../../includes/improve-request-performance.md)] + + +## API description +Submits or Updates batch of [Indicator](ti-indicator.md) entities. +
CIDR notation for IPs is not supported. + +## Limitations +1. Rate limitations for this API are 30 calls per minute. +2. There is a limit of 15,000 active [Indicators](ti-indicator.md) per tenant. + + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Get started](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Ti.ReadWrite | 'Read and write Indicators' +Application | Ti.ReadWrite.All | 'Read and write All Indicators' +Delegated (work or school account) | Ti.ReadWrite | 'Read and write Indicators' + + +## HTTP request +``` +POST https://api.securitycenter.microsoft.com/api/indicators/import +``` + +## 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 +:---|:---|:--- +Indicators | List<[Indicator](ti-indicator.md)> | List of [Indicators](ti-indicator.md). **Required** + + +## Response +- If successful, this method returns 200 - OK response code with a list of import results per indicator, see example below. +- If not successful: this method return 400 - Bad Request. Bad request usually indicates incorrect body. + +## Example + +**Request** + +Here is an example of the request. + +``` +POST https://api.securitycenter.microsoft.com/api/indicators/import +``` +```json +{ + "Indicators": + [ + { + "indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f", + "indicatorType": "FileSha1", + "title": "demo", + "application": "demo-test", + "expirationTime": "2021-12-12T00:00:00Z", + "action": "Alert", + "severity": "Informational", + "description": "demo2", + "recommendedActions": "nothing", + "rbacGroupNames": ["group1", "group2"] + }, + { + "indicatorValue": "2233223322332233223322332233223322332233223322332233223322332222", + "indicatorType": "FileSha256", + "title": "demo2", + "application": "demo-test2", + "expirationTime": "2021-12-12T00:00:00Z", + "action": "Alert", + "severity": "Medium", + "description": "demo2", + "recommendedActions": "nothing", + "rbacGroupNames": [] + } + ] +} +``` + +**Request** + +Here is an example of the request. + +```json +{ + "value": [ + { + "id": "2841", + "indicator": "220e7d15b011d7fac48f2bd61114db1022197f7f", + "isFailed": false, + "failureReason": null + }, + { + "id": "2842", + "indicator": "2233223322332233223322332233223322332233223322332233223322332222", + "isFailed": false, + "failureReason": null + } + ] +} +``` + +## Related topic +- [Manage indicators](manage-indicators.md) diff --git a/windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md b/windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md index ac9c3929ea..433f0a15eb 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md +++ b/windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md @@ -32,7 +32,7 @@ ms.topic: article ## API description Submits or Updates new [Indicator](ti-indicator.md) entity. -
CIDR notation for IPs is supported. +
CIDR notation for IPs is not supported. ## Limitations 1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour. @@ -90,7 +90,8 @@ Here is an example of the request. ``` POST https://api.securitycenter.microsoft.com/api/indicators -Content-type: application/json +``` +```json { "indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f", "indicatorType": "FileSha1", From 08ff136c0d20cf3c6c98780e6f136920d362f91d Mon Sep 17 00:00:00 2001 From: Ben Alfasi Date: Thu, 21 Jan 2021 21:48:50 +0200 Subject: [PATCH 3/6] 2 --- .../microsoft-defender-atp/import-ti-indicators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/windows/security/threat-protection/microsoft-defender-atp/import-ti-indicators.md b/windows/security/threat-protection/microsoft-defender-atp/import-ti-indicators.md index acc7328e9d..822e0f9985 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/import-ti-indicators.md +++ b/windows/security/threat-protection/microsoft-defender-atp/import-ti-indicators.md @@ -114,9 +114,9 @@ POST https://api.securitycenter.microsoft.com/api/indicators/import } ``` -**Request** +**Response** -Here is an example of the request. +Here is an example of the response. ```json { From 8f1150a12f25a24568016709705f1c62e43855f1 Mon Sep 17 00:00:00 2001 From: Ben Alfasi Date: Thu, 21 Jan 2021 22:10:40 +0200 Subject: [PATCH 4/6] 1 --- windows/security/threat-protection/TOC.md | 2 ++ .../threat-protection/microsoft-defender-atp/machine.md | 1 + .../threat-protection/microsoft-defender-atp/ti-indicator.md | 3 ++- 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/windows/security/threat-protection/TOC.md b/windows/security/threat-protection/TOC.md index 4fd85c48d2..af35c57f47 100644 --- a/windows/security/threat-protection/TOC.md +++ b/windows/security/threat-protection/TOC.md @@ -550,6 +550,7 @@ ####### [Get security recommendations](microsoft-defender-atp/get-security-recommendations.md) ####### [Add or Remove machine tags](microsoft-defender-atp/add-or-remove-machine-tags.md) ####### [Find machines by IP](microsoft-defender-atp/find-machines-by-ip.md) +####### [Find machines by tag](microsoft-defender-atp/find-machines-by-tag.md) ####### [Get missing KBs](microsoft-defender-atp/get-missing-kbs-machine.md) ####### [Set device value](microsoft-defender-atp/set-device-value.md) @@ -576,6 +577,7 @@ ###### [Indicators]() ####### [Indicators methods and properties](microsoft-defender-atp/ti-indicator.md) ####### [Submit Indicator](microsoft-defender-atp/post-ti-indicator.md) +####### [Import Indicators](microsoft-defender-atp/import-ti-indicators.md) ####### [List Indicators](microsoft-defender-atp/get-ti-indicators-collection.md) ####### [Delete Indicator](microsoft-defender-atp/delete-ti-indicator-by-id.md) diff --git a/windows/security/threat-protection/microsoft-defender-atp/machine.md b/windows/security/threat-protection/microsoft-defender-atp/machine.md index 53bdfe131c..f4952472cd 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/machine.md +++ b/windows/security/threat-protection/microsoft-defender-atp/machine.md @@ -44,6 +44,7 @@ Method|Return Type |Description [Get security recommendations](get-security-recommendations.md) | [recommendation](recommendation.md) collection | Retrieves a collection of security recommendations related to a given machine ID. [Add or Remove machine tags](add-or-remove-machine-tags.md) | [machine](machine.md) | Add or Remove tag to a specific machine. [Find machines by IP](find-machines-by-ip.md) | [machine](machine.md) collection | Find machines seen with IP. +[Find machines by tag](find-machines-by-tag.md) | [machine](machine.md) collection | Find machines by [Tag](machine-tags.md). [Get missing KBs](get-missing-kbs-machine.md) | KB collection | Get a list of missing KBs associated with the machine ID [Set device value](set-device-value.md)| [machine](machine.md) collection | Set the [value of a device](tvm-assign-device-value.md). diff --git a/windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md b/windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md index 39a5774d5c..1b6bef4976 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md +++ b/windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md @@ -35,7 +35,8 @@ ms.topic: article Method|Return Type |Description :---|:---|:--- [List Indicators](get-ti-indicators-collection.md) | [Indicator](ti-indicator.md) Collection | List [Indicator](ti-indicator.md) entities. -[Submit Indicator](post-ti-indicator.md) | [Indicator](ti-indicator.md) | Submits [Indicator](ti-indicator.md) entity. +[Submit Indicator](post-ti-indicator.md) | [Indicator](ti-indicator.md) | Submit or update [Indicator](ti-indicator.md) entity. +[Import Indicators](import-ti-indicators.md) | [Indicator](ti-indicator.md) Collection | Submit or update [Indicators](ti-indicator.md) entities. [Delete Indicator](delete-ti-indicator-by-id.md) | No Content | Deletes [Indicator](ti-indicator.md) entity. From 544c3c53ee7ae950290838dedfa6121e7da41a6d Mon Sep 17 00:00:00 2001 From: jcaparas Date: Thu, 21 Jan 2021 12:35:36 -0800 Subject: [PATCH 5/6] Update .openpublishing.redirection.json redirect for deleted file --- .openpublishing.redirection.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 0cf060785e..7bcd7f8d15 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -15110,6 +15110,11 @@ "redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip", "redirect_document_id": true }, + { + "source_path": "windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md", + "redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip", + "redirect_document_id": false + }, { "source_path": "windows/security/threat-protection/windows-defender-atp/get-filemachineaction-object-windows-defender-advanced-threat-protection.md", "redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/windows-defender-atp/use-apis", From 7314f0dc114c77be6ad51885a82d2bda31189ef8 Mon Sep 17 00:00:00 2001 From: Ben Alfasi Date: Fri, 22 Jan 2021 11:43:37 +0200 Subject: [PATCH 6/6] 1 --- .../find-machine-info-by-ip.md | 96 ------------------- 1 file changed, 96 deletions(-) delete mode 100644 windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md diff --git a/windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md b/windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md deleted file mode 100644 index b00bf9017d..0000000000 --- a/windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Find device information by internal IP API -description: Use this API to create calls related to finding a device entry around a specific timestamp by internal IP. -keywords: ip, apis, graph api, supported apis, find device, device information -search.product: eADQiWindows 10XVcnh -ms.prod: m365-security -ms.mktglfcycl: deploy -ms.sitesec: library -ms.pagetype: security -ms.author: macapara -author: mjcaparas -ms.localizationpriority: medium -manager: dansimp -audience: ITPro -ms.collection: M365-security-compliance -ms.topic: article -ms.technology: mde ---- - -# Find device information by internal IP API - -[!INCLUDE [Microsoft 365 Defender rebranding](../../includes/microsoft-defender.md)] - - -**Applies to:** [Microsoft Defender for Endpoint](https://go.microsoft.com/fwlink/p/?linkid=2146631) - -- Want to experience Microsoft Defender for Endpoint? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) - -[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)] - -[!include[Improve request performance](../../includes/improve-request-performance.md)] - -Find a device 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 Microsoft Defender for Endpoint APIs](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 devices 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", -… -} -```