deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-15 02:13:43 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'atp-new-api' of https://cpubwin.visualstudio.com/_git/it-client into atp-new-api

Browse Source
This commit is contained in:
Joey Caparas
2018-11-09 15:47:01 -08:00
parent 0206ec790b 63f648a3ab
commit af02bf3a38
18 changed files with 463 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -350,6 +350,7 @@
####### [User](windows-defender-atp/user-windows-defender-advanced-threat-protection-new.md)
######## [Get user related alerts](windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md)
######## [Get user related machines](windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.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)

2
windows/security/threat-protection/windows-defender-atp/create-alert-by-reference-windows-defender-advanced-threat-protection-new.md
View File

@ -39,7 +39,7 @@ Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
## HTTP request
```
POST /api/CreateAlertByReference
POST https://api.securitycenter.windows.com/api/CreateAlertByReference
```
## Request headers

1
windows/security/threat-protection/windows-defender-atp/custom-ti-api-windows-defender-advanced-threat-protection.md
View File

@ -187,7 +187,6 @@ The API currently supports the following IOC types:
- Sha1
- Sha256
- Md5
- FileName
- IpAddress
- DomainName

77
windows/security/threat-protection/windows-defender-atp/delete-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,77 @@
---
title: Delete Ti Indicator.
description: Deletes Ti Indicator entity by ID.
keywords: apis, public api, supported apis, delete, ti indicator, entity, id
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: 12/08/2017
---
# Delete TI Indicator API
[!include[Prerelease<73>information](prerelease.md)]
>[!Note]
> Currently this API is supported only for AppOnly context requests. (See [Get access without a user](exposed-apis-create-app-webapp.md) for more information)
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a TI Indicator entity by ID.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Ti.ReadWrite | 'Read and write TI Indicators'
## HTTP request
```
Delete https://api.securitycenter.windows.com/api/tiindicators/{id}
```
[!include[Improve request performance](improverequestperformance-new.md)]
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If TI Indicator exist and deleted successfully - 204 OK without content.
If TI Indicator with the specified id was not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
```
DELETE https://api.securitycenter.windows.com/api/tiindicators/220e7d15b0b3d7fac48f2bd61114db1022197f7f
```
**Response**
Here is an example of the response.
```
HTTP/1.1 204 NO CONTENT
```

2
windows/security/threat-protection/windows-defender-atp/exposed-apis-full-sample-powershell.md
View File

@ -101,7 +101,7 @@ $query = "NetworkCommunicationEvents
| where RemoteUrl == `"$suspiciousUrl`"
| summarize ConnectionsCount = count() by MachineId"
$queryUrl = "https://api.securitycenter.windows.com/advancedqueries/query"
$queryUrl = "https://api.securitycenter.windows.com/api/advancedqueries/run"
$queryBody = ConvertTo-Json -InputObject @{ 'Query' = $query }
$queryResponse = Invoke-WebRequest -Method Post -Uri $queryUrl -Headers $headers -Body $queryBody -ErrorAction Stop

4
windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md
View File

@ -13,7 +13,7 @@ ms.localizationpriority: medium
ms.date: 12/08/2017
---
# List machineActions API
# List MachineActions API
[!include[Prerelease<73>information](prerelease.md)]
@ -140,7 +140,7 @@ Here is an example of the response.
HTTP/1.1 200 Ok
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/testwdatppreview/$metadata#MachineActions",
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions",
"value": [
{
"id": "69dc3630-1ccc-4342-acf3-35286eec741d",

2
windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection-new.md
View File

@ -23,7 +23,7 @@ ms.date: 12/08/2017
Retrieves a collection of machines that have communicated with WDATP cloud on the last 30 days.
Get Machines collection API supports [OData V4 queries](https://www.odata.org/documentation/).
The OData's Filter query is supported on: "Id", "ComputerDnsName", "LastSeen", "LastIpAddress", "HealthStatus", "OsPlatform", "RiskScore" and "RbacGroupId"
The OData's Filter query is supported on: "Id", "ComputerDnsName", "LastSeen", "LastIpAddress", "HealthStatus", "OsPlatform", "RiskScore", "MachineTags" and "RbacGroupId"
## Permissions

92
windows/security/threat-protection/windows-defender-atp/get-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,92 @@
---
title: Get Ti Indicator by ID API
description: Retrieves Ti Indicator entity by ID.
keywords: apis, public api, supported apis, get, ti indicator, entity, id
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: 12/08/2017
---
# Get TI Indicator by ID API
[!include[Prerelease<73>information](prerelease.md)]
>[!Note]
> Currently this API is supported only for AppOnly context requests. (See [Get access without a user](exposed-apis-create-app-webapp.md) for more information)
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Retrieves a TI Indicator entity by ID.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Ti.ReadWrite | 'Read and write TI Indicators'
## HTTP request
```
GET https://api.securitycenter.windows.com/api/tiindicators/{id}
```
[!include[Improve request performance](improverequestperformance-new.md)]
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful and TI Indicator exists - 200 OK with the [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity in the body.
If TI Indicator with the specified id was not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
```
GET https://api.securitycenter.windows.com/api/tiindicators/220e7d15b0b3d7fac48f2bd61114db1022197f7f
```
**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#TiIndicators/$entity",
"indicator": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1",
"title": "test",
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
"createdBy": "45097602-0cfe-4cc6-925f-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock",
"severity": "Informational",
"description": "test",
"recommendedActions": "TEST"
}
```

109
windows/security/threat-protection/windows-defender-atp/get-ti-indicators-collection-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,109 @@
---
title: List TiIndicators API
description: Use this API to create calls related to get TiIndicators collection
keywords: apis, public api, supported apis, TiIndicators collection
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: 12/08/2017
---
# List TiIndicators API
[!include[Prerelease<73>information](prerelease.md)]
>[!Note]
> Currently this API is supported only for AppOnly context requests. (See [Get access without a user](exposed-apis-create-app-webapp.md) for more information)
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
Gets collection of TI Indicators.
Get TI Indicators collection API supports [OData V4 queries](https://www.odata.org/documentation/).
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Ti.ReadWrite | 'Read and write TI Indicators'
## HTTP request
```
GET https://api.securitycenter.windows.com/api/tiindicators
```
[!include[Improve request performance](improverequestperformance-new.md)]
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
## Request body
Empty
## Response
If successful, this method returns 200, Ok response code with a collection of [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entities.
>[!Note]
> The response will only include TI Indicators that submitted by the calling Application.
## Example
**Request**
Here is an example of a request that gets all TI Indicators
```
GET https://api.securitycenter.windows.com/api/tiindicators
```
**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#TiIndicators",
"value": [
{
"indicator": "12.13.14.15",
"indicatorType": "IpAddress",
"title": "test",
"creationTimeDateTimeUtc": "2018-10-24T11:15:35.3688259Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock",
"severity": "Informational",
"description": "test",
"recommendedActions": "test"
},
{
"indicator": "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"
}
]
}
```

115
windows/security/threat-protection/windows-defender-atp/post-ti-indicator-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,115 @@
---
title: Submit or Update Ti Indicator API
description: Use this API to submit or Update Ti Indicator.
keywords: apis, graph api, supported apis, submit, ti, 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
ms.date: 12/08/2017
---
# Submit or Update TI Indicator API
[!include[Prerelease information](prerelease.md)]
>[!Note]
> Currently this API is supported only for AppOnly context requests. (See [Get access without a user](exposed-apis-create-app-webapp.md) for more information)
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
- Submits or Updates new [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Ti.ReadWrite | 'Read and write TI Indicators'
## HTTP request
```
POST https://api.securitycenter.windows.com/api/tiindicators
```
[!include[Improve request performance](improverequestperformance-new.md)]
## 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
:---|:---|:---
indicator | String | Identity of the [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity. **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**
title | String | TI indicator alert title. **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**
description | String | Description of the indicator. **Optional**
recommendedActions | String | TI indicator alert recommended actions. **Optional**
## Response
- If successful, this method returns 200 - OK response code and the created / updated [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.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 a TI Indicator with existing indicator value but with different Indicator type or Action.
## Example
**Request**
Here is an example of the request.
```
POST https://api.securitycenter.windows.com/api/tiindicators
Content-type: application/json
{
"indicator": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1",
"title": "test",
"expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock",
"severity": "Informational",
"description": "test",
"recommendedActions": "TEST"
}
```
**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#MachineActions/$entity",
"indicator": "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"
}
```

4
windows/security/threat-protection/windows-defender-atp/run-advanced-query-api.md
View File

@ -46,7 +46,7 @@ Delegated (work or school account) | AdvancedQuery.Read | 'Run advanced queries'
## HTTP request
```
POST /advancedqueries/query
POST https://api.securitycenter.windows.com/api/advancedqueries/run
```
## Request headers
@ -80,7 +80,7 @@ Here is an example of the request.
> - api-uk.securitycenter.windows.com
```
POST https://api.securitycenter.windows.com/advancedqueries/query
POST https://api.securitycenter.windows.com/api/advancedqueries/run
Content-type: application/json
{
"Query":"ProcessCreationEvents

10
windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-ms-flow.md
View File

@ -40,15 +40,15 @@ Use the following basic flow as an example.
![Image of MsFlow choose an action](images/ms-flow-choose-action.png)
- Set method to be POST
- Uri is https://api.securitycenter.windows.com/advancedqueries/query or one of the region specific locations
- US: https://api-us.securitycenter.windows.com/advancedqueries/query
- Europe: https://api-eu.securitycenter.windows.com/advancedqueries/query
- United Kingdom: https://api-uk.securitycenter.windows.com/advancedqueries/query
- Uri is https://api.securitycenter.windows.com/api/advancedqueries/run or one of the region specific locations
- US: https://api-us.securitycenter.windows.com/api/advancedqueries/run
- Europe: https://api-eu.securitycenter.windows.com/api/advancedqueries/run
- United Kingdom: https://api-uk.securitycenter.windows.com/api/advancedqueries/run
- Add the Header: Content-Type application/json
- In the body write your query surrounded by single quotation mark (')
- In the Advanced options select Authentication to be Active Directory OAuth
- Set the Tenant with proper AAD Tenant Id
- Audience is https://securitycenter.onmicrosoft.com/windowsatpservice
- Audience is https://api.securitycenter.windows.com
- Client ID is your application ID
- Credential Type should be Secret
- Secret is the application secret generated in the Azure Active directory.

2
windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-app-token.md
View File

@ -59,7 +59,7 @@ If you want to use **user token** instead please refer to [this](run-advanced-qu
AccessToken= AuthResponse[access_token],
Bearer = Text.Combine({"Bearer", AccessToken}, " "),
AdvancedHuntingUrl = "https://api.securitycenter.windows.com/advancedqueries/query",
AdvancedHuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries/run",
Response = Json.Document(Web.Contents(
AdvancedHuntingUrl,

17
windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-user-token.md
View File

@ -47,15 +47,12 @@ You first need to [create an app](exposed-apis-create-app-nativeapp.md).
let
Query = "MachineInfo | where EventTime > ago(7d) | summarize EventCount=count(), LastSeen=max(EventTime) by MachineId",
AdvancedHuntingUrl = "https://api.securitycenter.windows.com/advancedqueries/query",
Response = Json.Document(Web.Contents(
AdvancedHuntingUrl,
[
Query=[#"queryText"=Query]
]
)),
FormattedQuery= Uri.EscapeDataString(Query),
AdvancedHuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries?key=" & FormattedQuery,
Response = Json.Document(Web.Contents(AdvancedHuntingUrl)),
TypeMap = #table(
{ "Type", "PowerBiType" },
@ -83,7 +80,7 @@ You first need to [create an app](exposed-apis-create-app-nativeapp.md).
Results = Response[Results],
Rows = Table.FromRecords(Results, Schema[Name]),
Table = Table.TransformColumnTypes(Rows, Table.ToList(TypedSchema, (c) => {c{0}, c{2}}))
in Table
```

2
windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-powershell.md
View File

@ -71,7 +71,7 @@ Run the following query:
```
$query = 'RegistryEvents | limit 10' # Paste your own query here
$url = "https://api.securitycenter.windows.com/advancedqueries/query"
$url = "https://api.securitycenter.windows.com/api/advancedqueries/run"
$headers = @{
'Content-Type' = 'application/json'
Accept = 'application/json'

2
windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-python.md
View File

@ -71,7 +71,7 @@ where
```
query = 'RegistryEvents | limit 10' # Paste your own query here
url = "https://api.securitycenter.windows.com/advancedqueries/query"
url = "https://api.securitycenter.windows.com/api/advancedqueries/run"
headers = {
'Content-Type' : 'application/json',
'Accept' : 'application/json',

45
windows/security/threat-protection/windows-defender-atp/ti-indicator-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,45 @@
---
title: TiIndicator resource type
description: TiIndicator entity description.
keywords: apis, supported apis, get, TiIndicator, recent
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: 12/08/2017
---
# TI(threat intelligence) Indicator resource type
**Applies to:**
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
[!include[Prerelease<73>information](prerelease.md)]
Method|Return Type |Description
:---|:---|:---
[List TI Indicators](get-ti-indicators-collection-windows-defender-advanced-threat-protection-new.md) | [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) Collection | List [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entities.
[Get TI Indicator by ID](get-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md) | [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) | Gets the requested [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity.
[Submit TI Indicator](post-ti-indicator-windows-defender-advanced-threat-protection-new.md) | [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) | Submits [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity.
[Delete TI Indicator](delete-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md) | No Content | Deletes [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity.
# Properties
Property | Type | Description
:---|:---|:---
indicator | String | Identity of the [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity.
indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url"
title | String | Ti indicator alert title.
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
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"
description | String | Description of the indicator.
recommendedActions | String | TI indicator alert recommended actions.

4
windows/security/threat-protection/windows-defender-atp/update-alert-windows-defender-advanced-threat-protection-new.md
View File

@ -49,13 +49,13 @@ Content-Type | String | application/json. **Required**.
## Request body
In the request body, supply the values for the relevant fields that should be updated.Existing properties that are not included in the request body will maintain their previous values or be recalculated based on tchanges to other property values. For best performance you shouldn't include existing values that haven't change.
In the request body, supply the values for the relevant fields that should be updated.Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. For best performance you shouldn't include existing values that haven't change.
Property | Type | Description
:---|:---|:---
status | String | Specifies the current status of the alert. The property values are: 'New', 'InProgress' and 'Resolved'.
assignedTo | String | Owner of the alert
classification | String | Speficies the specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'.
classification | String | Specifies the specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'.
determination | String | Specifies the determination of the alert. The property values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other'