mirror of
https://github.com/MicrosoftDocs/windows-itpro-docs.git
synced 2025-05-14 14:27:22 +00:00
investigations
This commit is contained in:
Ben Alfasi
parent
32a0457882
commit
217a2019c9
@ -408,6 +408,12 @@
|
||||
####### [Stop and quarantine file](microsoft-defender-atp/stop-and-quarantine-file.md)
|
||||
####### [Initiate investigation (preview)](microsoft-defender-atp/initiate-autoir-investigation.md)
|
||||
|
||||
###### [Automated Investigation]()
|
||||
####### [Investigation methods and properties](microsoft-defender-atp/investigation.md)
|
||||
####### [List Investigation](microsoft-defender-atp/get-investigation-collection.md)
|
||||
####### [Get Investigation](microsoft-defender-atp/get-investigation-object.md)
|
||||
####### [Start Investigation](microsoft-defender-atp/start-investigation.md)
|
||||
|
||||
###### [Indicators]()
|
||||
####### [Indicators methods and properties](microsoft-defender-atp/ti-indicator.md)
|
||||
####### [Submit Indicator](microsoft-defender-atp/post-ti-indicator.md)
|
||||
|
||||
@ -0,0 +1,110 @@
|
||||
---
|
||||
title: List Investigations API
|
||||
description: Use this API to create calls related to get Investigations collection
|
||||
keywords: apis, graph api, supported apis, Investigations 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
|
||||
manager: dansimp
|
||||
audience: ITPro
|
||||
ms.collection: M365-security-compliance
|
||||
ms.topic: article
|
||||
---
|
||||
|
||||
# List Investigations API
|
||||
|
||||
**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
|
||||
Retrieves a collection of [Investigations](investigation.md).
|
||||
<br>Supports [OData V4 queries](https://www.odata.org/documentation/).
|
||||
<br>The OData's ```$filter``` query is supported on: ```startTime```, ```state```, ```machineId``` and ```triggeringAlertId``` properties.
|
||||
<br>See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
|
||||
|
||||
|
||||
## Limitations
|
||||
1. Maximum page size is 10,000.
|
||||
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 | Alert.Read.All | 'Read all alerts'
|
||||
Application | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||
Delegated (work or school account) | Alert.Read | 'Read alerts'
|
||||
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||
|
||||
>[!Note]
|
||||
> When obtaining a token using user credentials:
|
||||
>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles.md) for more information)
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
GET https://api.securitycenter.windows.com/api/investigations
|
||||
```
|
||||
|
||||
## 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 [Investigations](investigation.md) entities.
|
||||
|
||||
|
||||
[!include[Improve request performance](../../includes/improve-request-performance.md)]
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
**Request**
|
||||
|
||||
Here is an example of a request to get all investigations:
|
||||
|
||||
|
||||
```
|
||||
GET https://api.securitycenter.windows.com/api/investigations
|
||||
```
|
||||
|
||||
**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#Investigations",
|
||||
"value": [
|
||||
{
|
||||
"id": "63017",
|
||||
"startTime": "2020-01-06T14:11:34Z",
|
||||
"endTime": null,
|
||||
"state": "Running",
|
||||
"cancelledBy": null,
|
||||
"statusDetails": null,
|
||||
"machineId": "a69a22debe5f274d8765ea3c368d00762e057b30",
|
||||
"computerDnsName": "desktop-gtrcon0",
|
||||
"triggeringAlertId": "da637139166940871892_-598649278"
|
||||
}
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Get Investigation object API
|
||||
description: Use this API to create calls related to get Investigation object
|
||||
keywords: apis, graph api, supported apis, Investigation object
|
||||
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
|
||||
---
|
||||
|
||||
# Get Investigation API
|
||||
|
||||
**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
|
||||
Retrieves specific [Investigation](investigation.md) by its ID.
|
||||
<br> ID can be the investigation ID or the investigation triggering alert ID.
|
||||
|
||||
|
||||
## 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 ATP APIs](apis-intro.md)
|
||||
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Alert.Read.All | 'Read all alerts'
|
||||
Application | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||
Delegated (work or school account) | Alert.Read | 'Read alerts'
|
||||
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||
|
||||
>[!Note]
|
||||
> When obtaining a token using user credentials:
|
||||
>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles.md) for more information)
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
GET https://api.securitycenter.windows.com/api/investigations/{id}
|
||||
```
|
||||
|
||||
## 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 [Investigations](investigations.md) entity.
|
||||
|
||||
@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Investigation resource type
|
||||
description: Microsoft Defender ATP Investigation entity.
|
||||
keywords: apis, graph api, supported apis, get, alerts, investigations
|
||||
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
|
||||
---
|
||||
|
||||
# Investigation resource type
|
||||
|
||||
**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)
|
||||
|
||||
Represent an Automated Investigation entity in Microsoft Defender ATP.
|
||||
<br> See [Overview of automated investigations](automated-investigations.md) for more information.
|
||||
|
||||
## Methods
|
||||
Method|Return Type |Description
|
||||
:---|:---|:---
|
||||
[List Investigations](.md) | Investigation collection | Get a collection of Investigation
|
||||
[Get single Investigation](.md) | Investigation entity | Gets a single Investigation entity.
|
||||
[Start Investigation](.md) | Investigation entity | Starts Investigation on a machine.
|
||||
|
||||
|
||||
## Properties
|
||||
Property | Type | Description
|
||||
:---|:---|:---
|
||||
id | String | Identity of the investigation entity.
|
||||
startTime | DateTime Nullable | The date and time when the investigation was created.
|
||||
endTime | DateTime Nullable | The date and time when the investigation was completed.
|
||||
cancelledBy | String | The ID of the user/application that cancelled that investigation.
|
||||
investigationState | Enum | The current state of the investigation. Possible values are: 'Unknown', 'Terminated', 'SuccessfullyRemediated', 'Benign', 'Failed', 'PartiallyRemediated', 'Running', 'PendingApproval', 'PendingResource', 'PartiallyInvestigated', 'TerminatedByUser', 'TerminatedBySystem', 'Queued', 'InnerFailure', 'PreexistingAlert', 'UnsupportedOs', 'UnsupportedAlertType', 'SuppressedAlert'.
|
||||
statusDetails | String | Additional information about the state of the investigation.
|
||||
machineId | String | The ID of the machine on which the investigation is executed.
|
||||
computerDnsName | String | The name of the machine on which the investigation is executed.
|
||||
triggeringAlertId | String | The ID of the alert that triggered the investigation.
|
||||
|
||||
|
||||
## Json representation
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "63004",
|
||||
"startTime": "2020-01-06T13:05:15Z",
|
||||
"endTime": null,
|
||||
"state": "Running",
|
||||
"cancelledBy": null,
|
||||
"statusDetails": null,
|
||||
"machineId": "e828a0624ed33f919db541065190d2f75e50a071",
|
||||
"computerDnsName": "desktop-test123",
|
||||
"triggeringAlertId": "da637139127150012465_1011995739"
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,99 @@
|
||||
---
|
||||
title: Start Investigation API
|
||||
description: Use this API to start investigation on a machine.
|
||||
keywords: apis, graph api, supported apis, investigation
|
||||
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
|
||||
---
|
||||
|
||||
# Start Investigation API
|
||||
|
||||
**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
|
||||
Starts automated investigation on a machine.
|
||||
<br>See [Overview of automated investigations](automated-investigations.md) for more information.
|
||||
|
||||
|
||||
-------------------------- im here
|
||||
|
||||
## Limitations
|
||||
1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
|
||||
|
||||
|
||||
[!include[Machine actions note](../../includes/machineactionsnote.md)]
|
||||
|
||||
## 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.Isolate | 'Isolate machine'
|
||||
Delegated (work or school account) | Machine.Isolate | 'Isolate machine'
|
||||
|
||||
>[!Note]
|
||||
> When obtaining a token using user credentials:
|
||||
>- The user needs to have at least the following role permission: 'Active remediation actions' (See [Create and manage roles](user-roles.md) for more information)
|
||||
>- The 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
|
||||
```
|
||||
POST https://api.securitycenter.windows.com/api/machines/{id}/isolate
|
||||
```
|
||||
|
||||
## 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
|
||||
:---|:---|:---
|
||||
Comment | String | Comment to associate with the action. **Required**.
|
||||
IsolationType | String | Type of the isolation. Allowed values are: 'Full' or 'Selective'.
|
||||
|
||||
**IsolationType** controls the type of isolation to perform and can be one of the following:
|
||||
- Full – Full isolation
|
||||
- Selective – Restrict only limited set of applications from accessing the network (see [Isolate machines from the network](respond-machine-alerts.md#isolate-machines-from-the-network) for more details)
|
||||
|
||||
|
||||
## Response
|
||||
If successful, this method returns 201 - Created response code and [Machine Action](machineaction.md) in the response body.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
**Request**
|
||||
|
||||
Here is an example of the request.
|
||||
|
||||
[!include[Improve request performance](../../includes/improve-request-performance.md)]
|
||||
|
||||
```
|
||||
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/isolate
|
||||
Content-type: application/json
|
||||
{
|
||||
"Comment": "Isolate machine due to alert 1234",
|
||||
“IsolationType”: “Full”
|
||||
}
|
||||
|
||||
|
||||
- To unisolate a machine, see [Release machine from isolation](unisolate-machine.md).
|
||||
Loading…
x
Reference in New Issue
Block a user