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

Merge pull request #4591 from MicrosoftDocs/user/bealfasi/mde-api-update-01-21-2021

Browse Source 
Added 2 new APIs
This commit is contained in:
Tina Burden 2021-01-22 08:25:11 -08:00 committed by GitHub
commit 333a490ada
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 236 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.openpublishing.redirection.json
View File

@ -15110,6 +15110,11 @@
"redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip", "redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip",
"redirect_document_id": true "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", "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", "redirect_url": "https://docs.microsoft.com/windows/security/threat-protection/windows-defender-atp/use-apis",

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

@ -550,6 +550,7 @@
####### [Get security recommendations](microsoft-defender-atp/get-security-recommendations.md) ####### [Get security recommendations](microsoft-defender-atp/get-security-recommendations.md)
####### [Add or Remove machine tags](microsoft-defender-atp/add-or-remove-machine-tags.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 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) ####### [Get missing KBs](microsoft-defender-atp/get-missing-kbs-machine.md)
####### [Set device value](microsoft-defender-atp/set-device-value.md) ####### [Set device value](microsoft-defender-atp/set-device-value.md)
@ -576,6 +577,7 @@
###### [Indicators]() ###### [Indicators]()
####### [Indicators methods and properties](microsoft-defender-atp/ti-indicator.md) ####### [Indicators methods and properties](microsoft-defender-atp/ti-indicator.md)
####### [Submit Indicator](microsoft-defender-atp/post-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) ####### [List Indicators](microsoft-defender-atp/get-ti-indicators-collection.md)
####### [Delete Indicator](microsoft-defender-atp/delete-ti-indicator-by-id.md) ####### [Delete Indicator](microsoft-defender-atp/delete-ti-indicator-by-id.md)

96
windows/security/threat-protection/microsoft-defender-atp/find-machine-info-by-ip.md
View File

@ -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",
…
}
```

82
windows/security/threat-protection/microsoft-defender-atp/find-machines-by-tag.md Normal file
View File

@ -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')
```

141
windows/security/threat-protection/microsoft-defender-atp/import-ti-indicators.md Normal file
View File

@ -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.
<br>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": []
}
]
}
```
**Response**
Here is an example of the response.
```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)

1
windows/security/threat-protection/microsoft-defender-atp/machine.md
View File

@ -45,6 +45,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. [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. [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 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 [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). [Set device value](set-device-value.md)| [machine](machine.md) collection | Set the [value of a device](tvm-assign-device-value.md).

5
windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md
View File

@ -33,7 +33,7 @@ ms.technology: mde
## API description ## API description
Submits or Updates new [Indicator](ti-indicator.md) entity. Submits or Updates new [Indicator](ti-indicator.md) entity.
<br>CIDR notation for IPs is supported. <br>CIDR notation for IPs is not supported.
## Limitations ## Limitations
1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour. 1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
@ -91,7 +91,8 @@ Here is an example of the request.
``` ```
POST https://api.securitycenter.microsoft.com/api/indicators POST https://api.securitycenter.microsoft.com/api/indicators
Content-type: application/json ```
```json
{ {
"indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f", "indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1", "indicatorType": "FileSha1",

3
windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md
View File

@ -36,7 +36,8 @@ ms.technology: mde
Method|Return Type |Description Method|Return Type |Description
:---|:---|:--- :---|:---|:---
[List Indicators](get-ti-indicators-collection.md) | [Indicator](ti-indicator.md) Collection | List [Indicator](ti-indicator.md) entities. [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. [Delete Indicator](delete-ti-indicator-by-id.md) | No Content | Deletes [Indicator](ti-indicator.md) entity.