From 2e60553f9e83e0e3b292fe5b0d324b71476b92a8 Mon Sep 17 00:00:00 2001 From: Ben Alfasi Date: Mon, 6 Jan 2020 23:02:39 +0200 Subject: [PATCH] inv --- windows/security/threat-protection/TOC.md | 1 - .../initiate-autoir-investigation.md | 98 ------------------- .../microsoft-defender-atp/oldTOC.txt | 7 +- .../start-investigation.md | 29 ++---- 4 files changed, 14 insertions(+), 121 deletions(-) delete mode 100644 windows/security/threat-protection/microsoft-defender-atp/initiate-autoir-investigation.md diff --git a/windows/security/threat-protection/TOC.md b/windows/security/threat-protection/TOC.md index 0ef79d47cd..718168a1c9 100644 --- a/windows/security/threat-protection/TOC.md +++ b/windows/security/threat-protection/TOC.md @@ -406,7 +406,6 @@ ####### [Run antivirus scan](microsoft-defender-atp/run-av-scan.md) ####### [Offboard machine](microsoft-defender-atp/offboard-machine-api.md) ####### [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) diff --git a/windows/security/threat-protection/microsoft-defender-atp/initiate-autoir-investigation.md b/windows/security/threat-protection/microsoft-defender-atp/initiate-autoir-investigation.md deleted file mode 100644 index f875c8027f..0000000000 --- a/windows/security/threat-protection/microsoft-defender-atp/initiate-autoir-investigation.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Initiate machine investigation API -description: Use this API to create calls related to initiating an investigation on a machine. -keywords: apis, graph api, supported apis, initiate AutoIR 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 ---- - -# Initiate machine investigation API (Preview) -**Applies to:** -- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) - -> [!IMPORTANT] -> Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. - -Initiate AutoIR investigation on a machine. - ->[!Note] -> This page focuses on performing an automated investigation on a machine. See [automated investigation](automated-investigations.md) for more information. - -## Limitations -1. The number of executions is limited (up to 5 calls per hour). -2. For Automated Investigation limitations, see [Automated Investigation](automated-investigations.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 | Alert.ReadWrite.All | 'Read and write all 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: 'Alerts Investigation' (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}/InitiateInvestigation -``` - -## 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**. - -## Response -If successful, this method returns 200 OK response code with object that holds the investigation ID in the "value" parameter. If machine was not found - 404 Not Found. - -## 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/fb9ab6be3965095a09c057be7c90f0a2/InitiateInvestigation -Content-type: application/json -{ - "Comment": "Initiate an investigation on machine fb9ab6be3965095a09c057be7c90f0a2" -} -``` - -**Response** - -Here is an example of the response. - -``` -HTTP/1.1 200 Created -Content-type: application/json -{ - "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Edm.Int64", - "value": 5146 -} - -``` diff --git a/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt b/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt index c4263e9958..b17e58e0c5 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt +++ b/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt @@ -380,7 +380,12 @@ ####### [Run antivirus scan](run-av-scan.md) ####### [Offboard machine](offboard-machine-api.md) ####### [Stop and quarantine file](stop-and-quarantine-file.md) -####### [Initiate investigation (preview)](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]() ####### [Methods and properties](ti-indicator.md) diff --git a/windows/security/threat-protection/microsoft-defender-atp/start-investigation.md b/windows/security/threat-protection/microsoft-defender-atp/start-investigation.md index c096992dab..3e95295b96 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/start-investigation.md +++ b/windows/security/threat-protection/microsoft-defender-atp/start-investigation.md @@ -24,25 +24,21 @@ ms.topic: article ## API description -Starts automated investigation on a machine. +Start automated investigation on a machine.
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. +1. Rate limitations for this API are 50 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' +Application | Alert.ReadWrite.All | 'Read and write all alerts' +Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' >[!Note] > When obtaining a token using user credentials: @@ -52,7 +48,7 @@ Delegated (work or school account) | Machine.Isolate | 'Isolate machine' ## HTTP request ``` -POST https://api.securitycenter.windows.com/api/machines/{id}/isolate +POST https://api.securitycenter.microsoft.com/api/machines/{id}/startInvestigation ``` ## Request headers @@ -68,15 +64,10 @@ 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. +If successful, this method returns 201 - Created response code and [Investigation](investigation.md) in the response body. ## Example @@ -88,12 +79,8 @@ 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 +POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/startInvestigation Content-type: application/json { - "Comment": "Isolate machine due to alert 1234", - “IsolationType”: “Full” + "Comment": "Test investigation", } - - -- To unisolate a machine, see [Release machine from isolation](unisolate-machine.md).