diff --git a/windows/threat-protection/TOC.md b/windows/threat-protection/TOC.md index 8604996ad8..3a9a5db10d 100644 --- a/windows/threat-protection/TOC.md +++ b/windows/threat-protection/TOC.md @@ -65,7 +65,7 @@ ###### [Restrict app execution](windows-defender-atp\respond-machine-alerts-windows-defender-advanced-threat-protection.md#restrict-app-execution) ###### [Remove app restriction](windows-defender-atp\respond-machine-alerts-windows-defender-advanced-threat-protection.md#remove-app-restriction) ###### [Isolate machines from the network](windows-defender-atp\respond-machine-alerts-windows-defender-advanced-threat-protection.md#isolate-machines-from-the-network) -###### [Release machine from the isolation](windows-defender-atp\respond-machine-alerts-windows-defender-advanced-threat-protection.md#release-machine-from-isolation) +###### [Release machine from isolation](windows-defender-atp\respond-machine-alerts-windows-defender-advanced-threat-protection.md#release-machine-from-isolation) ###### [Check activity details in Action center](windows-defender-atp\respond-machine-alerts-windows-defender-advanced-threat-protection.md#check-activity-details-in-action-center) ##### [Take response actions on a file](windows-defender-atp\respond-file-alerts-windows-defender-advanced-threat-protection.md) ###### [Stop and quarantine files in your network](windows-defender-atp\respond-file-alerts-windows-defender-advanced-threat-protection.md#stop-and-quarantine-files-in-your-network) @@ -110,27 +110,51 @@ ###### [Get domain related machines](windows-defender-atp\get-domain-related-machines-windows-defender-advanced-threat-protection.md) ###### [Get domain statistics](windows-defender-atp\get-domain-statistics-windows-defender-advanced-threat-protection.md) ###### [Is domain seen in organization](windows-defender-atp\is-domain-seen-in-org-windows-defender-advanced-threat-protection.md) + ##### File +###### [Block file API](windows-defender-atp\block-file-windows-defender-advanced-threat-protection.md) ###### [Get file information](windows-defender-atp\get-file-information-windows-defender-advanced-threat-protection.md) ###### [Get file related alerts](windows-defender-atp\get-file-related-alerts-windows-defender-advanced-threat-protection.md) ###### [Get file related machines](windows-defender-atp\get-file-related-machines-windows-defender-advanced-threat-protection.md) ###### [Get file statistics](windows-defender-atp\get-file-statistics-windows-defender-advanced-threat-protection.md) +###### [Get FileActions collection API](windows-defender-atp\get-fileactions-collection-windows-defender-advanced-threat-protection.md) +###### [Unblock file API](windows-defender-atp\unblock-file-windows-defender-advanced-threat-protection.md) + ##### IP ###### [Get IP related alerts](windows-defender-atp\get-ip-related-alerts-windows-defender-advanced-threat-protection.md) ###### [Get IP related machines](windows-defender-atp\get-ip-related-machines-windows-defender-advanced-threat-protection.md) ###### [Get IP statistics](windows-defender-atp\get-ip-statistics-windows-defender-advanced-threat-protection.md) ###### [Is IP seen in organization](windows-defender-atp\is-ip-seen-org-windows-defender-advanced-threat-protection.md) ##### Machines +###### [Collect investigation package API](windows-defender-atp\collect-investigation-package-windows-defender-advanced-threat-protection.md) ###### [Find machine information by IP](windows-defender-atp\find-machine-info-by-ip-windows-defender-advanced-threat-protection.md) ###### [Get machines](windows-defender-atp\get-machines-windows-defender-advanced-threat-protection.md) +###### [Get FileMachineAction object API](windows-defender-atp\get-filemachineaction-object-windows-defender-advanced-threat-protection.md) +###### [Get FileMachineActions collection API](windows-defender-atp\get-filemachineactions-collection-windows-defender-advanced-threat-protection.md) ###### [Get machine by ID](windows-defender-atp\get-machine-by-id-windows-defender-advanced-threat-protection.md) ###### [Get machine log on users](windows-defender-atp\get-machine-log-on-users-windows-defender-advanced-threat-protection.md) ###### [Get machine related alerts](windows-defender-atp\get-machine-related-alerts-windows-defender-advanced-threat-protection.md) +###### [Get MachineAction object API](windows-defender-atp\get-machineaction-object-windows-defender-advanced-threat-protection.md) +###### [Get MachineActions collection API](windows-defender-atp\get-machineactions-collection-windows-defender-advanced-threat-protection.md) +###### [Get machines](windows-defender-atp\get-machines-windows-defender-advanced-threat-protection.md) +###### [Get package SAS URI API](windows-defender-atp\get-package-sas-uri-windows-defender-advanced-threat-protection.md) +###### [Isolate machine API](windows-defender-atp\isolate-machine-windows-defender-advanced-threat-protection.md) +###### [Release machine from isolation API](windows-defender-atp\unisolate-machine-windows-defender-advanced-threat-protection.md) +###### [Remove app restriction API](windows-defender-atp\unrestrict-code-execution-windows-defender-advanced-threat-protection.md) +###### [Request sample API](windows-defender-atp\request-sample-windows-defender-advanced-threat-protection.md) +###### [Restrict app execution API](windows-defender-atp\restrict-code-execution-windows-defender-advanced-threat-protection.md) +###### [Run antivirus scan API](windows-defender-atp\run-av-scan-windows-defender-advanced-threat-protection.md) +###### [Stop and quarantine file API](windows-defender-atp\stop-quarantine-file-windows-defender-advanced-threat-protection.md) + + + ##### User ###### [Get alert related user information](windows-defender-atp\get-alert-related-user-info-windows-defender-advanced-threat-protection.md) ###### [Get user information](windows-defender-atp\get-user-information-windows-defender-advanced-threat-protection.md) ###### [Get user related alerts](windows-defender-atp\get-user-related-alerts-windows-defender-advanced-threat-protection.md) ###### [Get user related machines](windows-defender-atp\get-user-related-machines-windows-defender-advanced-threat-protection.md) + + ### [Create and build Power BI reports using Windows Defender ATP data](windows-defender-atp\powerbi-reports-windows-defender-advanced-threat-protection.md) ### [Check sensor state](windows-defender-atp\check-sensor-status-windows-defender-advanced-threat-protection.md) #### [Fix unhealthy sensors](windows-defender-atp\fix-unhealhty-sensors-windows-defender-advanced-threat-protection.md) diff --git a/windows/threat-protection/windows-defender-atp/block-file-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/block-file-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..2f0c164f77 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/block-file-windows-defender-advanced-threat-protection.md @@ -0,0 +1,91 @@ +--- +title: Block file API +description: Use this API to blocking files from being running in the organization. +keywords: apis, graph api, supported apis, block file +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Block file API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Prevent a file from being executed in the organization using Windows Defender Antivirus. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/files/{sha1}/block +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. +Content-Type | application/json + +## 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 empty body, which indicates that block message was sent to Windows Defender deployed in the organization. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/files/7327b54fd718525cbca07dacde913b5ac3c85673/block +Content-type: application/json +{ + "Comment": "Block file due to alert 32123" +} + + +``` + +Response + +Here is an example of the response. + + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "fileIdentifier": "7327b54fd718525cbca07dacde913b5ac3c85673", + "fileIdentifierType": "Sha1", + "actionType": "Block", + "fileStatus": "Blocked", + "creationDateTimeUtc": "2017-12-04T13:06:23.4502191Z", + "requestor": "Analyst@contoso.com ", + "requestorComment": "test", + "cancellationDateTimeUtc": null, + "cancellationRequestor": null, + "cancellationComment": null, + "lastUpdateDateTimeUtc": "2017-12-04T13:06:23.4502191Z" +} + +``` diff --git a/windows/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..9e23f63821 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection.md @@ -0,0 +1,90 @@ +--- +title: Collect investigation package API +description: Use this API to create calls related to the collecting an investigation package from a machine. +keywords: apis, graph api, supported apis, collect investigation package +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Collect investigation package API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Collect investigation package from a machine. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/machines/{id}/collectInvestigationPackage +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. Required. +Content-Type | application/json + +## Request body +In the request body, supply a JSON object with the following parameters: + +Parameter | Type | Description +:---|:---|:--- +Comment | Text | Comment to associate with the action. **Required**. + +## Response +If successful, this method returns 201, Created response code and _MachineAction_ object in the response body. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/machines/fb9ab6be3965095a09c057be7c90f0a2/collectInvestigationPackage +Content-type: application/json +{ + "Comment": "Collect forensics due to alert 1234" +} +``` + +Response + +Here is an example of the response. + +>[!NOTE] +>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#MachineActions/$entity", + "id": "c9042f9b-8483-4526-87b5-35e4c2532223", + "type": "CollectInvestigationPackage", + "requestor": "Analyst@contoso.com ", + "requestorComment": " Collect forensics due to alert 1234", + "status": "InProgress", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:09:24.1785079Z", + "lastUpdateTimeUtc": "2017-12-04T12:09:24.1785079Z" +} + + +``` diff --git a/windows/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection.md index fe5e562014..c654298268 100644 --- a/windows/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Find machine information by interal IP +# Find machine information by interal IP API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Find a machine entity around a specific timestamp by FQDN or internal IP. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md index b28a278ecb..52ece2cd59 100644 --- a/windows/threat-protection/windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md @@ -10,10 +10,18 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get actor information + +# Get actor information API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves an actor information report. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md index 08e20bead6..bf950ccad7 100644 --- a/windows/threat-protection/windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get actor related alerts +# Get actor related alerts API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves all alerts related to a given actor. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md index 6945987aa5..ea7ebc034a 100644 --- a/windows/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get alert information by ID +# Get alert information by ID API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves an alert by its ID. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md index a4742809ed..4936276d33 100644 --- a/windows/threat-protection/windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get alert related actor information +# Get alert related actor information API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves the actor information related to the specific alert. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md index 79c8c92ff7..8585e21488 100644 --- a/windows/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get alert related domain information +# Get alert related domain information API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves all domains related to a specific alert. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md index eff63d46af..5c00116cbb 100644 --- a/windows/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get alert related files information +# Get alert related files information API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves all files related to a specific alert. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md index 36d9343342..1422fd9d29 100644 --- a/windows/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get alert related IP information +# Get alert related IP information API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves all IPs related to a specific alert. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md index b61e99975b..1a6856dd1b 100644 --- a/windows/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get alert related machine information +# Get alert related machine information API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves all machines related to a specific alert. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection.md index 56dfc41f3b..322e415d1e 100644 --- a/windows/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get alert related user information +# Get alert related user information API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves the user associated to a specific alert. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md index ce20500f97..f0da636e39 100644 --- a/windows/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md @@ -10,12 +10,20 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get alerts +# Get alerts API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves top recent alerts. + ## Permissions User needs read permissions. diff --git a/windows/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md index 1525f4a7bb..c96b12cd50 100644 --- a/windows/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get domain related alerts +# Get domain related alerts API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a collection of alerts related to a given domain address. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection.md index 8d7f5c0266..69f702f7c9 100644 --- a/windows/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get domain related machines +# Get domain related machines API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a collection of machines related to a given domain address. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection.md index 4484c7c8ae..32271f2620 100644 --- a/windows/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get domain statistics +# Get domain statistics API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves the prevalence for the given domain. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection.md index 7192369f0f..b3a3eefa7b 100644 --- a/windows/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection.md @@ -10,10 +10,18 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get file information +# Get file information API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + + Retrieves a file by identifier Sha1, Sha256, or MD5. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection.md index 3d3ec62f57..fae00da926 100644 --- a/windows/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get file related alerts +# Get file related alerts API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a collection of alerts related to a given file hash. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection.md index 959c6f43e8..1332ba931e 100644 --- a/windows/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get file related machines +# Get file related machines API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a collection of machines related to a given file hash. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection.md index 705e48b901..a642184c9d 100644 --- a/windows/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get file statistics +# Get file statistics API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves the prevalence for the given file. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-fileactions-collection-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-fileactions-collection-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..21560e7198 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/get-fileactions-collection-windows-defender-advanced-threat-protection.md @@ -0,0 +1,115 @@ +--- +title: Get FileActions collection API +description: Use this API to create calls related to get fileactions collection +keywords: apis, graph api, supported apis, get, file, information, fileactions collection +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Get FileActions collection API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Gets collection of actions done on files. Get FileActions collection API supports OData V4 queries. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +GET /testwdatppreview/fileactions +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200, Ok response code with a collection of FileAction objects. + +>[!NOTE] +>Although Block and Unblock actions are under FileAction category, this API only returns the Block actions on files that are currently blocked. For example, a file that is blocked and then unblocked will not be seen on this API. + + + +## Example + +Request + +Here is an example of the request on an organization that has three FileActions. + +``` +GET https://graph.microsoft.com/testwdatppreview/fileactions +``` + +Response + +Here is an example of the response. + + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#FileActions", + "value": [ + { + "fileIdentifier": "87662bc3d60e4200ceaf7aae249d1c343f4b83c9", + "fileIdentifierType": "Sha1", + "actionType": "Block", + "fileStatus": "Blocked", + "creationDateTimeUtc": "2017-12-04T13:06:23.4502191Z", + "requestor": "Analyst@contoso.com ", + "requestorComment": "test", + "cancellationDateTimeUtc": null, + "cancellationRequestor": null, + "cancellationComment": null, + "lastUpdateDateTimeUtc": "2017-12-04T13:06:23.4502191Z" + }, + { + "fileIdentifier": "df708f0107c7cc75ba2e5aaadc88b8bcfa01071d", + "fileIdentifierType": "Sha1", + "actionType": "Block", + "fileStatus": "Blocked", + "creationDateTimeUtc": "2017-11-05T11:16:19.9209438Z", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "1316", + "cancellationDateTimeUtc": null, + "cancellationRequestor": null, + "cancellationComment": null, + "lastUpdateDateTimeUtc": "2017-11-05T11:16:19.9209438Z" + }, + { + "fileIdentifier": "f5bc0981641c8a1fb3ef03e4bf574d8adf7134cf", + "fileIdentifierType": "Sha1", + "actionType": "Block", + "fileStatus": "Blocked", + "creationDateTimeUtc": "2017-11-05T10:57:02.2430564Z", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "test 1256 2017.11.05", + "cancellationDateTimeUtc": null, + "cancellationRequestor": null, + "cancellationComment": null, + "lastUpdateDateTimeUtc": "2017-11-05T10:57:02.2430564Z" + } + ] +} + +``` diff --git a/windows/threat-protection/windows-defender-atp/get-filemachineaction-object-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-filemachineaction-object-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..6d6d936711 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/get-filemachineaction-object-windows-defender-advanced-threat-protection.md @@ -0,0 +1,87 @@ +--- +title: Get FileMachineAction object API +description: Use this API to create calls related to get machineaction object +keywords: apis, graph api, supported apis, filemachineaction object +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Get FileMachineAction object API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Gets file and machine actions. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +GET /testwdatppreview/filemachineactions/{id} +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200, Ok response code with the *FileMachineAction* object. + + +## Example + +Request + +Here is an example of the request. + +``` +GET https://graph.microsoft.com/testwdatppreview/filemachineactions/3dc88ce3-dd0c-40f7-93fc-8bd14317aab6 +``` + +Response + +Here is an example of the response. + + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#FileMachineActions/$entity", + "id": "3dc88ce3-dd0c-40f7-93fc-8bd14317aab6", + "sha1": "8908b4441a2cd7285fe9c82917f69041cd467cf7", + "type": "StopAndQuarantineFile", + "requestor": "Analyst@contoso.com ", + "requestorComment": "1104", + "status": "Succeeded", + "fileId": "8908b4441a2cd7285fe9c82917f69041cd467cf7", + "machineId": "61a2d326d2190d048950406b54af23416118094a", + "creationDateTimeUtc": "2017-09-06T08:04:06.1994034Z", + "lastUpdateDateTimeUtc": "2017-09-06T08:05:46.9200942Z", + "fileInstances": [ + { + "filePath": "C:\\tools\\PE\\7f06a650-040b-4774-bb39-5264ea9e93fa.exe", + "status": "Succeeded" + } + ] +} + + +``` diff --git a/windows/threat-protection/windows-defender-atp/get-filemachineactions-collection-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-filemachineactions-collection-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..013b12118a --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/get-filemachineactions-collection-windows-defender-advanced-threat-protection.md @@ -0,0 +1,174 @@ +--- +title: Get FileMachineActions collection API +description: Use this API to create calls related to get filemachineactions collection +keywords: apis, graph api, supported apis, filemachineactions collection +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Get FileMachineActions collection API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Get collection of file and machine actions. Get FileMachineActions collection API supports OData V4 queries. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +GET /testwdatppreview/filemachineactions +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200, Ok response code with a collection of FileMachineAction objects since the Retention policy time of the organization. + + +## Example 1 + +Request + +Here is an example of the request on an organization that has three FileMachineActions. + +``` +GET https://graph.microsoft.com/testwdatppreview/filemachineactions +``` + +Response + +Here is an example of the response. + + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#FileActions", + "value": [ + { + "fileIdentifier": "87662bc3d60e4200ceaf7aae249d1c343f4b83c9", + "fileIdentifierType": "Sha1", + "actionType": "Block", + "fileStatus": "Blocked", + "creationDateTimeUtc": "2017-12-04T13:06:23.4502191Z", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "test", + "cancellationDateTimeUtc": null, + "cancellationRequestor": null, + "cancellationComment": null, + "lastUpdateDateTimeUtc": "2017-12-04T13:06:23.4502191Z" + }, + { + "fileIdentifier": "df708f0107c7cc75ba2e5aaadc88b8bcfa01071d", + "fileIdentifierType": "Sha1", + "actionType": "Block", + "fileStatus": "Blocked", + "creationDateTimeUtc": "2017-11-05T11:16:19.9209438Z", + "requestor": "Analyst@contoso.com ", + "requestorComment": "1316", + "cancellationDateTimeUtc": null, + "cancellationRequestor": null, + "cancellationComment": null, + "lastUpdateDateTimeUtc": "2017-11-05T11:16:19.9209438Z" + }, + { + "fileIdentifier": "f5bc0981641c8a1fb3ef03e4bf574d8adf7134cf", + "fileIdentifierType": "Sha1", + "actionType": "Block", + "fileStatus": "Blocked", + "creationDateTimeUtc": "2017-11-05T10:57:02.2430564Z", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "test 1256 2017.11.05", + "cancellationDateTimeUtc": null, + "cancellationRequestor": null, + "cancellationComment": null, + "lastUpdateDateTimeUtc": "2017-11-05T10:57:02.2430564Z" + } + ] +} + + +``` + +##Example 2 + +Request + +Here is an example of a request that filters the FileMachineActions by machine ID and shows the latest two FileMachineActions. + +``` +GET https://graph.microsoft.com/testwdatppreview/filemachineactions?$filter=machineId eq 'f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f'&$top=2 +``` + +Response + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#FileMachineActions", + "value": [ + { + "id": "6f1d364c-680c-499a-b30c-dd9265ad4c9d", + "sha1": "87662bc3d60e4200ceaf7aae249d1c343f4b83c9", + "type": "StopAndQuarantineFile", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "test", + "status": "Succeeded", + "fileId": "87662bc3d60e4200ceaf7aae249d1c343f4b83c9", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T13:13:26.2106524Z", + "lastUpdateDateTimeUtc": "2017-12-04T13:15:07.1639963Z", + "fileInstances": [ + { + "filePath": "C:\\Users\\ testUser \\Downloads\\elma.exe", + "status": "Succeeded" + }, + { + "filePath": "C:\\Users\\ testUser \\AppData\\Local\\Packages\\Microsoft.MicrosoftEdge_8wekyb3d8bbwe\\TempState\\Downloads\\elma (2).exe.xc9q785.partial", + "status": "Succeeded" + }, + ] + }, + { + "id": "c083f601-012f-4955-b4cc-fab50fb69d79", + "sha1": "8d25682b3a82af25b42dc90291c35ff3293daa68", + "type": "RequestSample", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "test", + "status": "Succeeded", + "fileId": "8d25682b3a82af25b42dc90291c35ff3293daa68", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T13:39:24.9399004Z", + "lastUpdateDateTimeUtc": "2017-12-04T13:40:01.1094743Z", + "fileInstances": [ + { + "filePath": "C:\\Windows\\System32\\conhost.exe", + "status": "Succeeded" + } + ] + } + ] +} +``` \ No newline at end of file diff --git a/windows/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection.md index 8dce7c9a29..e390e5f56a 100644 --- a/windows/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get IP related alerts +# Get IP related alerts API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a collection of alerts related to a given IP address. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md index 28df454b38..284901aa0d 100644 --- a/windows/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md @@ -10,10 +10,10 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get IP related machines +# Get IP related machines API Retrieves a collection of alerts related to a given IP address. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection.md index 009928645f..77c52c4e99 100644 --- a/windows/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get IP statistics +# Get IP statistics API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves the prevalence for the given IP. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection.md index 7c77806dc7..f9cd74d2b6 100644 --- a/windows/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get machine by ID +# Get machine by ID API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a machine entity by ID. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection.md index 3f3b1b24bc..ebcdf50543 100644 --- a/windows/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection.md @@ -10,10 +10,18 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get machine log on users +# Get machine log on users API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + + Retrieves a collection of logged on users. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection.md index 6819e1fd72..b5b335d796 100644 --- a/windows/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get machine related alerts +# Get machine related alerts API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a collection of alerts related to a given machine ID. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..f680ca3c8e --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection.md @@ -0,0 +1,80 @@ +--- +title: Get MachineAction object API +description: Use this API to create calls related to get machineaction object +keywords: apis, graph api, supported apis, machineaction object +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Get MachineAction object API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Get actions done on a machine. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +GET /testwdatppreview/machineactions/{id} +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200, Ok response code with the *MachineAction* object. + + +## Example + +Request + +Here is an example of the request. + +``` +GET https://graph.microsoft.com/testwdatppreview/machineactions/2e9da30d-27f6-4208-81f2-9cd3d67893ba +``` + +Response + +Here is an example of the response. + + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#MachineActions/$entity", + "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba", + "type": "RunAntiVirusScan", + "requestor": "Analyst@contoso.com ", + "requestorComment": "Check machine for viruses due to alert 3212", + "status": "Succeeded", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z", + "lastUpdateTimeUtc": "2017-12-04T12:18:57.5511934Z" +} + + +``` diff --git a/windows/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..fd36945114 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection.md @@ -0,0 +1,154 @@ +--- +title: Get MachineActions collection API +description: Use this API to create calls related to get machineactions collection +keywords: apis, graph api, supported apis, machineaction collection +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Get MachineActions collection API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + + Gets collection of actions done on machines. Get MachineAction collection API supports OData V4 queries. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +GET /testwdatppreview/machineactions +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200, Ok response code with a collection of MachineAction objects since the Retention policy time of the organization. + + +## Example 1 + +Request + +Here is an example of the request on an organization that has three MachineActions. + +``` +GET https://graph.microsoft.com/testwdatppreview/machineactions +``` + +Response + +Here is an example of the response. + + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#MachineActions", + "value": [ + { + "id": "69dc3630-1ccc-4342-acf3-35286eec741d", + "type": "CollectInvestigationPackage", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "test", + "status": "Succeeded", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:43:57.2011911Z", + "lastUpdateTimeUtc": "2017-12-04T12:45:25.4049122Z" + }, + { + "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba", + "type": "RunAntiVirusScan", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "Check machine for viruses due to alert 3212", + "status": "Succeeded", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z", + "lastUpdateTimeUtc": "2017-12-04T12:18:57.5511934Z" + }, + { + "id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e", + "type": "UnrestrictCodeExecution", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "test", + "status": "Succeeded", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:15:40.6052029Z", + "lastUpdateTimeUtc": "2017-12-04T12:16:14.2899973Z" + } + ] +} + + +``` + +## Example 2 + +Request + +Here is an example of a request that filters the MachineActions by machine ID and shows the latest two MachineActions. + +``` +GET https://graph.microsoft.com/testwdatppreview/machineactions?$filter=machineId eq 'f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f'&$top=2 +``` + + + +Response + +Here is an example of the response. + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#MachineActions", + "value": [ + { + "id": "69dc3630-1ccc-4342-acf3-35286eec741d", + "type": "CollectInvestigationPackage", + "requestor": "Analyst@contoso.com ", + "requestorComment": "test", + "status": "Succeeded", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:43:57.2011911Z", + "lastUpdateTimeUtc": "2017-12-04T12:45:25.4049122Z" + }, + { + "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba", + "type": "RunAntiVirusScan", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "Check machine for viruses due to alert 3212", + "status": "Succeeded", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z", + "lastUpdateTimeUtc": "2017-12-04T12:18:57.5511934Z" + } + ] +} +``` diff --git a/windows/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md index 8cb1cd4acc..c446711e57 100644 --- a/windows/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get machines +# Get machines API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a collection of recently seen machines. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..def484c73a --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection.md @@ -0,0 +1,75 @@ +--- +title: Get package SAS URI API +description: Use this API to get a URI that allows downloading an investigation package. +keywords: apis, graph api, supported apis, get package, sas, uri +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Get package SAS URI API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Get a URI that allows downloading of an investigation package. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/machineactions/{id}/getPackageUri +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. +Content-Type | application/json + + +## Request body +Empty + +## Response +If successful, this method returns 200, Ok response code with object that holds the link to the package in the “value” parameter. This link is valid for a very short time and should be used immediately for downloading the package to a local storage. + + +## Example + +Request + +Here is an example of the request. + +``` +GET https://graph.microsoft.com/testwdatppreview/machineactions/7327b54fd718525cbca07dacde913b5ac3c85673/GetPackageUri + +``` + +Response + +Here is an example of the response. + + +``` +HTTP/1.1 200 Ok +Content-type: application/json + +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#Edm.String", + "value": "\"https://userrequests-us.securitycenter.windows.com:443/safedownload/WDATP_Investigation_Package.zip?token=gbDyj7y%2fbWGAZjn2sFiZXlliBTXOCVG7yiJ6mXNaQ9pLByC2Wxeno9mENsPFP3xMk5l%2bZiJXjLvqAyNEzUNROxoM2I1er9dxzfVeBsxSmclJjPsAx%2btiNyxSz1Ax%2b5jaT5cL5bZg%2b8wgbwY9urXbTpGjAKh6FB1e%2b0ypcWkPm8UkfOwsmtC%2biZJ2%2bPqnkkeQk7SKMNoAvmh9%2fcqDIPKXGIBjMa0D9auzypOqd8bQXp7p2BnLSH136BxST8n9IHR4PILvRjAYW9kvtHkBpBitfydAsUW4g2oDZSPN3kCLBOoo1C4w4Lkc9Bc3GNU2IW6dfB7SHcp7G9p4BDkeJl3VuDs6esCaeBorpn9FKJ%2fXo7o9pdcI0hUPZ6Ds9hiPpwPUtz5J29CBE3QAopCK%2fsWlf6OW2WyXsrNRSnF1tVE5H3wXpREzuhD7S4AIA3OIEZKzC4jIPLeMu%2bazZU9xGwuc3gICOaokbwMJiZTqcUuK%2fV9YdBdjdg8wJ16NDU96Pl6%2fgew2KYuk6Wo7ZuHotgHI1abcsvdlpe4AvixDbqcRJthsg2PpLRaFLm5av44UGkeK6TJpFvxUn%2f9fg6Zk5yM1KUTHb8XGmutoCM8U9er6AzXZlY0gGc3D3bQOg41EJZkEZLyUEbk1hXJB36ku2%2bW01cG71t7MxMBYz7%2bdXobxpdo%3d%3bRWS%2bCeoDfTyDcfH5pkCg6hYDmCOPr%2fHYQuaUWUBNVnXURYkdyOzVHqp%2fe%2f1BNyPdVoVkpQHpz1pPS3b5g9h7IMmNKCk5gFq5m2nPx6kk9EYtzx8Ndoa2m9Yj%2bSaf8zIFke86YnfQL4AYewsnQNJJh4wc%2bXxGlBq7axDcoiOdX91rKzVicH3GSBkFoLFAKoegWWsF%2fEDZcVpF%2fXUA1K8HvB6dwyfy4y0sAqnNPxYTQ97mG7yHhxPt4Pe9YF2UPPAJVuEf8LNlQ%2bWHC9%2f7msF6UUI4%2fca%2ftpjFs%2fSNeRE8%2fyQj21TI8YTF1SowvaJuDc1ivEoeopNNGG%2bGI%2fX0SckaVxU9Hdkh0zbydSlT5SZwbSwescs0IpzECitBbaLUz4aT8KTs8T0lvx8D7Te3wVsKAJ1r3iFMQZrlk%2bS1WW8rvac7oHRx2HKURn1v7fDIQWgJr9aNsNlFz4fLJ50T2qSHuuepkLVbe93Va072aMGhvr09WVKoTpAf1j2bcFZZU6Za5PxI32mr0k90FgiYFJ1F%2f1vRDrGwvWVWUkR3Z33m4g0gHa52W1FMxQY0TJIwbovD6FaSNDx7xhKZSd5IJ7r6P91Gez49PaZRcAZPjd%2bfbul3JNm1VqQPTLohT7wa0ymRiXpSST74xtFzuEBzNSNATdbngj3%2fwV4JesTjZjIj5Dc%3d%3blumqauVlFuuO8MQffZgs0tLJ4Fq6fpeozPTdDf8Ll6XLegi079%2b4mSPFjTK0y6eohstxdoOdom2wAHiZwk0u4KLKmRkfYOdT1wHY79qKoBQ3ZDHFTys9V%2fcwKGl%2bl8IenWDutHygn5IcA1y7GTZj4g%3d%3d\"" +} + + +``` diff --git a/windows/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection.md index eeeffd2959..825ff7a13f 100644 --- a/windows/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get user information +# Get user information API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieve a User entity by key (user name or domain\user). ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md index 50cd175885..7d3c12a300 100644 --- a/windows/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get user related alerts +# Get user related alerts API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a collection of alerts related to a given user ID. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection.md index df33d8915a..779624c483 100644 --- a/windows/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- -# Get user related machines +# Get user related machines API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Retrieves a collection of machines related to a given user ID. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection.md index e87d3488a6..a203295bcd 100644 --- a/windows/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection.md @@ -10,10 +10,17 @@ ms.pagetype: security ms.author: macapara author: mjcaparas ms.localizationpriority: high -ms.date: 10/16/2017 +ms.date: 12/08/2017 --- # Is IP seen in org + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + Answers whether an IP was seen in the organization. ## Permissions diff --git a/windows/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..506bb47499 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection.md @@ -0,0 +1,96 @@ +--- +title: Isolate machine API +description: Use this API to create calls related isolating a machine. +keywords: apis, graph api, supported apis, isolate machine +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Isolate machine API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Isolates a machine from accessing external network. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/machines/{id}/isolate +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. +Content-Type | application/json + +## 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 | IsolationType | Full or selective isolation + +**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 + + +## Response +If successful, this method returns 201, Created response code and _MachineAction_ object in the response body. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/machines/fb9ab6be3965095a09c057be7c90f0a2/isolate +Content-type: application/json +{ + "Comment": "Isolate machine due to alert 1234", + “IsolationType”: “Full” +} + +``` +Response + +Here is an example of the response. + +>[!NOTE] +>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#MachineActions/$entity", + "id": "b89eb834-4578-496c-8be0-03f004061435", + "type": "Isolate", + "requestor": "Analyst@contoso.com ", + "requestorComment": "Isolate machine due to alert 1234", + "status": "InProgress", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:12:18.9725659Z", + "lastUpdateTimeUtc": "2017-12-04T12:12:18.9725659Z" +} + +``` diff --git a/windows/threat-protection/windows-defender-atp/request-sample-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/request-sample-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..2a6bf80ab0 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/request-sample-windows-defender-advanced-threat-protection.md @@ -0,0 +1,99 @@ +--- +title: Request sample API +description: Use this API to create calls related to requesting a sample from a machine. +keywords: apis, graph api, supported apis, request sample +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Request sample API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Request sample of a file from a specific machine. File will be collected from the machine and uploaded to a secure storage. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/machines/{id}/requestSample +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. +Content-Type | application/json + +## 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**. +Sha1 | String | Sha1 of the file to upload to the secure storage. **Required**. + +## Response +If successful, this method returns 201, Created response code and *FileMachineAction* object in the response body. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/machines/fb9ab6be3965095a09c057be7c90f0a2/requestSample +Content-type: application/json +{ + "Comment": "Request Sample on machine due to alert 32123", + "Sha1": "8d25682b3a82af25b42dc90291c35ff3293daa68" +} + +``` + +Response + +Here is an example of the response. + +>[!NOTE] +>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#FileMachineActions/$entity", + "id": "c083f601-012f-4955-b4cc-fab50fb69d79", + "sha1": "8d25682b3a82af25b42dc90291c35ff3293daa68", + "type": "RequestSample", + "requestor": "Analyst@contoso.com ", + "requestorComment": "test", + "status": "InProgress", + "fileId": "8d25682b3a82af25b42dc90291c35ff3293daa68", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T13:39:24.9399004Z", + "lastUpdateDateTimeUtc": "2017-12-04T13:39:24.9399004Z", + "fileInstances": [ + { + "filePath": "C:\\Windows\\System32\\conhost.exe", + "status": "InProgress" + } + ] +} + +``` diff --git a/windows/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..d6e18c2022 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection.md @@ -0,0 +1,89 @@ +--- +title: Restrict app execution API +description: Use this API to create calls related to restricting an application from executing. +keywords: apis, graph api, supported apis, collect investigation package +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Restrict app execution API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Restrict execution of set of predefined applications. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/machines/{id}/restrictCodeExecution +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. +Content-Type | application/json + +## 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 201, Created response code and _MachineAction_ object in the response body. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/machines/fb9ab6be3965095a09c057be7c90f0a2/restrictCodeExecution +Content-type: application/json +{ + "Comment": "Restrict code execution due to alert 1234" +} + +``` +Response + +Here is an example of the response. + +>[!NOTE] +>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#MachineActions/$entity", + "id": "78d408d1-384c-4c19-8b57-ba39e378011a", + "type": "RestrictCodeExecution", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "Restrict code execution due to alert 1234", + "status": "InProgress", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:15:04.3825985Z", + "lastUpdateTimeUtc": "2017-12-04T12:15:04.3825985Z" +} + +``` diff --git a/windows/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..9469fbc10a --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection.md @@ -0,0 +1,98 @@ +--- +title: Run antivirus scan API +description: Use this API to create calls related to running an antivirus scan on a machine. +keywords: apis, graph api, supported apis, remove machine from isolation +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Run antivirus scan API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Initiate Windows Defender Antivirus scan on the machine. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/machines/{id}/runAntiVirusScan +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. +Content-Type | application/json + +## 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**. +ScanType| ScanType | Defines the type of the Scan. **Required**. + +**ScanType** controls the type of isolation to perform and can be one of the following: + +- **Quick** – Perform quick scan on the machine +- **Full** – Perform full scan on the machine + + + +## Response +If successful, this method returns 201, Created response code and _MachineAction_ object in the response body. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/machines/fb9ab6be3965095a09c057be7c90f0a2/runAntiVirusScan +Content-type: application/json +{ + "Comment": "Check machine for viruses due to alert 3212", + “ScanType”: “Full” +} +``` + +Response + +Here is an example of the response. + +>[!NOTE] +>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#MachineActions/$entity", + "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba", + "type": "RunAntiVirusScan", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "Check machine for viruses due to alert 3212", + "status": "InProgress", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z", + "lastUpdateTimeUtc": "2017-12-04T12:18:27.1293487Z" +} + +``` diff --git a/windows/threat-protection/windows-defender-atp/stop-quarantine-file-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/stop-quarantine-file-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..44ac36d4ef --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/stop-quarantine-file-windows-defender-advanced-threat-protection.md @@ -0,0 +1,103 @@ +--- +title: Stop and quarantine file API +description: Use this API to create calls related to stopping and quarantining a file. +keywords: apis, graph api, supported apis, stop, quarantine, file +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Stop and quarantine file API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Stop execution of a file on a machine and ensure it’s not executed again on that machine. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/machines/{id}/stopAndQuarantineFile +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. +Content-Type | application/json + +## 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**. +Sha1 | String | Sha1 of the file to stop and quarantine on the machine. **Required**. + +## Response +If successful, this method returns 201, Created response code and _FileMachineAction_ object in the response body. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/machines/fb9ab6be3965095a09c057be7c90f0a2/stopAndQuarantineFile +Content-type: application/json +{ + "Comment": "Stop and quarantine file on machine due to alert 32123", + "Sha1": "87662bc3d60e4200ceaf7aae249d1c343f4b83c9" +} + +``` +Response + +Here is an example of the response. + +>[!NOTE] +>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#FileMachineActions/$entity", + "id": "6f1d364c-680c-499a-b30c-dd9265ad4c9d", + "sha1": "87662bc3d60e4200ceaf7aae249d1c343f4b83c9", + "type": "StopAndQuarantineFile", + "requestor": "Analyst@contoso.com ", + "requestorComment": " Stop and quarantine file on machine due to alert 32123", + "status": "InProgress", + "fileId": "87662bc3d60e4200ceaf7aae249d1c343f4b83c9", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T13:13:26.2106524Z", + "lastUpdateDateTimeUtc": "2017-12-04T13:13:58.8098277Z", + "fileInstances": [ + { + "filePath": "C:\\Users\\ testUser \\Downloads\\elma.exe", + "status": "InProgress" + }, + { + "filePath": "C:\\Users\\testUser\\AppData\\Local\\Packages\\Microsoft.MicrosoftEdge_8wekyb3d8bbwe\\TempState\\Downloads\\elma (2).exe.xc9q785.partial", + "status": "InProgress" + }, + ] + } + + +``` diff --git a/windows/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md index a8783ecd74..6277924353 100644 --- a/windows/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md +++ b/windows/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md @@ -1,5 +1,5 @@ --- -title: Supported Windows Defender Advanced Threat Protection APIs +title: Supported Windows Defender Advanced Threat Protection query APIs description: Learn about the specific supported Windows Defender Advanced Threat Protection entities where you can create API calls to. keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file search.product: eADQiWindows 10XVcnh @@ -13,7 +13,7 @@ ms.localizationpriority: high ms.date: 10/16/2017 --- -# Supported Windows Defender ATP APIs +# Supported Windows Defender ATP query APIs **Applies to:** diff --git a/windows/threat-protection/windows-defender-atp/supported-response-apis-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/supported-response-apis-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..70bff68a83 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/supported-response-apis-windows-defender-advanced-threat-protection.md @@ -0,0 +1,48 @@ +--- +title: Supported Windows Defender Advanced Threat Protection response APIs +description: Learn about the specific response related Windows Defender Advanced Threat Protection API calls. +keywords: response apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/01/2017 +--- + +# Supported Windows Defender ATP query APIs + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + +>Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-supported-response-apis-abovefoldlink) + +Learn about the supported response related API calls you can run and details such as the required request headers, and expected response from the calls. + +## In this section +Topic | Description +:---|:--- +Collect investigation package | Run this to collect an investigation package from a machine. +Isolate machine | Run this to isolate a machine from the network. +Unisolate machine | Remove a machine from isolation. +Restrict code execution | Run this to contain an attack by stopping malicious processes. You can also lock down a device and prevent subsequent attempts of potentially malicious programs from running. +Unrestrict code execution | Run this to reverse the restriction of applications policy after you have verified that the compromised machine has been remediated. +Run antivirus scan | Remotely initiate an antivirus scan to help identify and remediate malware that might be present on a compromised machine. +Stop and quarantine file | Run this call to stop running processes, quarantine files, and delete persistency such as registry keys. +Request sample | Run this call to request a sample of a file from a specific machine. The file will be collected from the machine and uploaded to a secure storage. +Block file | Run this to prevent further propagation of an attack in your organization by banning potentially malicious files or suspected malware. +Unblock file | Allow a file run in the organization using Windows Defender Antivirus. +Get package SAS URI | Run this to get a URI that allows downloading an investigation package. +Get MachineAction object | Run this to get MachineAction object. +Get MachineActions collection | Run this to get MachineAction collection. +Get FileActions collection | Run this to get FileActions collection. +Get FileMachineAction object | Run this to get FileMachineAction object. +Get FileMachineActions collection | Run this to get FileMachineAction collection. + + + diff --git a/windows/threat-protection/windows-defender-atp/unblock-file-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/unblock-file-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..a007aefd5d --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/unblock-file-windows-defender-advanced-threat-protection.md @@ -0,0 +1,89 @@ +--- +title: Unblock file API +description: Use this API to create calls related to allowing a file to be executed in the organization +keywords: apis, graph api, supported apis, unblock file +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Unblock file API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Allow a file to be executed in the organization, using Windows Defender Antivirus. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/files/{sha1}/unblock +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. +Content-Type | application/json + +## 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 empty body, which indicates that block message was sent to Windows Defender deployed in the organization. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/files/7327b54fd718525cbca07dacde913b5ac3c85673/unblock +Content-type: application/json +{ + "Comment": "Unblock file since alert 1234 was investigated and discovered to be false alarm", +} +``` + +Response + +Here is an example of the response. + + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "fileIdentifier": "7327b54fd718525cbca07dacde913b5ac3c85673", + "fileIdentifierType": "Sha1", + "actionType": "UnBlock", + "fileStatus": "Blocked", + "creationDateTimeUtc": "2017-12-04T13:06:23.4502191Z", + "requestor": "Analyst@contoso.com ", + "requestorComment": "test", + "cancellationDateTimeUtc": null, + "cancellationRequestor": null, + "cancellationComment": null, + "lastUpdateDateTimeUtc": "2017-12-04T13:06:23.4502191Z" +} + +``` diff --git a/windows/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..e45662c5cd --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection.md @@ -0,0 +1,90 @@ +--- +title: Release machine from isolation API +description: Use this API to create calls related to release a machine from isolation. +keywords: apis, graph api, supported apis, remove machine from isolation +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Release machine from isolation API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Undo isolation of a machine. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/machines/{id}/unisolate +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. +Content-Type | application/json + +## 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 201, Created response code and _MachineAction_ object in the response body. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/machines/fb9ab6be3965095a09c057be7c90f0a2/unisolate +Content-type: application/json +{ + "Comment": "Unisolate machine since it was clean and validated" +} + +``` +Response + +Here is an example of the response. + +>[!NOTE] +>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#MachineActions/$entity", + "id": "09a0f91e-a2eb-409d-af33-5577fe9bd558", + "type": "Unisolate", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "Unisolate machine since it was clean and validated ", + "status": "InProgress", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:13:15.0104931Z", + "lastUpdateTimeUtc": "2017-12-04T12:13:15.0104931Z" +} + + +``` diff --git a/windows/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection.md b/windows/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..67c98f2595 --- /dev/null +++ b/windows/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection.md @@ -0,0 +1,91 @@ +--- +title: Remove app restriction API +description: Use this API to create calls related to removing a restriction from applications from executing. +keywords: apis, graph api, supported apis, remove machine from isolation +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: high +ms.date: 12/08/2017 +--- + +# Remove app restriction API + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Unrestrict execution of set of predefined applications. + +## Permissions +Users need to have Security administrator or Global admin directory roles. + +## HTTP request +``` +POST /testwdatppreview/machines/{id}/unrestrictCodeExecution +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. Required. +Content-Type | application/json + +## 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 201, Created response code and _MachineAction_ object in the response body. + + +## Example + +Request + +Here is an example of the request. + +``` +POST https://graph.microsoft.com/testwdatppreview/machines/fb9ab6be3965095a09c057be7c90f0a2/unrestrictCodeExecution +Content-type: application/json +{ + "Comment": "Unrestrict code execution since machine was cleaned and validated" +} + +``` + +Response + +Here is an example of the response. + +>[!NOTE] +>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#MachineActions/$entity", + "id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e", + "type": "UnrestrictCodeExecution", + "requestor": "Analyst@ contoso.com ", + "requestorComment": "Unrestrict code execution since machine was cleaned and validated ", + "status": "InProgress", + "error": "None", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2017-12-04T12:15:40.6052029Z", + "lastUpdateTimeUtc": "2017-12-04T12:15:40.6052029Z" +} + + +```