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

indicators

Browse Source
This commit is contained in:
Ben Alfasi 2020-01-06 14:27:30 +02:00
parent 45caec75ad
commit 68eeb287df
4 changed files with 102 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
windows/security/threat-protection/microsoft-defender-atp/delete-ti-indicator-by-id.md
View File

@ -18,15 +18,18 @@ ms.topic: article
# Delete Indicator API # Delete Indicator API
**Applies to:** **Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
- [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)
>[!Note] ## API description
> Currently this API is only supported for AppOnly context requests. (See [Get access with application context](exposed-apis-create-app-webapp.md) for more information) Deletes an [Indicator](ti-indicator.md) entity by ID.
- Deletes an Indicator entity by ID. ## Limitations
1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
## Permissions ## 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) 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)
@ -66,15 +69,5 @@ If Indicator with the specified id was not found - 404 Not Found.
Here is an example of the request. Here is an example of the request.
``` ```
DELETE https://api.securitycenter.windows.com/api/indicators/220e7d15b0b3d7fac48f2bd61114db1022197f7f DELETE https://api.securitycenter.windows.com/api/indicators/995
```
**Response**
Here is an example of the response.
```
HTTP/1.1 204 NO CONTENT
``` ```

47
windows/security/threat-protection/microsoft-defender-atp/get-ti-indicators-collection.md
View File

@ -18,16 +18,21 @@ ms.topic: article
# List Indicators API # List Indicators API
**Applies to:** **Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
- [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)
>[!NOTE] ## API description
> Currently this API is supported only for AppOnly context requests. (See [Get access with application context](exposed-apis-create-app-webapp.md) for more information) Retrieves a collection of all active [Indicators](ti-indicator.md).
<br>Supports [OData V4 queries](https://www.odata.org/documentation/).
<br>The OData's ```$filter``` query is supported on: ```indicatorValue```, ```indicatorType```, ```creationTimeDateTimeUtc```, ```createdBy```, ```action``` and ```severity``` properties.
<br>See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
- Gets collection of TI Indicators. ## Limitations
- Get TI Indicators collection API supports [OData V4 queries](https://www.odata.org/documentation/). 1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
## Permissions ## 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) 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)
@ -36,7 +41,7 @@ Permission type | Permission | Permission display name
:---|:---|:--- :---|:---|:---
Application | Ti.ReadWrite | 'Read and write Indicators' Application | Ti.ReadWrite | 'Read and write Indicators'
Application | Ti.ReadWrite.All | 'Read and write All Indicators' Application | Ti.ReadWrite.All | 'Read and write All Indicators'
Delegated (work or school account) | Ti.ReadWrite | 'Read and write Indicators'
## HTTP request ## HTTP request
``` ```
@ -82,26 +87,38 @@ Content-type: application/json
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators",
"value": [ "value": [
{ {
"id": "995",
"indicatorValue": "12.13.14.15", "indicatorValue": "12.13.14.15",
"indicatorType": "IpAddress", "indicatorType": "IpAddress",
"action": "Alert",
"application": "demo-test",
"source": "TestPrdApp",
"sourceType": "AadApp",
"title": "test", "title": "test",
"creationTimeDateTimeUtc": "2018-10-24T11:15:35.3688259Z", "creationTimeDateTimeUtc": "2018-10-24T11:15:35.3688259Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c", "createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z", "expirationTime": "2020-12-12T00:00:00Z",
"action": "Alert", "lastUpdateTime": "2019-10-24T10:54:23.2009016Z",
"lastUpdatedBy": TestPrdApp,
"severity": "Informational", "severity": "Informational",
"description": "test", "description": "test",
"recommendedActions": "test", "recommendedActions": "test",
"rbacGroupNames": [] "rbacGroupNames": []
}, },
{ {
"id": "996",
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", "indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1", "indicatorType": "FileSha1",
"action": "AlertAndBlock",
"application": null,
"source": "TestPrdApp",
"sourceType": "AadApp",
"title": "test", "title": "test",
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z", "creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c", "createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z", "expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock", "lastUpdateTime": "2019-10-24T10:54:23.2009016Z",
"lastUpdatedBy": TestPrdApp,
"severity": "Informational", "severity": "Informational",
"description": "test", "description": "test",
"recommendedActions": "TEST", "recommendedActions": "TEST",
@ -119,7 +136,7 @@ Content-type: application/json
Here is an example of a request that gets all Indicators with 'AlertAndBlock' action Here is an example of a request that gets all Indicators with 'AlertAndBlock' action
``` ```
GET https://api.securitycenter.windows.com/api/indicators?$filter=action eq 'AlertAndBlock' GET https://api.securitycenter.windows.com/api/indicators?$filter=action+eq+'AlertAndBlock'
``` ```
**Response** **Response**
@ -133,13 +150,19 @@ Content-type: application/json
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators",
"value": [ "value": [
{ {
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", "id": "997",
"indicatorValue": "111e7d15b0b3d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1", "indicatorType": "FileSha1",
"action": "AlertAndBlock",
"application": null,
"source": "TestPrdApp",
"sourceType": "AadApp",
"title": "test", "title": "test",
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z", "creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c", "createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z", "expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock", "lastUpdateTime": "2019-10-24T10:54:23.2009016Z",
"lastUpdatedBy": TestPrdApp,
"severity": "Informational", "severity": "Informational",
"description": "test", "description": "test",
"recommendedActions": "TEST", "recommendedActions": "TEST",

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

@ -18,18 +18,19 @@ ms.topic: article
# Submit or Update Indicator API # Submit or Update Indicator API
**Applies to:** **Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
- [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)
>[!NOTE] ## API description
> Currently this API is supported only for AppOnly context requests. (See [Get access with application context](exposed-apis-create-app-webapp.md) for more information) Submits or Updates new [Indicator](ti-indicator.md) entity.
- Submits or Updates new [Indicator](ti-indicator.md) entity. ## Limitations
1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
2. There is a limit of 5,000 active indicators per tenant.
>[!NOTE]
>There is a limit of 5000 indicators per tenant.
## Permissions ## 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) 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)
@ -38,6 +39,7 @@ Permission type | Permission | Permission display name
:---|:---|:--- :---|:---|:---
Application | Ti.ReadWrite | 'Read and write Indicators' Application | Ti.ReadWrite | 'Read and write Indicators'
Application | Ti.ReadWrite.All | 'Read and write All Indicators' Application | Ti.ReadWrite.All | 'Read and write All Indicators'
Delegated (work or school account) | Ti.ReadWrite | 'Read and write Indicators'
## HTTP request ## HTTP request
@ -63,16 +65,17 @@ Parameter | Type | Description
indicatorValue | String | Identity of the [Indicator](ti-indicator.md) entity. **Required** indicatorValue | String | Identity of the [Indicator](ti-indicator.md) entity. **Required**
indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url". **Required** indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url". **Required**
action | Enum | The action that will be taken if the indicator will be discovered in the organization. Possible values are: "Alert", "AlertAndBlock", and "Allowed". **Required** action | Enum | The action that will be taken if the indicator will be discovered in the organization. Possible values are: "Alert", "AlertAndBlock", and "Allowed". **Required**
title | String | Indicator alert title. **Optional** application | String | The application associated with the indicator. **Optional**
title | String | Indicator alert title. **Required**
description | String | Description of the indicator. **Required**
expirationTime | DateTimeOffset | The expiration time of the indicator. **Optional** expirationTime | DateTimeOffset | The expiration time of the indicator. **Optional**
severity | Enum | The severity of the indicator. possible values are: "Informational", "Low", "Medium" and "High". **Optional** severity | Enum | The severity of the indicator. possible values are: "Informational", "Low", "Medium" and "High". **Optional**
description | String | Description of the indicator. **Optional**
recommendedActions | String | TI indicator alert recommended actions. **Optional** recommendedActions | String | TI indicator alert recommended actions. **Optional**
## Response ## Response
- If successful, this method returns 200 - OK response code and the created / updated [Indicator](ti-indicator.md) entity in the response body. - If successful, this method returns 200 - OK response code and the created / updated [Indicator](ti-indicator.md) entity in the response body.
- If not successful: this method return 400 - Bad Request / 409 - Conflict with the failure reason. Bad request usually indicates incorrect body and Conflict can happen if you try to submit an Indicator that conflicts with an existing Indicator type or Action. - If not successful: this method return 400 - Bad Request. Bad request usually indicates incorrect body.
## Example ## Example
@ -84,40 +87,16 @@ Here is an example of the request.
POST https://api.securitycenter.windows.com/api/indicators POST https://api.securitycenter.windows.com/api/indicators
Content-type: application/json Content-type: application/json
{ {
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", "indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1", "indicatorType": "FileSha1",
"title": "test", "title": "test",
"application": "demo-test",
"expirationTime": "2020-12-12T00:00:00Z", "expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock", "action": "AlertAndBlock",
"severity": "Informational", "severity": "Informational",
"description": "test", "description": "test",
"recommendedActions": "TEST" "recommendedActions": "nothing"
} }
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators/$entity",
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1",
"title": "test",
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock",
"severity": "Informational",
"description": "test",
"recommendedActions": "TEST",
"rbacGroupNames": []
}
```
## Related topic ## Related topic
- [Manage indicators](manage-indicators.md) - [Manage indicators](manage-indicators.md)

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

@ -18,9 +18,11 @@ ms.topic: article
# Indicator resource type # Indicator resource type
**Applies to:** **Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
- [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)
- See the corresponding [Indicators page](https://securitycenter.windows.com/preferences2/custom_ti_indicators/files) in the portal.
Method|Return Type |Description Method|Return Type |Description
:---|:---|:--- :---|:---|:---
@ -28,23 +30,49 @@ Method|Return Type |Description
[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) | Submits [Indicator](ti-indicator.md) entity.
[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.
- See the corresponding [page](https://securitycenter.windows.com/preferences2/custom_ti_indicators/files) in the portal.
For more information on creating indicators, see [Manage indicators](manage-indicators.md).
## Properties ## Properties
Property | Type | Description Property | Type | Description
:---|:---|:--- :---|:---|:---
indicatorValue | String | Identity of the [Indicator](ti-indicator.md) entity. id | String | Identity of the [Indicator](ti-indicator.md) entity.
indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url" indicatorValue | String | The value of the [Indicator](ti-indicator.md).
title | String | Indicator alert title. indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url".
application | String | The application associated with the indicator.
action | Enum | The action that will be taken if the indicator will be discovered in the organization. Possible values are: "Alert", "AlertAndBlock", and "Allowed".
sourceType | Enum | "User" in case the Indicator created by a user (e.g. from the portal), "AadApp" in case it submitted using automated application via the API.
source | string | The name of the user/application that submitted the indicator.
createdBy | String | Unique identity of the user/application that submitted the indicator.
lastUpdatedBy | String | Identity of the user/application that last updated the indicator.
creationTimeDateTimeUtc | DateTimeOffset | The date and time when the indicator was created. creationTimeDateTimeUtc | DateTimeOffset | The date and time when the indicator was created.
createdBy | String | Identity of the user/application that submitted the indicator. expirationTime | DateTimeOffset | The expiration time of the indicator.
expirationTime | DateTimeOffset | The expiration time of the indicator lastUpdateTime | DateTimeOffset | The last time the indicator was updated.
action | Enum | The action that will be taken if the indicator will be discovered in the organization. Possible values are: "Alert", "AlertAndBlock", and "Allowed" severity | Enum | The severity of the indicator. possible values are: "Informational", "Low", "Medium" and "High".
severity | Enum | The severity of the indicator. possible values are: "Informational", "Low", "Medium" and "High" title | String | Indicator title.
description | String | Description of the indicator. description | String | Description of the indicator.
recommendedActions | String | Indicator alert recommended actions. recommendedActions | String | Recommended actions for the indicator.
rbacGroupNames | List of strings | RBAC group names where the indicator is exposed. Empty list in case it exposed to all groups. rbacGroupNames | List of strings | RBAC machine group names where the indicator is exposed and active. Empty list in case it exposed to all machines.
## Json representation
```json
{
"id": "994",
"indicatorValue": "881c0f10c75e64ec39d257a131fcd531f47dd2cff2070ae94baa347d375126fd",
"indicatorType": "FileSha256",
"action": "AlertAndBlock",
"application": null,
"source": "user@contoso.onmicrosoft.com",
"sourceType": "User",
"createdBy": "user@contoso.onmicrosoft.com",
"severity": "Informational",
"title": "Michael test",
"description": "test",
"recommendedActions": "nothing",
"creationTimeDateTimeUtc": "2019-12-19T09:09:46.9139216Z",
"expirationTime": null,
"lastUpdateTime": "2019-12-19T09:09:47.3358111Z",
"lastUpdatedBy": null,
"rbacGroupNames": ["team1"]
}
```