From b3ca0f5434a84a9b52c1299e1a3924e2c93d92bf Mon Sep 17 00:00:00 2001 From: Beth Levin Date: Thu, 1 Oct 2020 14:42:42 -0700 Subject: [PATCH] api updates --- .../get-or-set-device-value.md | 64 ---------------- .../microsoft-defender-atp/machine.md | 2 +- .../set-device-value.md | 75 +++++++++++++++++++ .../threat-and-vuln-mgt-scenarios.md | 15 +--- 4 files changed, 78 insertions(+), 78 deletions(-) delete mode 100644 windows/security/threat-protection/microsoft-defender-atp/get-or-set-device-value.md create mode 100644 windows/security/threat-protection/microsoft-defender-atp/set-device-value.md diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-or-set-device-value.md b/windows/security/threat-protection/microsoft-defender-atp/get-or-set-device-value.md deleted file mode 100644 index 1c031b9db2..0000000000 --- a/windows/security/threat-protection/microsoft-defender-atp/get-or-set-device-value.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Get or set device value -description: Learn how to use the Device Value API to get or set the device value -keywords: apis, graph api, supported apis, get, list, file, information, software id, threat & vulnerability management api, mdatp tvm api -search.product: eADQiWindows 10XVcnh -ms.prod: w10 -ms.mktglfcycl: deploy -ms.sitesec: library -ms.pagetype: security -ms.author: ellevin -author: levinec -ms.localizationpriority: medium -manager: dansimp -audience: ITPro -ms.collection: M365-security-compliance -ms.topic: article ---- - -# Get or set device value - -[!INCLUDE [Microsoft 365 Defender rebranding](../../includes/microsoft-defender.md)] - - -**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) - -- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) - -## API description - -Set or GET specific [Machine](machine.md) device value to define it's value to the organization. [Learn more about device value](threat-and-vuln-mgt-scenarios.md#define-a-devices-value-to-the-organization) - -## Permissions - -One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md) for details. - -### Get machines - -Permission type | Permission | Permission display name -:---|:---|:--- -User |ViewData | ? -Application |Machine.Read | ? - -### Get device value - -Permission type | Permission | Permission display name -:---|:---|:--- -User |ViewData | > -Application | Machine.ReadWrite | ? - -## HTTP GET request - -```http -GET /api/machines/{machineId}/getDeviceValue -``` - -## HTTP set request -```http -POST /api/machines/{machineId}/setDeviceValue -``` - -### Possible values - -Normal/Low/High - diff --git a/windows/security/threat-protection/microsoft-defender-atp/machine.md b/windows/security/threat-protection/microsoft-defender-atp/machine.md index 8874d119f9..72558cc088 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/machine.md +++ b/windows/security/threat-protection/microsoft-defender-atp/machine.md @@ -41,7 +41,7 @@ Method|Return Type |Description [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. [Get missing KBs](get-missing-kbs-machine.md) | KB collection | Get a list of missing KBs associated with the machine ID -[Get or set device value](get-or-set-device-value.md)| [machine](machine.md) collection | Get or set the value of a device +[Set device value](set-device-value.md)| [machine](machine.md) collection | Set the value of a device ## Properties diff --git a/windows/security/threat-protection/microsoft-defender-atp/set-device-value.md b/windows/security/threat-protection/microsoft-defender-atp/set-device-value.md new file mode 100644 index 0000000000..4d51c36e4a --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/set-device-value.md @@ -0,0 +1,75 @@ +--- +title: Set device value API +description: Learn how to use the Add or Remove machine tags API to adds or remove a tag for a machine in Microsoft Defender Advanced Threat Protection. +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 +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Set device value API + +[!INCLUDE [Microsoft 365 Defender rebranding](../../includes/microsoft-defender.md)] + + +**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) + +- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + +## API description + +Adds or remove tag to a specific [Machine](machine.md). + +## Limitations + +1. You can post on machines last seen according to your configured retention period. + +2. 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 ATP APIs](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' + +>[!Note] +> When obtaining a token using user credentials: +> +>- The user needs to have at least the following role permission: 'Manage security setting'. For more (See [Create and manage roles](user-roles.md) for more information) +>- User needs to have access to the machine, based on machine group settings (See [Create and manage machine groups](machine-groups.md) for more information) + +## HTTP request + +```http +POST https://api.securitycenter.windows.com/api/machines/{machineId}/setDeviceValue +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. +Content-Type | string | application/json. **Required**. + +## Request body + +```http +"DeviceValue": "{device value}" +``` + +## Response + +If successful, this method returns 200 - Ok response code and the updated Machine in the response body. diff --git a/windows/security/threat-protection/microsoft-defender-atp/threat-and-vuln-mgt-scenarios.md b/windows/security/threat-protection/microsoft-defender-atp/threat-and-vuln-mgt-scenarios.md index 677ca55787..85d599cd64 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/threat-and-vuln-mgt-scenarios.md +++ b/windows/security/threat-protection/microsoft-defender-atp/threat-and-vuln-mgt-scenarios.md @@ -57,6 +57,8 @@ DeviceName=any(DeviceName) by DeviceId, AlertId Defining a device’s value helps you differentiate between asset priorities. The device value is used to incorporate the risk appetite of an individual asset into the threat and vulnerability management exposure score calculation. Devices marked as “high value” will receive more weight. +You can also use the [set device value API](set-device-value.md). + Device value options: - Low @@ -82,19 +84,6 @@ Examples of devices that should be marked as high value: 3. A flyout will appear with the current device value and what it means. Review the value of the device and choose the one that best fits your device. ![Example of the device value flyout.](images/tvm-device-value-flyout.png) -## Get or set device value - -HTTP GET request -```http -GET /api/machines/{machineId}/getDeviceValue -``` - -HTTP set request -```http -POST /api/machines/{machineId}/setDeviceValue -``` - -**Possible values**: Normal/Low/High ## Related topics