diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 224abb8ddd..82a24ff791 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -524,6 +524,10 @@ "master": [ "Publish", "Pdf" + ], + "atp-api-danm": [ + "Publish", + "Pdf" ] }, "need_generate_pdf_url_template": true, diff --git a/windows/deployment/windows-autopilot/user-driven-hybrid.md b/windows/deployment/windows-autopilot/user-driven-hybrid.md index 88e4a87f15..a5fa678ff4 100644 --- a/windows/deployment/windows-autopilot/user-driven-hybrid.md +++ b/windows/deployment/windows-autopilot/user-driven-hybrid.md @@ -9,7 +9,7 @@ ms.sitesec: library ms.pagetype: deploy author: greg-lindsay ms.author: greg-lindsay -ms.date: 11/07/2018 +ms.date: 11/12/2018 --- @@ -23,7 +23,6 @@ Windows Autopilot requires that devices be Azure Active Directory joined. If you To perform a user-driven hybrid AAD joined deployment using Windows Autopilot: -- Users must be able to join devices to Azure Active Directory. - A Windows Autopilot profile for user-driven mode must be created and - **Hybrid Azure AD joined** must be specified as the selected option under **Join to Azure AD as** in the Autopilot profile. - If using Intune, a device group in Azure Active Directory must exist with the Windows Autopilot profile assigned to that group. @@ -32,6 +31,8 @@ To perform a user-driven hybrid AAD joined deployment using Windows Autopilot: - The Intune Connector for Active Directory must be installed. - Note: The Intune Connector will perform an on-prem AD join, therefore users do not need on-prem AD-join permission, assuming the Connector is [configured to perform this action](https://docs.microsoft.com/intune/windows-autopilot-hybrid#increase-the-computer-account-limit-in-the-organizational-unit) on the user's behalf. +**AAD device join**: The hybrid AAD join process uses the system context to perform device AAD join, therefore it is not affected by user based AAD join permission settings. In addition, all users are enabled to join devices to AAD by default. + ## Step by step instructions See [Deploy hybrid Azure AD joined devices using Intune and Windows Autopilot](https://docs.microsoft.com/intune/windows-autopilot-hybrid). diff --git a/windows/security/threat-protection/TOC.md b/windows/security/threat-protection/TOC.md index a328d38a24..ab27a7496a 100644 --- a/windows/security/threat-protection/TOC.md +++ b/windows/security/threat-protection/TOC.md @@ -23,6 +23,7 @@ ###### [Investigate incidents](windows-defender-atp/investigate-incidents-windows-defender-advanced-threat-protection.md) + ##### Alerts queue ###### [View and organize the Alerts queue](windows-defender-atp/alerts-queue-windows-defender-advanced-threat-protection.md) ###### [Manage alerts](windows-defender-atp/manage-alerts-windows-defender-advanced-threat-protection.md) @@ -80,77 +81,11 @@ ##### [Custom detections](windows-defender-atp/overview-custom-detections.md) ###### [Create custom detections rules](windows-defender-atp/custom-detection-rules.md) + #### [Management and APIs](windows-defender-atp/management-apis.md) ##### [Understand threat intelligence concepts](windows-defender-atp/threat-indicator-concepts-windows-defender-advanced-threat-protection.md) -##### [Supported Windows Defender ATP APIs](windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md) -######Actor -####### [Get actor information](windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md) -####### [Get actor related alerts](windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md) -######Alerts -####### [Get alerts](windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md) -####### [Get alert information by ID](windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md) -####### [Get alert related actor information](windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md) -####### [Get alert related domain information](windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md) -####### [Get alert related file information](windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md) -####### [Get alert related IP information](windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md) -####### [Get alert related machine information](windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md) -######Domain -####### [Get domain related alerts](windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md) -####### [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) -######Machines Security States -####### [Get MachineSecurityStates collection](windows-defender-atp/get-machinesecuritystates-collection-windows-defender-advanced-threat-protection.md) -######Machine Groups -####### [Get MachineGroups collection](windows-defender-atp/get-machinegroups-collection-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) - -######Windows updates (KB) info -####### [Get KbInfo collection](windows-defender-atp/get-kbinfo-collection-windows-defender-advanced-threat-protection.md) -######Common Vulnerabilities and Exposures (CVE) to KB map -####### [Get CVE-KB map](windows-defender-atp/get-cvekbmap-collection-windows-defender-advanced-threat-protection.md) - +##### [Windows Defender ATP APIs](windows-defender-atp/apis-intro.md) ##### [Managed security service provider support](windows-defender-atp/mssp-support-windows-defender-advanced-threat-protection.md) #### [Microsoft threat protection](windows-defender-atp/threat-protection-integration.md) @@ -290,6 +225,152 @@ ###### [Troubleshoot onboarding issues](windows-defender-atp/troubleshoot-onboarding-windows-defender-advanced-threat-protection.md) ####### [Troubleshoot subscription and portal access issues](windows-defender-atp/troubleshoot-onboarding-error-messages-windows-defender-advanced-threat-protection.md) +##### [Use the Windows Defender ATP exposed APIs](windows-defender-atp/use-apis.md) +###### Create your app +####### [Get access on behalf of a user](windows-defender-atp/exposed-apis-create-app-nativeapp.md) +####### [Get access without a user](windows-defender-atp/exposed-apis-create-app-webapp.md) +###### [Supported Windows Defender ATP APIs](windows-defender-atp/exposed-apis-list.md) +####### [Advanced Hunting](windows-defender-atp/run-advanced-query-api.md) + +####### [Alert](windows-defender-atp/alerts-windows-defender-advanced-threat-protection-new.md) +######## [List alerts](windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection-new.md) +######## [Create alert](windows-defender-atp/create-alert-by-reference-windows-defender-advanced-threat-protection-new.md) +######## [Update Alert](windows-defender-atp/update-alert-windows-defender-advanced-threat-protection-new.md) +######## [Get alert information by ID](windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) +######## [Get alert related domains information](windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md) +######## [Get alert related file information](windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md) +######## [Get alert related IPs information](windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md) +######## [Get alert related machine information](windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md) +######## [Get alert related user information](windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md) + +####### Domain +######## [Get domain related alerts](windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md) +######## [Get domain related machines](windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection-new.md) +######## [Get domain statistics](windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection-new.md) +######## [Is domain seen in organization](windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection-new.md) + +####### [File](windows-defender-atp/files-windows-defender-advanced-threat-protection-new.md) +######## [Get file information](windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection-new.md) +######## [Get file related alerts](windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection-new.md) +######## [Get file related machines](windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection-new.md) +######## [Get file statistics](windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection-new.md) + +####### IP +######## [Get IP related alerts](windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection-new.md) +######## [Get IP related machines](windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection-new.md) +######## [Get IP statistics](windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection-new.md) +######## [Is IP seen in organization](windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection-new.md) + +####### [Machine](windows-defender-atp/machine-windows-defender-advanced-threat-protection-new.md) +######## [Get machines](windows-defender-atp/get-machines-windows-defender-advanced-threat-protection-new.md) +######## [Get machine by ID](windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection-new.md) +######## [Get machine log on users](windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md) +######## [Get machine related alerts](windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md) +######## [Add or Remove machine tags](windows-defender-atp/add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md) +######## [Find machines by IP](windows-defender-atp/find-machines-by-ip-windows-defender-advanced-threat-protection-new.md) + + +####### [Machine Action](windows-defender-atp/machineaction-windows-defender-advanced-threat-protection-new.md) +######## [List MachineActions](windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md) +######## [Get MachineAction](windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection-new.md) +######## [Collect investigation package](windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection-new.md) +######## [Get investigation package SAS URI](windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection-new.md) +######## [Isolate machine](windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection-new.md) +######## [Release machine from isolation](windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection-new.md) +######## [Restrict app execution](windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection-new.md) +######## [Remove app restriction](windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md) +######## [Run antivirus scan](windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection-new.md) +######## [Offboard machine](windows-defender-atp/offboard-machine-api-windows-defender-advanced-threat-protection-new.md) + +####### [User](windows-defender-atp/user-windows-defender-advanced-threat-protection-new.md) +######## [Get user related alerts](windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md) +######## [Get user related machines](windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md) + + +###### How to use APIs - Samples +####### Advanced Hunting API +######## [Schedule advanced Hunting using Microsoft Flow](windows-defender-atp/run-advanced-query-sample-ms-flow.md) +######## [Advanced Hunting using PowerShell](windows-defender-atp/run-advanced-query-sample-powershell.md) +######## [Advanced Hunting using Python](windows-defender-atp/run-advanced-query-sample-python.md) +######## [Create custom Power BI reports](windows-defender-atp/run-advanced-query-sample-power-bi-app-token.md) +####### Multiple APIs +######## [PowerShell](windows-defender-atp/exposed-apis-full-sample-powershell.md) +####### [Using OData Queries](windows-defender-atp/exposed-apis-odata-samples.md) + +##### [Use the Windows Defender ATP exposed APIs (deprecated)](windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md) +###### [Supported Windows Defender ATP APIs (deprecated)](windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md) +#######Actor (deprecated) +######## [Get actor information (deprecated)](windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md) +######## [Get actor related alerts (deprecated)](windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md) +#######Alerts (deprecated) +######## [Get alerts (deprecated)](windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md) +######## [Get alert information by ID (deprecated)](windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md) +######## [Get alert related actor information (deprecated)](windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md) +######## [Get alert related domain information (deprecated)](windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md) +######## [Get alert related file information (deprecated)](windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md) +######## [Get alert related IP information (deprecated)](windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md) +######## [Get alert related machine information (deprecated)](windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md) +#######Domain (deprecated) +######## [Get domain related alerts (deprecated)](windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md) +######## [Get domain related machines (deprecated)](windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection.md) +######## [Get domain statistics (deprecated)](windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection.md) +######## [Is domain seen in organization (deprecated)](windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection.md) + +#######File(deprecated) +######## [Block file (deprecated)](windows-defender-atp/block-file-windows-defender-advanced-threat-protection.md) +######## [Get file information (deprecated)](windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection.md) +######## [Get file related alerts (deprecated)](windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection.md) +######## [Get file related machines (deprecated)](windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection.md) +######## [Get file statistics (deprecated)](windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection.md) +######## [Get FileActions collection (deprecated)](windows-defender-atp/get-fileactions-collection-windows-defender-advanced-threat-protection.md) +######## [Unblock file (deprecated)](windows-defender-atp/unblock-file-windows-defender-advanced-threat-protection.md) + +#######IP (deprecated) +######## [Get IP related alerts (deprecated)](windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection.md) +######## [Get IP related machines (deprecated)](windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md) +######## [Get IP statistics (deprecated)](windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection.md) +######## [Is IP seen in organization (deprecated)](windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection.md) +#######Machines (deprecated) +######## [Collect investigation package (deprecated)](windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection.md) +######## [Find machine information by IP (deprecated)](windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection.md) +######## [Get machines (deprecated)](windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md) +######## [Get FileMachineAction object (deprecated)](windows-defender-atp/get-filemachineaction-object-windows-defender-advanced-threat-protection.md) +######## [Get FileMachineActions collection (deprecated)](windows-defender-atp/get-filemachineactions-collection-windows-defender-advanced-threat-protection.md) +######## [Get machine by ID (deprecated)](windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection.md) +######## [Get machine log on users (deprecated)](windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection.md) +######## [Get machine related alerts (deprecated)](windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection.md) +######## [Get MachineAction object (deprecated)](windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection.md) +######## [Get MachineActions collection (deprecated)](windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection.md) +######## [Get machines (deprecated)](windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md) +######## [Get package SAS URI (deprecated)](windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection.md) +######## [Isolate machine (deprecated)](windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection.md) +######## [Release machine from isolation (deprecated)](windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection.md) +######## [Remove app restriction (deprecated)](windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection.md) +######## [Request sample (deprecated)](windows-defender-atp/request-sample-windows-defender-advanced-threat-protection.md) +######## [Restrict app execution (deprecated)](windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection.md) +######## [Run antivirus scan (deprecated)](windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection.md) +######## [Stop and quarantine file (deprecated)](windows-defender-atp/stop-quarantine-file-windows-defender-advanced-threat-protection.md) + +#######User (deprecated) +######## [Get alert related user information (deprecated)](windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection.md) +######## [Get user information (deprecated)](windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection.md) +######## [Get user related alerts (deprecated)](windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md) +######## [Get user related machines (deprecated)](windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection.md) + + +#####Windows updates (KB) info +###### [Get KbInfo collection](windows-defender-atp/get-kbinfo-collection-windows-defender-advanced-threat-protection.md) +#####Common Vulnerabilities and Exposures (CVE) to KB map +###### [Get CVE-KB map](windows-defender-atp/get-cvekbmap-collection-windows-defender-advanced-threat-protection.md) + + + + + + + + + ##### API for custom alerts ###### [Enable the custom threat intelligence application](windows-defender-atp/enable-custom-ti-windows-defender-advanced-threat-protection.md) ###### [Use the Windows Defender ATP exposed APIs](windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md) diff --git a/windows/security/threat-protection/windows-defender-atp/TOC.md b/windows/security/threat-protection/windows-defender-atp/TOC.md index f05f3f551f..efe244b001 100644 --- a/windows/security/threat-protection/windows-defender-atp/TOC.md +++ b/windows/security/threat-protection/windows-defender-atp/TOC.md @@ -16,7 +16,6 @@ #### [Security operations dashboard](security-operations-dashboard-windows-defender-advanced-threat-protection.md) - #### [Incidents queue](incidents-queue.md) ##### [View and organize the Incidents queue](view-incidents-queue.md) ##### [Manage incidents](manage-incidents-windows-defender-advanced-threat-protection.md) @@ -84,74 +83,7 @@ ### [Management and APIs](management-apis.md) #### [Understand threat intelligence concepts](threat-indicator-concepts-windows-defender-advanced-threat-protection.md) -#### [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection.md) -#####Actor -###### [Get actor information](get-actor-information-windows-defender-advanced-threat-protection.md) -###### [Get actor related alerts](get-actor-related-alerts-windows-defender-advanced-threat-protection.md) -#####Alerts -###### [Get alerts](get-alerts-windows-defender-advanced-threat-protection.md) -###### [Get alert information by ID](get-alert-info-by-id-windows-defender-advanced-threat-protection.md) -###### [Get alert related actor information](get-alert-related-actor-info-windows-defender-advanced-threat-protection.md) -###### [Get alert related domain information](get-alert-related-domain-info-windows-defender-advanced-threat-protection.md) -###### [Get alert related file information](get-alert-related-files-info-windows-defender-advanced-threat-protection.md) -###### [Get alert related IP information](get-alert-related-ip-info-windows-defender-advanced-threat-protection.md) -###### [Get alert related machine information](get-alert-related-machine-info-windows-defender-advanced-threat-protection.md) - -#####Domain -###### [Get domain related alerts](get-domain-related-alerts-windows-defender-advanced-threat-protection.md) -###### [Get domain related machines](get-domain-related-machines-windows-defender-advanced-threat-protection.md) -###### [Get domain statistics](get-domain-statistics-windows-defender-advanced-threat-protection.md) -###### [Is domain seen in organization](is-domain-seen-in-org-windows-defender-advanced-threat-protection.md) - -#####File -###### [Block file API](block-file-windows-defender-advanced-threat-protection.md) -###### [Get file information](get-file-information-windows-defender-advanced-threat-protection.md) -###### [Get file related alerts](get-file-related-alerts-windows-defender-advanced-threat-protection.md) -###### [Get file related machines](get-file-related-machines-windows-defender-advanced-threat-protection.md) -###### [Get file statistics](get-file-statistics-windows-defender-advanced-threat-protection.md) -###### [Get FileActions collection API](get-fileactions-collection-windows-defender-advanced-threat-protection.md) -###### [Unblock file API](unblock-file-windows-defender-advanced-threat-protection.md) - -#####IP -###### [Get IP related alerts](get-ip-related-alerts-windows-defender-advanced-threat-protection.md) -###### [Get IP related machines](get-ip-related-machines-windows-defender-advanced-threat-protection.md) -###### [Get IP statistics](get-ip-statistics-windows-defender-advanced-threat-protection.md) -###### [Is IP seen in organization](is-ip-seen-org-windows-defender-advanced-threat-protection.md) -#####Machines -###### [Collect investigation package API](collect-investigation-package-windows-defender-advanced-threat-protection.md) -###### [Find machine information by IP](find-machine-info-by-ip-windows-defender-advanced-threat-protection.md) -###### [Get machines](get-machines-windows-defender-advanced-threat-protection.md) -###### [Get FileMachineAction object API](get-filemachineaction-object-windows-defender-advanced-threat-protection.md) -###### [Get FileMachineActions collection API](get-filemachineactions-collection-windows-defender-advanced-threat-protection.md) -###### [Get machine by ID](get-machine-by-id-windows-defender-advanced-threat-protection.md) -###### [Get machine log on users](get-machine-log-on-users-windows-defender-advanced-threat-protection.md) -###### [Get machine related alerts](get-machine-related-alerts-windows-defender-advanced-threat-protection.md) -###### [Get MachineAction object API](get-machineaction-object-windows-defender-advanced-threat-protection.md) -###### [Get MachineActions collection API](get-machineactions-collection-windows-defender-advanced-threat-protection.md) -###### [Get machines](get-machines-windows-defender-advanced-threat-protection.md) -###### [Get package SAS URI API](get-package-sas-uri-windows-defender-advanced-threat-protection.md) -###### [Isolate machine API](isolate-machine-windows-defender-advanced-threat-protection.md) -###### [Release machine from isolation API](unisolate-machine-windows-defender-advanced-threat-protection.md) -###### [Remove app restriction API](unrestrict-code-execution-windows-defender-advanced-threat-protection.md) -###### [Request sample API](request-sample-windows-defender-advanced-threat-protection.md) -###### [Restrict app execution API](restrict-code-execution-windows-defender-advanced-threat-protection.md) -###### [Run antivirus scan API](run-av-scan-windows-defender-advanced-threat-protection.md) -###### [Stop and quarantine file API](stop-quarantine-file-windows-defender-advanced-threat-protection.md) -#####Machines Security States -###### [Get MachineSecurityStates collection](get-machinesecuritystates-collection-windows-defender-advanced-threat-protection.md) -#####Machine Groups -###### [Get MachineGroups collection](get-machinegroups-collection-windows-defender-advanced-threat-protection.md) -#####User -###### [Get alert related user information](get-alert-related-user-info-windows-defender-advanced-threat-protection.md) -###### [Get user information](get-user-information-windows-defender-advanced-threat-protection.md) -###### [Get user related alerts](get-user-related-alerts-windows-defender-advanced-threat-protection.md) -###### [Get user related machines](get-user-related-machines-windows-defender-advanced-threat-protection.md) -#####Windows updates (KB) info -###### [Get KbInfo collection](get-kbinfo-collection-windows-defender-advanced-threat-protection.md) -#####Common Vulnerabilities and Exposures (CVE) to KB map -###### [Get CVE-KB map](get-cvekbmap-collection-windows-defender-advanced-threat-protection.md) - - +#### [Windows Defender ATP APIs](apis-intro.md) #### [Managed security service provider support](mssp-support-windows-defender-advanced-threat-protection.md) @@ -289,6 +221,160 @@ ##### [Troubleshoot onboarding issues](troubleshoot-onboarding-windows-defender-advanced-threat-protection.md) ###### [Troubleshoot subscription and portal access issues](troubleshoot-onboarding-error-messages-windows-defender-advanced-threat-protection.md) + +#### [Use the Windows Defender ATP exposed APIs](use-apis.md) +##### Create your app +###### [Get access on behalf of a user](exposed-apis-create-app-nativeapp.md) +###### [Get access without a user](exposed-apis-create-app-webapp.md) +##### [Supported Windows Defender ATP APIs](exposed-apis-list.md) +###### [Advanced Hunting](run-advanced-query-api.md) + +###### [Alert](alerts-windows-defender-advanced-threat-protection-new.md) +####### [List alerts](get-alerts-windows-defender-advanced-threat-protection-new.md) +####### [Create alert](create-alert-by-reference-windows-defender-advanced-threat-protection-new.md) +####### [Update Alert](update-alert-windows-defender-advanced-threat-protection-new.md) +####### [Get alert information by ID](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) +####### [Get alert related domains information](get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md) +####### [Get alert related file information](get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md) +####### [Get alert related IPs information](get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md) +####### [Get alert related machine information](get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md) +####### [Get alert related user information](get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md) + +###### Domain +####### [Get domain related alerts](get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md) +####### [Get domain related machines](get-domain-related-machines-windows-defender-advanced-threat-protection-new.md) +####### [Get domain statistics](get-domain-statistics-windows-defender-advanced-threat-protection-new.md) +####### [Is domain seen in organization](is-domain-seen-in-org-windows-defender-advanced-threat-protection-new.md) + +###### [File](files-windows-defender-advanced-threat-protection-new.md) +####### [Get file information](get-file-information-windows-defender-advanced-threat-protection-new.md) +####### [Get file related alerts](get-file-related-alerts-windows-defender-advanced-threat-protection-new.md) +####### [Get file related machines](get-file-related-machines-windows-defender-advanced-threat-protection-new.md) +####### [Get file statistics](get-file-statistics-windows-defender-advanced-threat-protection-new.md) + +###### IP +####### [Get IP related alerts](get-ip-related-alerts-windows-defender-advanced-threat-protection-new.md) +####### [Get IP related machines](get-ip-related-machines-windows-defender-advanced-threat-protection-new.md) +####### [Get IP statistics](get-ip-statistics-windows-defender-advanced-threat-protection-new.md) +####### [Is IP seen in organization](is-ip-seen-org-windows-defender-advanced-threat-protection-new.md) + +###### [Machine](machine-windows-defender-advanced-threat-protection-new.md) +####### [Get machines](get-machines-windows-defender-advanced-threat-protection-new.md) +####### [Get machine by ID](get-machine-by-id-windows-defender-advanced-threat-protection-new.md) +####### [Get machine log on users](get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md) +####### [Get machine related alerts](get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md) +####### [Add or Remove machine tags](add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md) +####### [Find machines by IP](find-machines-by-ip-windows-defender-advanced-threat-protection-new.md) + +###### [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) +####### [List MachineActions](get-machineactions-collection-windows-defender-advanced-threat-protection-new.md) +####### [Get MachineAction](get-machineaction-object-windows-defender-advanced-threat-protection-new.md) +####### [Collect investigation package](collect-investigation-package-windows-defender-advanced-threat-protection-new.md) +####### [Get investigation package SAS URI](get-package-sas-uri-windows-defender-advanced-threat-protection-new.md) +####### [Isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md) +####### [Release machine from isolation](unisolate-machine-windows-defender-advanced-threat-protection-new.md) +####### [Restrict app execution](restrict-code-execution-windows-defender-advanced-threat-protection-new.md) +####### [Remove app restriction](unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md) +####### [Run antivirus scan](run-av-scan-windows-defender-advanced-threat-protection-new.md) +####### [Offboard machine](offboard-machine-api-windows-defender-advanced-threat-protection-new.md) + + +###### [User](user-windows-defender-advanced-threat-protection-new.md) +####### [Get user related alerts](get-user-related-alerts-windows-defender-advanced-threat-protection-new.md) +####### [Get user related machines](get-user-related-machines-windows-defender-advanced-threat-protection-new.md) + +##### How to use APIs - Samples +###### Advanced Hunting API +####### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md) +####### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) +####### [Advanced Hunting using Python](run-advanced-query-sample-python.md) +####### [Create custom Power BI reports](run-advanced-query-sample-power-bi-app-token.md) +###### Multiple APIs +####### [PowerShell](exposed-apis-full-sample-powershell.md) +###### [Using OData Queries](exposed-apis-odata-samples.md) + +#### [Use the Windows Defender ATP exposed APIs (deprecated)](exposed-apis-windows-defender-advanced-threat-protection.md) +##### [Supported Windows Defender ATP APIs (deprecated)](supported-apis-windows-defender-advanced-threat-protection.md) +######Actor (deprecated) +####### [Get actor information (deprecated)](get-actor-information-windows-defender-advanced-threat-protection.md) +####### [Get actor related alerts (deprecated)](get-actor-related-alerts-windows-defender-advanced-threat-protection.md) +######Alerts (deprecated) +####### [Get alerts (deprecated)](get-alerts-windows-defender-advanced-threat-protection.md) +####### [Get alert information by ID (deprecated)](get-alert-info-by-id-windows-defender-advanced-threat-protection.md) +####### [Get alert related actor information (deprecated)](get-alert-related-actor-info-windows-defender-advanced-threat-protection.md) +####### [Get alert related domain information (deprecated)](get-alert-related-domain-info-windows-defender-advanced-threat-protection.md) +####### [Get alert related file information (deprecated)](get-alert-related-files-info-windows-defender-advanced-threat-protection.md) +####### [Get alert related IP information (deprecated)](get-alert-related-ip-info-windows-defender-advanced-threat-protection.md) +####### [Get alert related machine information (deprecated)](get-alert-related-machine-info-windows-defender-advanced-threat-protection.md) +######Domain (deprecated) +####### [Get domain related alerts (deprecated)](get-domain-related-alerts-windows-defender-advanced-threat-protection.md) +####### [Get domain related machines (deprecated)](get-domain-related-machines-windows-defender-advanced-threat-protection.md) +####### [Get domain statistics (deprecated)](get-domain-statistics-windows-defender-advanced-threat-protection.md) +####### [Is domain seen in organization (deprecated)](is-domain-seen-in-org-windows-defender-advanced-threat-protection.md) + +######File(deprecated) +####### [Block file (deprecated)](block-file-windows-defender-advanced-threat-protection.md) +####### [Get file information (deprecated)](get-file-information-windows-defender-advanced-threat-protection.md) +####### [Get file related alerts (deprecated)](get-file-related-alerts-windows-defender-advanced-threat-protection.md) +####### [Get file related machines (deprecated)](get-file-related-machines-windows-defender-advanced-threat-protection.md) +####### [Get file statistics (deprecated)](get-file-statistics-windows-defender-advanced-threat-protection.md) +####### [Get FileActions collection (deprecated)](get-fileactions-collection-windows-defender-advanced-threat-protection.md) +####### [Unblock file (deprecated)](unblock-file-windows-defender-advanced-threat-protection.md) + +######IP (deprecated) +####### [Get IP related alerts (deprecated)](get-ip-related-alerts-windows-defender-advanced-threat-protection.md) +####### [Get IP related machines (deprecated)](get-ip-related-machines-windows-defender-advanced-threat-protection.md) +####### [Get IP statistics (deprecated)](get-ip-statistics-windows-defender-advanced-threat-protection.md) +####### [Is IP seen in organization (deprecated)](is-ip-seen-org-windows-defender-advanced-threat-protection.md) +######Machines (deprecated) +####### [Collect investigation package (deprecated)](collect-investigation-package-windows-defender-advanced-threat-protection.md) +####### [Find machine information by IP (deprecated)](find-machine-info-by-ip-windows-defender-advanced-threat-protection.md) +####### [Get machines (deprecated)](get-machines-windows-defender-advanced-threat-protection.md) +####### [Get FileMachineAction object (deprecated)](get-filemachineaction-object-windows-defender-advanced-threat-protection.md) +####### [Get FileMachineActions collection (deprecated)](get-filemachineactions-collection-windows-defender-advanced-threat-protection.md) +####### [Get machine by ID (deprecated)](get-machine-by-id-windows-defender-advanced-threat-protection.md) +####### [Get machine log on users (deprecated)](get-machine-log-on-users-windows-defender-advanced-threat-protection.md) +####### [Get machine related alerts (deprecated)](get-machine-related-alerts-windows-defender-advanced-threat-protection.md) +####### [Get MachineAction object (deprecated)](get-machineaction-object-windows-defender-advanced-threat-protection.md) +####### [Get MachineActions collection (deprecated)](get-machineactions-collection-windows-defender-advanced-threat-protection.md) +####### [Get machines (deprecated)](get-machines-windows-defender-advanced-threat-protection.md) +####### [Get package SAS URI (deprecated)](get-package-sas-uri-windows-defender-advanced-threat-protection.md) +####### [Isolate machine (deprecated)](isolate-machine-windows-defender-advanced-threat-protection.md) +####### [Release machine from isolation (deprecated)](unisolate-machine-windows-defender-advanced-threat-protection.md) +####### [Remove app restriction (deprecated)](unrestrict-code-execution-windows-defender-advanced-threat-protection.md) +####### [Request sample (deprecated)](request-sample-windows-defender-advanced-threat-protection.md) +####### [Restrict app execution (deprecated)](restrict-code-execution-windows-defender-advanced-threat-protection.md) +####### [Run antivirus scan (deprecated)](run-av-scan-windows-defender-advanced-threat-protection.md) +####### [Stop and quarantine file (deprecated)](stop-quarantine-file-windows-defender-advanced-threat-protection.md) + +######User (deprecated) +####### [Get alert related user information (deprecated)](get-alert-related-user-info-windows-defender-advanced-threat-protection.md) +####### [Get user information (deprecated)](get-user-information-windows-defender-advanced-threat-protection.md) +####### [Get user related alerts (deprecated)](get-user-related-alerts-windows-defender-advanced-threat-protection.md) +####### [Get user related machines (deprecated)](get-user-related-machines-windows-defender-advanced-threat-protection.md) + + + + + + + + + + + + + + + + + + + + + + + #### API for custom alerts ##### [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md) ##### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md) diff --git a/windows/security/threat-protection/windows-defender-atp/add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..e28bac587b --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,110 @@ +--- +title: Add or Remove Machine Tags API +description: Use this API to Add or Remove machine tags. +keywords: apis, graph api, supported apis, tags, machine tags +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Add or Remove Machine Tags API + +[!include[Prerelease information](prerelease.md)] + +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) +- Adds or remove tag to a specific machine. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'Manage security setting' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- User needs to have access to the machine, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/machines/{id}/tags +``` + +## 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 +:---|:---|:--- +Value | String | The tag name. **Required**. +Action | Enum | Add or Remove. Allowed values are: 'Add' or 'Remove'. **Required**. + + +## Response +If successful, this method returns 200 - Ok response code and the updated Machine in the response body. + + +## Example + +**Request** + +Here is an example of a request that adds machine tag. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +POST https://api.securitycenter.windows.com/api/machines/863fed4b174465c703c6e412965a31b5e1884cc4/tags +Content-type: application/json +{ + "Value" : "Test Tag", + "Action": "Add" +} + +``` +**Response** + +Here is an example of the response. + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machine/$entity", + "id": "863fed4b174465c703c6e412965a31b5e1884cc4", + "computerDnsName": "mymachine55.contoso.com", + "firstSeen": "2018-07-31T14:20:55.8223496Z", + "lastSeen": "2018-09-27T08:44:05.6228836Z", + "osPlatform": "Windows10", + "osVersion": null, + "lastIpAddress": "10.248.240.38", + "lastExternalIpAddress": "167.220.2.166", + "agentVersion": "10.3720.16299.98", + "osBuild": 16299, + "healthStatus": "Active", + "isAadJoined": true, + "machineTags": [ + "Test Tag" + ], + "rbacGroupId": 75, + "riskScore": "Medium", + "aadDeviceId": null +} + +``` + +To remove machine tag, set the Action to 'Remove' instead of 'Add' in the request body. \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/alerts-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/alerts-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..b1cde1afaf --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/alerts-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,81 @@ +--- +title: Get alerts API +description: Retrieves top recent alerts. +keywords: apis, graph api, supported apis, get, alerts, recent +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Alert resource type +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Represents an alert entity in WDATP. + +# Methods +Method|Return Type |Description +:---|:---|:--- +[Get alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) | [Alert](alerts-windows-defender-advanced-threat-protection-new.md) | Get a single [alert](alerts-windows-defender-advanced-threat-protection-new.md) object. +[List alerts](get-alerts-windows-defender-advanced-threat-protection-new.md) | [Alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | List [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection. +[Create alert](create-alert-by-reference-windows-defender-advanced-threat-protection-new.md)|[Alert](alerts-windows-defender-advanced-threat-protection-new.md)|Create an alert based on event data obtained from [Advanced Hunting](run-advanced-query-api.md). +[List related domains](get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md)|Domain collection| List URLs associated with the alert. +[List related files](get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md) | [File](files-windows-defender-advanced-threat-protection-new.md) collection | List the [file](files-windows-defender-advanced-threat-protection-new.md) entities that are associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md). +[List related IPs](get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md) | IP collection | List IPs that are associated with the alert. +[Get related machines](get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md) | [Machine](machine-windows-defender-advanced-threat-protection-new.md) | The [machine](machine-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md). +[Get related users](get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md) | [User](user-windows-defender-advanced-threat-protection-new.md) | The [user](user-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md). + + +# Properties +Property | Type | Description +:---|:---|:--- +id | String | Alert ID +severity | String | Severity of the alert. Allowed values are: 'Low', 'Medium' and 'High'. +status | String | Specifies the current status of the alert. The property values are: 'New', 'InProgress' and 'Resolved'. +description | String | Description of the threat, identified by the alert. +recommendedAction | String | Action recommended for handling the suspected threat. +alertCreationTime | DateTimeOffset | The date and time (in UTC) the alert was created. +category| String | Category of the alert. The property values are: 'None', 'SuspiciousActivity', 'Malware', 'CredentialTheft', 'Exploit', 'WebExploit', 'DocumentExploit', 'PrivilegeEscalation', 'Persistence', 'RemoteAccessTool', 'CommandAndControl', 'SuspiciousNetworkTraffic', 'Ransomware', 'MalwareDownload', 'Reconnaissance', 'WebFingerprinting', 'Weaponization', 'Delivery', 'SocialEngineering', 'CredentialStealing', 'Installation', 'Backdoor', 'Trojan', 'TrojanDownloader', 'LateralMovement', 'ExplorationEnumeration', 'NetworkPropagation', 'Exfiltration', 'NotApplicable', 'EnterprisePolicy' and 'General'. +title | string | Alert title +threatFamilyName | string | Threat family +detectionSource | string | Detection source +assignedTo | String | Owner of the alert +classification | String | Specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'. +determination | String | Specifies the determination of the alert. The property values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other' +resolvedTime | DateTimeOffset | The date and time in which the status of the alert was changed to 'Resolved'. +lastEventTime | DateTimeOffset | The last occurance of the event that triggered the alert on the same machine. +firstEventTime | DateTimeOffset | The first occurance of the event that triggered the alert on that machine. +machineId | String | ID of a [machine](machine-windows-defender-advanced-threat-protection-new.md) entity that is associated with the alert. + +# JSON representation +``` +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts", + "id": "636688558380765161_2136280442", + "severity": "Informational", + "status": "InProgress", + "description": "Some alert description 1", + "recommendedAction": "Some recommended action 1", + "alertCreationTime": "2018-08-03T01:17:17.9516179Z", + "category": "General", + "title": "Some alert title 1", + "threatFamilyName": null, + "detectionSource": "WindowsDefenderAtp", + "classification": "TruePositive", + "determination": null, + "assignedTo": "best secop ever", + "resolvedTime": null, + "lastEventTime": "2018-08-02T07:02:52.0894451Z", + "firstEventTime": "2018-08-02T07:02:52.0894451Z", + "actorName": null, + "machineId": "ff0c3800ed8d66738a514971cd6867166809369f" +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/apis-intro.md b/windows/security/threat-protection/windows-defender-atp/apis-intro.md new file mode 100644 index 0000000000..304eed3564 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/apis-intro.md @@ -0,0 +1,57 @@ +--- +title: Windows Defender Advanced Threat Protection API overview +description: Learn how you can use APIs to automate workflows and innovate based on Windows Defender ATP capabilities +keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 09/03/2018 +--- + +# Windows Defender ATP API overview + +**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-exposedapis-abovefoldlink) + +[!include[Prerelease information](prerelease.md)] + +Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code). + +In general, you’ll need to take the following steps to use the APIs: +- Create an app +- Get an access token +- Use the token to access Windows Defender ATP API + + +As a developer, you decide which permissions for Windows Defender ATP your app requests. When a user signs in to your app they (or, in some cases, an administrator) are given a chance to give consent to these permissions. If the user provides consent, your app is given access to the resources and APIs that it has requested. For apps that don't take a signed-in user, permissions can be pre-approved to by an administrator when the app is installed or during sign-up. + +## Delegated permissions, application permissions, and effective permissions + +Windows Defender ATP has two types of permissions: delegated permissions and application permissions. + +- **Delegated permissions**
+ Used by apps that have a signed-in user present. For these apps either the user or an administrator provides consent to the permissions that the app requests and the app is delegated permission to act as the signed-in user when making calls to Windows Defender ATP. Some delegated permissions can be consented to by non-administrative users, but some higher-privileged permissions require administrator consent. +- **Application permissions**
+ Used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. Application permissions can only be consented by an administrator. + +Effective permissions are permissions that your app will have when making requests to Windows Defender ATP. It is important to understand the difference between the delegated and application permissions that your app is granted and its effective permissions when making calls to Windows Defender ATP. + +- For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (via consent) and the privileges of the currently signed-in user. Your app can never have more privileges than the signed-in user. Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. For more information about administrator roles, see [Assigning administrator roles in Azure Active Directory](https://docs.microsoft.com/azure/active-directory/active-directory-assign-admin-roles). + + For example, assume your app has been granted the `Machine.CollectForensics` delegated permission. This permission nominally grants your app permission to collect investigation package from a machine. If the signed-in user has 'Alerts Investigation' permission, your app will be able to collect investigation package from a machine, if the machine belongs to a group the user is exposed to. However, if the signed-in user doesn't have 'Alerts Investigation' permission, your app won't be able to collect investigation package from any machine. + +- For application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. For example, an app that has the `Machine.CollectForensics` application permission can collect investigation package from any machine in the organization. + + +## Related topics +- [Supported Windows Defender ATP APIs](exposed-apis-list.md) +- [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md) +- [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md) \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/block-file-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/block-file-windows-defender-advanced-threat-protection.md index 16ae492cd3..64f4c8d321 100644 --- a/windows/security/threat-protection/windows-defender-atp/block-file-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/block-file-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Block file API +# Block file API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Prevent a file from being executed in the organization using Windows Defender Antivirus. diff --git a/windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..bcd6861b37 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,98 @@ +--- +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: medium +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. + +[!include[Machine actions note](machineactionsnote.md)] + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.CollectForensics | 'Collect forensics' +Delegated (work or school account) | Machine.CollectForensics | 'Collect forensics' + +>[!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-windows-defender-advanced-threat-protection.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-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/machines/{id}/collectInvestigationPackage +``` + +## 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 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/collectInvestigationPackage +Content-type: application/json +{ + "Comment": "Collect forensics due to alert 1234" +} +``` + +**Response** + +Here is an example of the response. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity", + "id": "c9042f9b-8483-4526-87b5-35e4c2532223", + "type": "CollectInvestigationPackage", + "requestor": "Analyst@contoso.com", + "requestorComment": " Collect forensics due to alert 1234", + "status": "InProgress", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2018-12-04T12:09:24.1785079Z", + "lastUpdateTimeUtc": "2018-12-04T12:09:24.1785079Z", + "relatedFileInfo": null +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection.md index f6394dc5a6..74df3d6aa3 100644 --- a/windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Collect investigation package API +# Collect investigation package API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Collect investigation package from a machine. diff --git a/windows/security/threat-protection/windows-defender-atp/create-alert-by-reference-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/create-alert-by-reference-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..53054cc36b --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/create-alert-by-reference-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,93 @@ +--- +title: Create alert from event API +description: Creates an alert using event details +keywords: apis, graph api, supported apis, get, alert, information, id +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Create alert from event API +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + +[!include[Prerelease information](prerelease.md)] + + +Enables using event data, as obtained from the [Advanced Hunting](run-advanced-query-api.md) for creating a new alert entity. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alerts.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-windows-defender-advanced-threat-protection.md) for more information) +>- The user needs to have access to the machine associated with the alert, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/CreateAlertByReference +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. +Content-Type | String | application/json. **Required**. + +## Request body +In the request body, supply the following values (all are required): + +Property | Type | Description +:---|:---|:--- +machineId | String | Id of the machine on which the event was identified. **Required**. +severity | String | Severity of the alert. The property values are: 'Low', 'Medium' and 'High'. **Required**. +title | String | Title for the alert. **Required**. +description | String | Description of the alert. **Required**. +recommendedAction| String | Action that is recommended to be taken by security officer when analyzing the alert. +eventTime | DateTime(UTC) | The time of the event, as obtained from the advanced query. **Required**. +reportId | String | The reportId, as obtained from the advanced query. **Required**. +category| String | Category of the alert. The property values are: 'None', 'SuspiciousActivity', 'Malware', 'CredentialTheft', 'Exploit', 'WebExploit', 'DocumentExploit', 'PrivilegeEscalation', 'Persistence', 'RemoteAccessTool', 'CommandAndControl', 'SuspiciousNetworkTraffic', 'Ransomware', 'MalwareDownload', 'Reconnaissance', 'WebFingerprinting', 'Weaponization', 'Delivery', 'SocialEngineering', 'CredentialStealing', 'Installation', 'Backdoor', 'Trojan', 'TrojanDownloader', 'LateralMovement', 'ExplorationEnumeration', 'NetworkPropagation', 'Exfiltration', 'NotApplicable', 'EnterprisePolicy' and 'General'. + + +## Response +If successful, this method returns 200 OK, and a new [alert](alerts-windows-defender-advanced-threat-protection-new.md) object in the response body. If event with the specified properties (_reportId_, _eventTime_ and _machineId_) was not found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +POST https://api.securitycenter.windows.com/api/CreateAlertByReference +Content-Length: application/json + +{ + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "severity": "Low", + "title": "test alert", + "description": "redalert", + "recommendedAction": "white alert", + "eventTime": "2018-08-03T16:45:21.7115183Z", + "reportId": "20776", + "category": "None" +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/custom-ti-api-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/custom-ti-api-windows-defender-advanced-threat-protection.md index 8bc7172555..67591e6f98 100644 --- a/windows/security/threat-protection/windows-defender-atp/custom-ti-api-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/custom-ti-api-windows-defender-advanced-threat-protection.md @@ -187,7 +187,6 @@ The API currently supports the following IOC types: - Sha1 - Sha256 - Md5 -- FileName - IpAddress - DomainName diff --git a/windows/security/threat-protection/windows-defender-atp/delete-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/delete-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..b0d3efb765 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/delete-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,77 @@ +--- +title: Delete Ti Indicator. +description: Deletes Ti Indicator entity by ID. +keywords: apis, public api, supported apis, delete, ti indicator, entity, id +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Delete TI Indicator API + +[!include[Prerelease information](prerelease.md)] + +>[!Note] +> Currently this API is supported only for AppOnly context requests. (See [Get access without a user](exposed-apis-create-app-webapp.md) for more information) + + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) +Retrieves a TI Indicator entity by ID. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Ti.ReadWrite | 'Read and write TI Indicators' + + +## HTTP request +``` +Delete https://api.securitycenter.windows.com/api/tiindicators/{id} +``` + +[!include[Improve request performance](improverequestperformance-new.md)] + + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If TI Indicator exist and deleted successfully - 204 OK without content. +If TI Indicator with the specified id was not found - 404 Not Found. + +## Example + +**Request** + +Here is an example of the request. + +``` +DELETE https://api.securitycenter.windows.com/api/tiindicators/220e7d15b0b3d7fac48f2bd61114db1022197f7f +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 204 NO CONTENT + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/deprecate.md b/windows/security/threat-protection/windows-defender-atp/deprecate.md new file mode 100644 index 0000000000..fe73a4d416 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/deprecate.md @@ -0,0 +1,7 @@ +--- +ms.date: 10/17/2018 +--- +>[!WARNING] + + +> This page documents a feature that will soon be deprecated. For the updated and supported version, see [Use the Windows Defender ATP APIs](use-apis.md). \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-nativeapp.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-nativeapp.md new file mode 100644 index 0000000000..679dc47866 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-nativeapp.md @@ -0,0 +1,175 @@ +--- +title: Use Windows Defender Advanced Threat Protection APIs +description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph. +keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 09/03/2018 +--- + +# Use Windows Defender ATP 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-exposedapis-abovefoldlink) + + +[!include[Prerelease information](prerelease.md)] + + +This page describe how to create an application to get programmatical access to Windows Defender ATP on behalf of a user. + +If you need programmatical access Windows Defender ATP without a user, refer to [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md). + +If you are not sure which access you need, read the [Introduction page](apis-intro.md). + +Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code). + +In general, you’ll need to take the following steps to use the APIs: +- Create an app +- Get an access token +- Use the token to access Windows Defender ATP API + +This page explains how to create an app, get an access token to Windows Defender ATP and validate the token includes the required permission. + +>[!NOTE] +> When accessing Windows Defender ATP API on behalf of a user, you will need the correct app permission and user permission. +> If you are not familiar with user permissions on Windows Defender ATP, see [Manage portal access using role-based access control](rbac-windows-defender-advanced-threat-protection.md). + +>[!TIP] +> If you have the permission to perform an action in the portal, you have the permission to perform the action in the API. + +## Create an app + +1. Log on to [Azure](https://portal.azure.com). + +2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**. + + ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app.png) + +3. In the Create window, enter the following information then click **Create**. + + ![Image of Create application window](images/nativeapp-create.png) + + - **Name:** -Your app name- + - **Application type:** Native + - **Redirect URI:** `https://127.0.0.1` + + +4. Click **Settings** > **Required permissions** > **Add**. + + ![Image of new app in Azure](images/nativeapp-add-permission.png) + +5. Click **Select an API** > **WindowsDefenderATP**, then click **Select**. + + **Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear. + + ![Image of API access and API selection](images/webapp-add-permission-2.png) + +6. Click **Select permissions** > check **Read alerts** and **Collect forensics** > **Select**. + + >[!IMPORTANT] + >You need to select the relevant permissions. 'Read alerts' and 'Collect forensics' are only an example. + + ![Image of select permissions](images/nativeapp-select-permissions.png) + + For instance, + + - To [run advanced queries](run-advanced-query-api.md), select 'Run advanced queries' permission + - To [isolate a machine](isolate-machine-windows-defender-advanced-threat-protection-new.md), select 'Isolate machine' permission + + To determine which permission you need, look at the **Permissions** section in the API you are interested to call. + + +7. Click **Done** + + ![Image of add permissions completion](images/nativeapp-add-permissions-end.png) + +8. Click **Grant permissions** + + In order to add the new selected permissions to the app, the Admin's tenant must press on the **Grant permissions** button. + + If in the future you will want to add more permission to the app, you will need to press on the **Grant permissions** button again so the changes will take effect. + + ![Image of Grant permissions](images/webapp-grant-permissions.png) + +9. Write down your application ID. + + ![Image of app ID](images/nativeapp-get-appid.png) + + +## Get an access token + +For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds) + +### Using C# + +The code was below tested with nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8 + +- Create a new Console Application +- Install Nuget [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/) +- Add the below using + + ``` + using Microsoft.IdentityModel.Clients.ActiveDirectory; + ``` + +- Copy/Paste the below code in your application (pay attention to the comments in the code) + + ``` + const string authority = "https://login.windows.net"; + const string wdatpResourceId = "https://api.securitycenter.windows.com"; + + string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here + string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here + + string username = "SecurityAdmin123@microsoft.com"; // Paste your username here + string password = GetPasswordFromSafePlace(); // Paste your own password here for a test, and then store it in a safe place! + + UserPasswordCredential userCreds = new UserPasswordCredential(username, password); + + AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}"); + AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, appId, userCreds).GetAwaiter().GetResult(); + string token = authenticationResult.AccessToken; + ``` + +## Validate the token + +Sanity check to make sure you got a correct token: +- Copy/paste into [JWT](https://jwt.ms) the token you get in the previous step in order to decode it +- Validate you get a 'scp' claim with the desired app permissions +- In the screenshot below you can see a decoded token acquired from the app in the tutorial: + +![Image of token validation](images/nativeapp-decoded-token.png) + +## Use the token to access Windows Defender ATP API + +- Choose the API you want to use - [Supported Windows Defender ATP APIs](exposed-apis-list.md) +- Set the Authorization header in the HTTP request you send to "Bearer {token}" (Bearer is the Authorization scheme) +- The Expiration time of the token is 1 hour (you can send more then one request with the same token) + +- Example of sending a request to get a list of alerts **using C#** + ``` + var httpClient = new HttpClient(); + + var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.windows.com/api/alerts"); + + request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token); + + var response = await httpClient.SendAsync(request).ConfigureAwait(false); + + // Do something useful with the response + ``` + +## Related topics +- [Windows Defender ATP APIs](apis-intro.md) +- [Supported Windows Defender ATP APIs](exposed-apis-list.md) +- [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md) \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-webapp.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-webapp.md new file mode 100644 index 0000000000..ca0153916b --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-webapp.md @@ -0,0 +1,220 @@ +--- +title: Create an app to access Windows Defender ATP without a user +description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph. +keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 09/03/2018 +--- + +# Create an app to access Windows Defender ATP without a user + +**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-exposedapis-abovefoldlink) + +[!include[Prerelease information](prerelease.md)] + +This page describes how to create an application to get programmatical access to Windows Defender ATP without a user. + +If you need programmatical access Windows Defender ATP on behalf of a user, see [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md) + +If you are not sure which access you need, see [Use Windows Defender ATP APIs](apis-intro.md). + +Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will help you automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code). + +In general, you’ll need to take the following steps to use the APIs: +- Create an app +- Get an access token +- Use the token to access Windows Defender ATP API + +This page explains how to create an app, get an access token to Windows Defender ATP and validate the token includes the required permission. + +## Create an app + +1. Log on to [Azure](https://portal.azure.com). + +2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**. + + ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app.png) + +3. In the Create window, enter the following information then click **Create**. + + ![Image of Create application window](images/webapp-create.png) + + - **Name:** WdatpEcosystemPartner + - **Application type:** Web app / API + - **Redirect URI:** `https://WdatpEcosystemPartner.com` (The URL where user can sign in and use your app. You can change this URL later.) + + +4. Click **Settings** > **Required permissions** > **Add**. + + ![Image of new app in Azure](images/webapp-add-permission.png) + +5. Click **Select an API** > **WindowsDefenderATP**, then click **Select**. + + **Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear. + + ![Image of API access and API selection](images/webapp-add-permission-2.png) + +6. Click **Select permissions** > **Run advanced queries** > **Select**. + + **Important note**: You need to select the relevant permission. 'Run advanced queries' is only an example! + + ![Image of select permissions](images/webapp-select-permission.png) + + For instance, + + - To [run advanced queries](run-advanced-query-api.md), select 'Run advanced queries' permission + - To [isolate a machine](isolate-machine-windows-defender-advanced-threat-protection-new.md), select 'Isolate machine' permission + + To determine which permission you need, please look at the **Permissions** section in the API you are interested to call. + +7. Click **Done** + + ![Image of add permissions completion](images/webapp-add-permission-end.png) + +8. Click **Grant permissions** + + In order to add the new selected permissions to the app, the Admin's tenant must press on the **Grant permissions** button. + + If in the future you will want to add more permission to the app, you will need to press on the **Grant permissions** button again so the changes will take effect. + + ![Image of Grant permissions](images/webapp-grant-permissions.png) + +9. Click **Keys** and type a key name and click **Save**. + + **Important**: After you save, **copy the key value**. You won't be able to retrieve after you leave! + + ![Image of create app key](images/webapp-create-key.png) + +10. Write down your application ID. + + ![Image of app ID](images/webapp-get-appid.png) + +11. Set your application to be multi-tenanted + + This is **required** for 3rd party apps (for example, if you create an application that is intended to run in multiple customers tenant). + + This is **not required** if you create a service that you want to run in your tenant only (for example, if you create an application for your own usage that will only interact with your own data)​ + + Click **Properties** > **Yes** > **Save**. + + ![Image of multi tenant](images/webapp-edit-multitenant.png) + + +## Application consent +You need your application to be approved in each tenant where you intend to use it. This is because your application interacts with WDATP application on behalf of your customer. + +You (or your customer if you are writing a 3rd party application) need to click the consent link and approve your application. The consent should be done with a user who has admin privileges in the active directory. + +Consent link is of the form: + +``` +https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true​ +``` + +where 00000000-0000-0000-0000-000000000000​ should be replaced with your Azure application ID + + +## Get an access token + +For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds) + +### Using C# + +>The below code was tested with nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8 + +- Create a new Console Application +- Install Nuget [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/) +- Add the below using + + ``` + using Microsoft.IdentityModel.Clients.ActiveDirectory; + ``` + +- Copy/Paste the below code in your application (do not forget to update the 3 variables: ```tenantId, appId, appSecret```) + + ``` + string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here + string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here + string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! + + const string authority = "https://login.windows.net"; + const string wdatpResourceId = "https://api.securitycenter.windows.com"; + + AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/"); + ClientCredential clientCredential = new ClientCredential(appId, appSecret); + AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult(); + string token = authenticationResult.AccessToken; + ``` + +### Using PowerShell + +Refer to [Get token using PowerShell](run-advanced-query-sample-powershell.md#get-token) + +### Using Python + +Refer to [Get token using Python](run-advanced-query-sample-python.md#get-token) + +### Using Curl + +> [!NOTE] +> The below procedure supposed Curl for Windows is already installed on your computer + +- Open a command window +- ​Set CLIENT_ID to your Azure application ID +- Set CLIENT_SECRET to your Azure application secret +- Set TENANT_ID to the Azure tenant ID of the customer that wants to use your application to access WDATP application +- Run the below command: + +``` +curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice​/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID​%/oauth2/v2.0/token" -k​ +``` + +You will get an answer of the form: + +``` +{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn aWReH7P0s0tjTBX8wGWqJUdDA"} +``` + +## Validate the token + +Sanity check to make sure you got a correct token: +- Copy/paste into [JWT](https://jwt.ms) the token you get in the previous step in order to decode it +- Validate you get a 'roles' claim with the desired permissions +- In the screenshot below you can see a decoded token acquired from an app with permissions to all of Wdatp's roles: + +![Image of token validation](images/webapp-decoded-token.png) + +## Use the token to access Windows Defender ATP API + +- Choose the API you want to use, for more information, see [Supported Windows Defender ATP APIs](exposed-apis-list.md) +- Set the Authorization header in the Http request you send to "Bearer {token}" (Bearer is the Authorization scheme) +- The Expiration time of the token is 1 hour (you can send more then one request with the same token) + +- Example of sending a request to get a list of alerts **using C#** + ``` + var httpClient = new HttpClient(); + + var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.windows.com/api/alerts"); + + request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token); + + var response = await httpClient.SendAsync(request).ConfigureAwait(false); + + // Do something useful with the response + ``` + +## Related topics +- [Windows Defender ATP APIs](apis-intro.md) +- [Supported Windows Defender ATP APIs](exposed-apis-list.md) +- [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md) \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-full-sample-powershell.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-full-sample-powershell.md new file mode 100644 index 0000000000..5c554d4040 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-full-sample-powershell.md @@ -0,0 +1,118 @@ +--- +title: Advanced Hunting API +description: Use this API to run advanced queries +keywords: apis, supported apis, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 09/24/2018 +--- + +# Windows Defender ATP APIs using PowerShell +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + + +Full scenario using multiple APIs from Windows Defender ATP. + +In this section we share PowerShell samples to + - Retrieve a token + - Use token to retrieve the latest alerts in Windows Defender ATP + - For each alert, if the alert has medium or high priority and is still in progress, check how many times the machine has connected to suspicious URL. + +>**Prerequisite**: You first need to [create an app](apis-intro.md). + +## Preparation Instructions + +- Open a PowerShell window. +- If your policy does not allow you to run the PowerShell commands, you can run the below command: +``` +Set-ExecutionPolicy -ExecutionPolicy Bypass +``` + +>For more details, refer to [PowerShell documentation](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) + +## Get token + +- Run the below + +> - $tenantId: ID of the tenant on behalf of which you want to run the query (i.e., the query will be run on the data of this tenant) +> - $appId: ID of your AAD app (the app must have 'Run advanced queries' permission to WDATP) +> - $appSecret: Secret of your AAD app +> - $suspiciousUrl: The URL + + +``` +$tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here +$appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here +$appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here +$suspiciousUrl = 'www.suspiciousUrl.com' # Paste your own URL here + +$resourceAppIdUri = 'https://securitycenter.onmicrosoft.com/windowsatpservice' +$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token" +$authBody = [Ordered] @{ + resource = "$resourceAppIdUri" + client_id = "$appId" + client_secret = "$appSecret" + grant_type = 'client_credentials' +} +$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop +$aadToken = $authResponse.access_token + + +#Get latest alert +$alertUrl = "https://api.securitycenter.windows.com/api/alerts?`$top=10" +$headers = @{ + 'Content-Type' = 'application/json' + Accept = 'application/json' + Authorization = "Bearer $aadToken" +} +$alertResponse = Invoke-WebRequest -Method Get -Uri $alertUrl -Headers $headers -ErrorAction Stop +$alerts = ($alertResponse | ConvertFrom-Json).value + +$machinesToInvestigate = New-Object System.Collections.ArrayList + +Foreach($alert in $alerts) +{ + #echo $alert.id $alert.machineId $alert.severity $alert.status + + $isSevereAlert = $alert.severity -in 'Medium', 'High' + $isOpenAlert = $alert.status -in 'InProgress', 'New' + if($isOpenAlert -and $isSevereAlert) + { + if (-not $machinesToInvestigate.Contains($alert.machineId)) + { + $machinesToInvestigate.Add($alert.machineId) > $null + } + } +} + +$commaSeparatedMachines = '"{0}"' -f ($machinesToInvestigate -join '","') + +$query = "NetworkCommunicationEvents +| where MachineId in ($commaSeparatedMachines) +| where RemoteUrl == `"$suspiciousUrl`" +| summarize ConnectionsCount = count() by MachineId" + +$queryUrl = "https://api.securitycenter.windows.com/api/advancedqueries/run" + +$queryBody = ConvertTo-Json -InputObject @{ 'Query' = $query } +$queryResponse = Invoke-WebRequest -Method Post -Uri $queryUrl -Headers $headers -Body $queryBody -ErrorAction Stop +$response = ($queryResponse | ConvertFrom-Json).Results +$response + +``` + + +## Related topic +- [Windows Defender ATP APIs](apis-intro.md) +- [Advanced Hunting API](run-advanced-query-api.md) +- [Advanced Hunting using Python](run-advanced-query-sample-python.md) +- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md) diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-list.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-list.md new file mode 100644 index 0000000000..aaf42956c2 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-list.md @@ -0,0 +1,58 @@ +--- +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, supported apis, actor, alerts, machine, user, domain, ip, file, advanced queries, advanced hunting +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 30/07/2018 +--- + +# 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-supportedapis-abovefoldlink) + +## End Point URI and Versioning + +### End Point URI: + +> The service base URI is: https://api.securitycenter.windows.com + +> The queries based OData have the '/api' prefix. For example, to get Alerts you can send GET request to https://api.securitycenter.windows.com/api/alerts + +### Versioning: + +> The API supports versioning. + +> The current version is **V1.0**. + +> To use a specific version, use this format: https://api.securitycenter.windows.com/api/{Version}. For example: https://api.securitycenter.windows.com/api/v1.0/alerts + +> If you don't specify any version ( without /v1.0/ ) you will get to the latest version. + + +Learn more about the individual supported entities where you can run API calls to and details such as HTTP request values, request headers and expected responses. + +## In this section +Topic | Description +:---|:--- +Advanced Hunting | Run queries from API. +Alerts | Run API calls such as get alerts, alert information by ID, alert related actor information, alert related IP information, and alert related machine information. +Domain |Run API calls such as get domain related machines, domain related machines, statistics, and check if a domain is seen in your organization. +File | Run API calls such as get file information, file related alerts, file related machines, and file statistics. +IP | Run API calls such as get IP related alerts, IP related machines, IP statistics, and check if and IP is seen in your organization. +Machines | Run API calls such as find machine information by IP, get machines, get machines by ID, information about logged on users, and alerts related to a given machine ID. +User | Run API calls such as get alert related user information, user information, user related alerts, and user related machines. + +## Related topic +- [Windows Defender ATP APIs](apis-intro.md) diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-odata-samples.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-odata-samples.md new file mode 100644 index 0000000000..a7384d989f --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-odata-samples.md @@ -0,0 +1,188 @@ +--- +title: OData queries with Windows Defender ATP +description: OData queries with Windows Defender ATP +keywords: apis, supported apis, odata, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 09/24/2018 +--- + +# OData queries with Windows Defender ATP +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +> If you are not familiar with OData queries, please see: [OData V4 queries](https://www.odata.org/documentation/) + +> ** Currently, [Machine](machine-windows-defender-advanced-threat-protection-new.md) and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entities supports all OData queries.** +> ** [Alert](alerts-windows-defender-advanced-threat-protection-new.md) entity support all OData queries except $filter.** + +### Example 1 + +**Get all the machines with 'High' 'RiskScore'** + +``` +HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=riskScore eq 'High' +``` + +**Response:** + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "e3a77eeddb83d581238792387b1239b01286b2f", + "computerDnsName": "examples.dev.corp.microsoft.com", + "firstSeen": "2016-11-02T23:26:03.7882168Z", + "lastSeen": "2018-11-12T10:27:08.708723Z", + "osPlatform": "Windows10", + "osVersion": "10.0.0.0", + "lastIpAddress": "123.123.10.33", + "lastExternalIpAddress": "124.124.160.172", + "agentVersion": "10.6300.18279.1001", + "osBuild": 18279, + "healthStatus": "ImpairedCommunication", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 5, + "rbacGroupName": "North", + "riskScore": "High", + "aadDeviceId": "d90b0b99-1234-1234-1234-b91d50c6796a" + }, + . + . + . + ] +} +``` + +### Example 2 + +**Get top 100 machines with 'HealthStatus' not equals to 'Active'** + +``` +HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=healthStatus ne 'Active'&$top=100 +``` + +**Response:** + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "1113333ddb83d581238792387b1239b01286b2f", + "computerDnsName": "examples.dev.corp.microsoft.com", + "firstSeen": "2016-11-02T23:26:03.7882168Z", + "lastSeen": "2018-11-12T10:27:08.708723Z", + "osPlatform": "Windows10", + "osVersion": "10.0.0.0", + "lastIpAddress": "123.123.10.33", + "lastExternalIpAddress": "124.124.160.172", + "agentVersion": "10.6300.18279.1001", + "osBuild": 18279, + "healthStatus": "ImpairedCommunication", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 5, + "rbacGroupName": "North", + "riskScore": "Medium", + "aadDeviceId": "d90b0b99-1234-1234-1234-b91d50c6796a" + }, + . + . + . + ] +} +``` + +### Example 3 + +**Get all the machines that last seen after 2018-10-20** + +``` +HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=lastSeen gt 2018-10-20Z +``` + +**Response:** + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "83113465ffceca4a731234e5dcde3357e026e873", + "computerDnsName": "examples-vm10", + "firstSeen": "2018-11-12T16:07:50.1706168Z", + "lastSeen": "2018-11-12T16:07:50.1706168Z", + "osPlatform": "WindowsServer2019", + "osVersion": null, + "lastIpAddress": "10.123.72.35", + "lastExternalIpAddress": "123.220.2.3", + "agentVersion": "10.6300.18281.1000", + "osBuild": 18281, + "healthStatus": "Active", + "isAadJoined": false, + "machineTags": [], + "rbacGroupId": 4, + "rbacGroupName": "East", + "riskScore": "None", + "aadDeviceId": null + }, + . + . + . + ] +} +``` + +### Example 4 + +**Get all the Anti-Virus scans that the user Analyst@examples.onmicrosoft.com created using WDATP** + +``` +HTTP GET https://api.securitycenter.windows.com/api/machineactions?$filter=requestor eq 'Analyst@WcdTestPrd.onmicrosoft.com' and type eq 'RunAntiVirusScan' +``` + +**Response:** + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions", + "value": [ + { + "id": "5c3e3322-d993-1234-1111-dfb136ebc8c5", + "type": "RunAntiVirusScan", + "requestor": "Analyst@examples.onmicrosoft.com", + "requestorComment": "1533", + "status": "Succeeded", + "machineId": "123321c10e44a82877af76b1d0161a17843f688a", + "creationDateTimeUtc": "2018-11-12T13:33:24.5755657Z", + "lastUpdateDateTimeUtc": "2018-11-12T13:34:32.0319826Z", + "relatedFileInfo": null + }, + . + . + . + ] +} +``` + +## Related topic +- [Windows Defender ATP APIs](apis-intro.md) diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md index 82d6912c6d..67ec69e0e1 100644 --- a/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection.md @@ -14,7 +14,7 @@ ms.localizationpriority: medium ms.date: 10/23/2017 --- -# Use the Windows Defender ATP exposed APIs +# Use the Windows Defender ATP exposed APIs (deprecated) **Applies to:** diff --git a/windows/security/threat-protection/windows-defender-atp/files-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/files-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..076ab10d21 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/files-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,49 @@ +--- +title: File resource type +description: Retrieves top recent alerts. +keywords: apis, graph api, supported apis, get, alerts, recent +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# File resource type + +[!include[Prerelease information](prerelease.md)] + +Represent a file entity in WDATP. + +# Methods +Method|Return Type |Description +:---|:---|:--- +[Get file](get-file-information-windows-defender-advanced-threat-protection-new.md) | [file](files-windows-defender-advanced-threat-protection-new.md) | Get a single file +[List file related alerts](get-file-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | Get the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities that are associated with the file. +[List file related machines](get-file-related-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | Get the [machine](machine-windows-defender-advanced-threat-protection-new.md) entities associated with the alert. +[file statistics](get-file-statistics-windows-defender-advanced-threat-protection-new.md) | Statistics summary | Retrieves the prevalence for the given file. + + +# Properties +Property | Type | Description +:---|:---|:--- +sha1 | String | Sha1 hash of the file content +sha256 | String | Sha256 hash of the file content +md5 | String | md5 hash of the file content +globalPrevalence | Integer | File prevalence accross organization +globalFirstObserved | DateTimeOffset | First time the file was observed. +globalLastObserved | DateTimeOffset | Last time the file was observed. +size | Integer | Size of the file. +fileType | String | Type of the file. +isPeFile | Boolean | true if the file is portable executable (e.g. "DLL", "EXE", etc.) +filePublisher | String | File publisher. +fileProductName | String | Product name. +signer | String | File signer. +issuer | String | File issuer. +signerHash | String | Hash of the signing certificate. +isValidCertificate | Boolean | Was signing certificate successfully verified by WDATP agent. + diff --git a/windows/security/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..5f1df97182 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,88 @@ +--- +title: Find machine information by internal IP API +description: Use this API to create calls related to finding a machine entry around a specific timestamp by internal IP. +keywords: ip, apis, graph api, supported apis, find machine, machine information +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: 07/25/2018 +--- + +# Find machine information by internal IP API + +[!include[Prerelease information](prerelease.md)] + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + +Find a machine by internal IP. + +>[!NOTE] +>The timestamp must be within the last 30 days. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' + +## HTTP request +``` +GET /api/machines/find(timestamp={time},key={IP}) +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and machine exists - 200 OK. +If no machine found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +``` +GET https://graph.microsoft.com/testwdatppreview/machines/find(timestamp=2018-06-19T10:00:00Z,key='10.166.93.61') +Content-type: application/json +``` + +**Response** + +Here is an example of the response. + +The response will return a list of all machines that reported this IP address within sixteen minutes prior and after the timestamp. + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#Machines", + "value": [ + { + "id": "04c99d46599f078f1c3da3783cf5b95f01ac61bb", + "computerDnsName": "", + "firstSeen": "2017-07-06T01:25:04.9480498Z", + "osPlatform": "Windows10", +… +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection.md index 0f74a2e1cf..f1e846309d 100644 --- a/windows/security/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 07/25/2018 --- -# Find machine information by internal IP API +# Find machine information by internal IP API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Find a machine entity around a specific timestamp by internal IP. diff --git a/windows/security/threat-protection/windows-defender-atp/find-machines-by-ip-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/find-machines-by-ip-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..495830551e --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/find-machines-by-ip-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,105 @@ +--- +title: Find machines by internal IP API +description: Find machines seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp +keywords: apis, graph api, supported apis, get, machine, IP, find, find machine, by ip, ip +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Find machines by internal IP API + +[!include[Prerelease information](prerelease.md)] + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) +- Find machines seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp +- The given timestamp must be in the past 30 days. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only machines,that the user have access to, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/machines/findbyip(ip='{IP}',timestamp={TimeStamp}) +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and machines were found - 200 OK with list of the machines in the response body. +If no machine found - 404 Not Found. +If the timestamp is not in the past 30 days - 400 Bad Request. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/machines/findbyip(ip='10.248.240.38',timestamp=2018-09-22T08:44:05Z) +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "863fed4b174465c703c6e412965a31b5e1884cc4", + "computerDnsName": "mymachine33.contoso.com", + "firstSeen": "2018-07-31T14:20:55.8223496Z", + "lastSeen": null, + "osPlatform": "Windows10", + "osVersion": null, + "lastIpAddress": "10.248.240.38", + "lastExternalIpAddress": "167.220.2.166", + "agentVersion": "10.3720.16299.98", + "osBuild": 16299, + "healthStatus": "Active", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 75, + "riskScore": "Medium", + "aadDeviceId": null + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md index 12e531ccb6..ac3608c9c2 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-actor-information-windows-defender-advanced-threat-protection.md @@ -15,12 +15,13 @@ ms.date: 12/08/2017 --- -# Get actor information API +# Get actor information API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves an actor information report. diff --git a/windows/security/threat-protection/windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md index 216bf3fd90..c0ff5a988c 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-actor-related-alerts-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get actor related alerts API +# Get actor related alerts API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves all alerts related to a given actor. diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..d2187f343b --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,98 @@ +--- +title: Get alert information by ID API +description: Retrieves an alert by its ID. +keywords: apis, graph api, supported apis, get, alert, information, id +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alert.Read.All | 'Read all alerts' +Application | Alert.ReadWrite.All | 'Read and write all alerts' +Delegated (work or school account) | Alert.Read | 'Read alerts' +Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- The user needs to have access to the machine associated with the alert, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/alerts/{id} +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200 OK, and the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entity in the response body. If alert with the specified id was not found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442 +``` + +**Response** + +Here is an example of the response. + + +``` +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts", + "id": "636688558380765161_2136280442", + "severity": "Informational", + "status": "InProgress", + "description": "Some alert description 1", + "recommendedAction": "Some recommended action 1", + "alertCreationTime": "2018-08-03T01:17:17.9516179Z", + "category": "General", + "title": "Some alert title 1", + "threatFamilyName": null, + "detectionSource": "WindowsDefenderAtp", + "classification": "TruePositive", + "determination": null, + "assignedTo": "best secop ever", + "resolvedTime": null, + "lastEventTime": "2018-08-02T07:02:52.0894451Z", + "firstEventTime": "2018-08-02T07:02:52.0894451Z", + "actorName": null, + "machineId": "ff0c3800ed8d66738a514971cd6867166809369f" +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md index d74debcef4..70160a3b2c 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get alert information by ID API +# Get alert information by ID API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves an alert by its ID. diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md index 6eb366dc10..99fcbab5bf 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-actor-info-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get alert related actor information API +# Get alert related actor information API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves the actor information related to the specific alert. diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..0df45988d6 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,87 @@ +--- +title: Get alert related domains information +description: Retrieves all domains related to a specific alert. +keywords: apis, graph api, supported apis, get alert information, alert information, related domain +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | URL.Read.All | 'Read URLs' +Delegated (work or school account) | URL.Read.All | 'Read URLs' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- The user needs to have access to the machine associated with the alert, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/alerts/{id}/domains +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and alert and domain exist - 200 OK. +If alert not found or domain not found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + + +``` +GET https://api.securitycenter.windows.com/alerts/636688558380765161_2136280442/domains +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/$metadata#Domains", + "value": [ + { + "host": "www.example.com" + } + ] +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md index 4558e6c341..d0cfda9671 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection.md @@ -14,13 +14,16 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get alert related domain information API +# Get alert related domain information API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] + + Retrieves all domains related to a specific alert. diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..0761a7b22c --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,100 @@ +--- +title: Get alert related files information +description: Retrieves all files related to a specific alert. +keywords: apis, graph api, supported apis, get alert information, alert information, related files +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | File.Read.All | 'Read file profiles' +Delegated (work or school account) | File.Read.All | 'Read file profiles' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- The user needs to have access to the machine associated with the alert, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/alerts/{id}/files +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and alert and files exist - 200 OK. +If alert not found or files not found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/files +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files", + "value": [ + { + "sha1": "654f19c41d9662cf86be21bf0af5a88c38c56a9d", + "sha256": "2f905feec2798cee6f63da2c26758d86bfeaab954c01e20ac7085bf55fedde87", + "md5": "82849dc81d94056224445ea73dc6153a", + "globalPrevalence": 33, + "globalFirstObserved": "2018-07-17T18:17:27.5909748Z", + "globalLastObserved": "2018-08-06T16:07:12.9414137Z", + "windowsDefenderAVThreatName": null, + "size": 801112, + "fileType": "PortableExecutable", + "isPeFile": true, + "filePublisher": null, + "fileProductName": null, + "signer": "Microsoft Windows", + "issuer": "Microsoft Development PCA 2014", + "signerHash": "9e284231a4d1c53fc8d4492b09f65116bf97447f", + "isValidCertificate": true + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md index 46fc01cffb..cc2ec68bf7 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get alert related files information API +# Get alert related files information API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves all files related to a specific alert. diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..0aa81fbd10 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,89 @@ +--- +title: Get alert related IPs information +description: Retrieves all IPs related to a specific alert. +keywords: apis, graph api, supported apis, get alert information, alert information, related ip +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Ip.Read.All | 'Read IP address profiles' +Delegated (work or school account) | Ip.Read.All | 'Read IP address profiles' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- The user needs to have access to the machine associated with the alert, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/alerts/{id}/ips +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and alert and an IP exist - 200 OK. If alert not found or IPs not found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/alerts/636688558380765161_2136280442/ips +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/$metadata#Ips", + "value": [ + { + "id": "104.80.104.128" + }, + { + "id": "23.203.232.228 + } + ] +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md index 1952732087..fba77be35c 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get alert related IP information API +# Get alert related IP information API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves all IPs related to a specific alert. diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..5eec325056 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,99 @@ +--- +title: Get alert related machine information +description: Retrieves all machines related to a specific alert. +keywords: apis, graph api, supported apis, get alert information, alert information, related machine +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get alert related machine information API +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Retrieves machine that is related to a specific alert. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine information' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- The user needs to have access to the machine associated with the alert, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/alerts/{id}/machine +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and alert and machine exist - 200 OK. +If alert not found or machine not found - 404 Not Found. + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + + +``` +GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/machine +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines/$entity", + "id": "ff0c3800ed8d66738a514971cd6867166809369f", + "computerDnsName": "amazingmachine.contoso.com", + "firstSeen": "2017-12-10T07:47:34.4269783Z", + "lastSeen": "2017-12-10T07:47:34.4269783Z", + "osPlatform": "Windows10", + "osVersion": "10.0.0.0", + "systemProductName": null, + "lastIpAddress": "172.17.0.0", + "lastExternalIpAddress": "167.220.0.0", + "agentVersion": "10.5830.17732.1001", + "osBuild": 17732, + "healthStatus": "Active", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 75, + "riskScore": "Low", + "aadDeviceId": "80fe8ff8-0000-0000-9591-41f0491218f9" +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md index 52169b949b..a9abbd55bb 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get alert related machine information API +# Get alert related machine information API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves all machines related to a specific alert. diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..143f06474b --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,91 @@ +--- +title: Get alert related user information +description: Retrieves the user associated to a specific alert. +keywords: apis, graph api, supported apis, get, alert, information, related, user +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | User.Read.All | 'Read user profiles' +Delegated (work or school account) | User.Read.All | 'Read user profiles' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- The user needs to have access to the machine associated with the alert, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/alerts/{id}/user +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and alert and a user exists - 200 OK with user in the body. +If alert not found or user not found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + + +``` +GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/user +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users/$entity", + "id": "contoso\\user1", + "firstSeen": "2018-08-02T00:00:00Z", + "lastSeen": "2018-08-04T00:00:00Z", + "mostPrevalentMachineId": null, + "leastPrevalentMachineId": null, + "logonTypes": "Network", + "logOnMachinesCount": 3, + "isDomainAdmin": false, + "isOnlyNetworkUser": null +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection.md index c60acf0220..cd9221b4db 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get alert related user information API +# Get alert related user information API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves the user associated to a specific alert. diff --git a/windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..c68a75f6be --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,130 @@ +--- +title: List alerts API +description: Retrieves top recent alerts. +keywords: apis, graph api, supported apis, get, alerts, recent +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# List alerts API +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + +[!include[Prerelease information](prerelease.md)] + + +Retrieves top recent alerts. + + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alert.Read.All | 'Read all alerts' +Application | Alert.ReadWrite.All | 'Read and write all alerts' +Delegated (work or school account) | Alert.Read | 'Read alerts' +Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- The response will include only alerts that are associated with machines that the user can access, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/alerts +``` + +## Optional query parameters +Method supports $skip and $top query parameters. + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200 OK, and a list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) objects in the response body. If no recent alerts found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/alerts +``` + +**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. + + +``` +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts", + "value": [ + { + "id": "636688558380765161_2136280442", + "severity": "Informational", + "status": "InProgress", + "description": "Some alert description 1", + "recommendedAction": "Some recommended action 1", + "alertCreationTime": "2018-08-03T01:17:17.9516179Z", + "category": "General", + "title": "Some alert title 1", + "threatFamilyName": null, + "detectionSource": "WindowsDefenderAtp", + "classification": "TruePositive", + "determination": null, + "assignedTo": "best secop ever", + "resolvedTime": null, + "lastEventTime": "2018-08-02T07:02:52.0894451Z", + "firstEventTime": "2018-08-02T07:02:52.0894451Z", + "actorName": null, + "machineId": "ff0c3800ed8d66738a514971cd6867166809369f" + }, + { + "id": "636688558380765161_2136280442", + "severity": "Informational", + "status": "InProgress", + "description": "Some alert description 2", + "recommendedAction": "Some recommended action 2", + "alertCreationTime": "2018-08-04T01:17:17.9516179Z", + "category": "General", + "title": "Some alert title 2", + "threatFamilyName": null, + "detectionSource": "WindowsDefenderAtp", + "classification": "TruePositive", + "determination": null, + "assignedTo": "best secop ever", + "resolvedTime": null, + "lastEventTime": "2018-08-03T07:02:52.0894451Z", + "firstEventTime": "2018-08-03T07:02:52.0894451Z", + "actorName": null, + "machineId": "ff0c3800ed8d66738a514971cd6867166809369d" + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md index 29b9ca446e..30daf66f8c 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get alerts API +# Get alerts API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves top recent alerts. diff --git a/windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..ee1404dd5e --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,129 @@ +--- +title: Get domain related alerts API +description: Retrieves a collection of alerts related to a given domain address. +keywords: apis, graph api, supported apis, get, domain, related, alerts +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alert.Read.All | 'Read all alerts' +Application | Alert.ReadWrite.All | 'Read and write all alerts' +Delegated (work or school account) | Alert.Read | 'Read alerts' +Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only alerts, associated with machines, that the user have access to, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/domains/{domain}/alerts +``` + +## Request headers + +Header | Value +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and domain and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities. If domain or alert does not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/domains/client.wns.windows.com/alerts +``` + +**Response** + +Here is an example of the response. + +``` +HTTP/1.1 200 OK +Content-type: application/json + +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "636688558380765161_2136280442", + "severity": "Informational", + "status": "InProgress", + "description": "Some alert description 1", + "recommendedAction": "Some recommended action 1", + "alertCreationTime": "2018-08-03T01:17:17.9516179Z", + "category": "General", + "title": "Some alert title 1", + "threatFamilyName": null, + "detectionSource": "WindowsDefenderAtp", + "classification": "TruePositive", + "determination": null, + "assignedTo": "best secop ever", + "resolvedTime": null, + "lastEventTime": "2018-08-02T07:02:52.0894451Z", + "firstEventTime": "2018-08-02T07:02:52.0894451Z", + "actorName": null, + "machineId": "ff0c3800ed8d66738a514971cd6867166809369f" + }, + { + "id": "636688558380765161_2136280442", + "severity": "Informational", + "status": "InProgress", + "description": "Some alert description 2", + "recommendedAction": "Some recommended action 2", + "alertCreationTime": "2018-08-04T01:17:17.9516179Z", + "category": "General", + "title": "Some alert title 2", + "threatFamilyName": null, + "detectionSource": "WindowsDefenderAtp", + "classification": "TruePositive", + "determination": null, + "assignedTo": "best secop ever", + "resolvedTime": null, + "lastEventTime": "2018-08-03T07:02:52.0894451Z", + "firstEventTime": "2018-08-03T07:02:52.0894451Z", + "actorName": null, + "machineId": "ff0c3800ed8d66738a514971cd6867166809369d" + } + ] +} +``` + diff --git a/windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md index 5f0b8ccfc5..4d2cd0fc45 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection.md @@ -14,13 +14,15 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get domain related alerts API +# Get domain related alerts API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] + Retrieves a collection of alerts related to a given domain address. diff --git a/windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..4d69da1a53 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,122 @@ +--- +title: Get domain related machines API +description: Retrieves a collection of machines related to a given domain address. +keywords: apis, graph api, supported apis, get, domain, related, machines +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get domain related machines API +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Retrieves a collection of machines that have communicated to or from a given domain address. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only machines that the user can access, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/domains/{domain}/machines +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and domain and machine exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities. If domain or machines do not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + + +``` +GET https://api.securitycenter.windows.com/api/domains/api.securitycenter.windows.com/machines +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "02ea9a24e8bd39c247ed7ca0edae879c321684e5", + "computerDnsName": "testMachine1", + "firstSeen": "2018-07-30T20:12:00.3708661Z", + "lastSeen": "2018-07-30T20:12:00.3708661Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "10.209.67.177", + "lastExternalIpAddress": "167.220.1.210", + "agentVersion": "10.5830.18208.1000", + "osBuild": 18208, + "healthStatus": "Inactive", + "isAadJoined": false, + "machineTags": [], + "rbacGroupId": 75, + "riskScore": "Low", + "aadDeviceId": null + }, + { + "id": "02efb9a9b85f07749a018fbf3f962b4700b3b949", + "computerDnsName": "testMachine2", + "firstSeen": "2018-07-30T19:50:47.3618349Z", + "lastSeen": "2018-07-30T19:50:47.3618349Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "10.209.70.231", + "lastExternalIpAddress": "167.220.0.28", + "agentVersion": "10.5830.18208.1000", + "osBuild": 18208, + "healthStatus": "Inactive", + "isAadJoined": false, + "machineTags": [], + "rbacGroupId": 75, + "riskScore": "None", + "aadDeviceId": null + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection.md index c09460e204..9995b7a57f 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get domain related machines API +# Get domain related machines API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves a collection of machines related to a given domain address. diff --git a/windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..d3dd0b2f72 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,84 @@ +--- +title: Get domain statistics API +description: Retrieves the prevalence for the given domain. +keywords: apis, graph api, supported apis, get, domain, domain related machines +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | URL.Read.All | 'Read URLs' +Delegated (work or school account) | URL.Read.All | 'Read URLs' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/domains/{domain}/stats +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and domain exists - 200 OK, with statistics object in the response body. +If domain does not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/domains/example.com/stats +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgDomainStats", + "host": "example.com", + "orgPrevalence": "4070", + "orgFirstSeen": "2017-07-30T13:23:48Z", + "orgLastSeen": "2017-08-29T13:09:05Z" +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection.md index 2e3cde9b70..7cab84b5fb 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get domain statistics API +# Get domain statistics API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves the prevalence for the given domain. diff --git a/windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..2080cabc06 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,98 @@ +--- +title: Get file information API +description: Retrieves a file by identifier Sha1, Sha256, or MD5. +keywords: apis, graph api, supported apis, get, file, information, sha1, sha256, md5 +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | File.Read.All | 'Read all file profiles' +Delegated (work or school account) | File.Read.All | 'Read all file profiles' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) + + +## HTTP request +``` +GET /api/files/{id} +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and file exists - 200 OK with the [file](files-windows-defender-advanced-threat-protection-new.md) entity in the body. +If file does not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1 +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files/$entity", + "sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1", + "sha256": "d4447dffdbb2889b4b4e746b0bc882df1b854101614b0aa83953ef3cb66904cf", + "md5": "7f05a371d2beffb3784fd2199f81d730", + "globalPrevalence": 7329, + "globalFirstObserved": "2018-04-08T05:50:29.4459725Z", + "globalLastObserved": "2018-08-07T23:35:11.1361328Z", + "windowsDefenderAVThreatName": null, + "size": 391680, + "fileType": "PortableExecutable", + "isPeFile": true, + "filePublisher": null, + "fileProductName": null, + "signer": null, + "issuer": null, + "signerHash": null, + "isValidCertificate": null +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection.md index 2d6f45993f..9683f68898 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get file information API +# Get file information API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves a file by identifier Sha1, Sha256, or MD5. diff --git a/windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..0ef637c98e --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,107 @@ +--- +title: Get file related alerts API +description: Retrieves a collection of alerts related to a given file hash. +keywords: apis, graph api, supported apis, get, file, hash +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alert.Read.All | 'Read all alerts' +Application | Alert.ReadWrite.All | 'Read and write all alerts' +Delegated (work or school account) | Alert.Read | 'Read alerts' +Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only alerts, associated with machines, that the user have access to, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/files/{id}/alerts +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and file and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body. +If file or alerts do not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/alerts +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts", + "value": [ + { + "id": "636692391408655573_2010598859", + "severity": "Low", + "status": "New", + "description": "test alert", + "recommendedAction": "do this and that", + "alertCreationTime": "2018-08-07T11:45:40.0199932Z", + "category": "None", + "title": "test alert", + "threatFamilyName": null, + "detectionSource": "CustomerTI", + "classification": null, + "determination": null, + "assignedTo": null, + "resolvedTime": null, + "lastEventTime": "2018-08-03T16:45:21.7115182Z", + "firstEventTime": "2018-08-03T16:45:21.7115182Z", + "actorName": null, + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07" + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection.md index 89272a50e2..3967df849d 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get file related alerts API +# Get file related alerts API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves a collection of alerts related to a given file hash. diff --git a/windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..94de515e8e --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,123 @@ +--- +title: Get file related machines API +description: Retrieves a collection of machines related to a given file hash. +keywords: apis, graph api, supported apis, get, machines, hash +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only machines, that the user have access to, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/files/{id}/machines +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and file and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. +If file or machines do not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/files/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/machines +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "computerDnsName": "mymachine1.contoso.com", + "firstSeen": "2018-08-02T14:55:03.7791856Z", + "lasttSeen": "2018-07-09T13:22:45.1250071Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "172.17.230.209", + "lastExternalIpAddress": "167.220.196.71", + "agentVersion": "10.5830.18209.1001", + "osBuild": 18209, + "healthStatus": "Active", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 140, + "riskScore": "Low", + "aadDeviceId": null + }, + { + "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7", + "computerDnsName": "mymachine2.contoso.com", + "firstSeen": "2018-07-09T13:22:45.1250071Z", + "lasttSeen": "2018-07-09T13:22:45.1250071Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "192.168.12.225", + "lastExternalIpAddress": "79.183.65.82", + "agentVersion": "10.5820.17724.1000", + "osBuild": 17724, + "healthStatus": "Inactive", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 140, + "riskScore": "Low", + "aadDeviceId": null + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection.md index 62a8f25bcf..dc8a07b552 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get file related machines API +# Get file related machines API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves a collection of machines related to a given file hash. diff --git a/windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..31913eb556 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,93 @@ +--- +title: Get file statistics API +description: Retrieves the prevalence for the given file. +keywords: apis, graph api, supported apis, get, file, statistics +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | File.Read.All | 'Read file profiles' +Delegated (work or school account) | File.Read.All | 'Read file profiles' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/files/{id}/stats +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and file exists - 200 OK with statistical data in the body. +If file do not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/stats +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgFileStats", + "sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1", + "orgPrevalence": "3", + "orgFirstSeen": "2018-07-15T06:13:59Z", + "orgLastSeen": "2018-08-03T16:45:21Z", + "topFileNames": [ + "chrome_1.exe", + "chrome_2.exe" + ] +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection.md index 07424aafd3..e7b702fac8 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get file statistics API +# Get file statistics API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves the prevalence for the given file. diff --git a/windows/security/threat-protection/windows-defender-atp/get-fileactions-collection-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-fileactions-collection-windows-defender-advanced-threat-protection.md index fb469ffac8..b83bae0e6d 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-fileactions-collection-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-fileactions-collection-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get FileActions collection API +# Get FileActions collection API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Gets collection of actions done on files. Get FileActions collection API supports OData V4 queries. diff --git a/windows/security/threat-protection/windows-defender-atp/get-filemachineaction-object-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-filemachineaction-object-windows-defender-advanced-threat-protection.md index 0d846e906b..5fc6065ee7 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-filemachineaction-object-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-filemachineaction-object-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get FileMachineAction object API +# Get FileMachineAction object API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Gets file and machine actions. diff --git a/windows/security/threat-protection/windows-defender-atp/get-filemachineactions-collection-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-filemachineactions-collection-windows-defender-advanced-threat-protection.md index 27eb723cd9..b00ad9d909 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-filemachineactions-collection-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-filemachineactions-collection-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get FileMachineActions collection API +# Get FileMachineActions collection API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Get collection of file and machine actions. Get FileMachineActions collection API supports OData V4 queries. diff --git a/windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..27c06e86a8 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,106 @@ +--- +title: Get IP related alerts API +description: Retrieves a collection of alerts related to a given IP address. +keywords: apis, graph api, supported apis, get, ip, related, alerts +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alert.Read.All | 'Read all alerts' +Application | Alert.ReadWrite.All | 'Read and write all alerts' +Delegated (work or school account) | Alert.Read | 'Read alerts' +Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only alerts, associated with machines, that the user have access to, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/ips/{ip}/alerts +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and IP and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body. +If IP and alerts do not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + + +``` +GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/alerts +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts", + "value": [ + { + "id": "636692391408655573_2010598859", + "severity": "Low", + "status": "New", + "description": "test alert", + "recommendedAction": "do this and that", + "alertCreationTime": "2018-08-07T11:45:40.0199932Z", + "category": "None", + "title": "test alert", + "threatFamilyName": null, + "detectionSource": "CustomerTI", + "classification": null, + "determination": null, + "assignedTo": null, + "resolvedTime": null, + "lastEventTime": "2018-08-03T16:45:21.7115182Z", + "firstEventTime": "2018-08-03T16:45:21.7115182Z", + "actorName": null, + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07" + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection.md index 32e5f6f95e..3502e90557 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get IP related alerts API +# Get IP related alerts API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves a collection of alerts related to a given IP address. diff --git a/windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..20449184f7 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,123 @@ +--- +title: Get IP related machines API +description: Retrieves a collection of machines related to a given IP address. +keywords: apis, graph api, supported apis, get, ip, related, machines +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get IP related machines API +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + + +Retrieves a collection of machines that communicated with or from a particular IP. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only machines, that the user have access to, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/ips/{ip}/machines +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and IP and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. +If IP or machines do not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/machines +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "computerDnsName": "mymachine1.contoso.com", + "firstSeen": "2018-08-02T14:55:03.7791856Z", + "lastSeen": "2018-08-02T14:55:03.7791856Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "172.17.230.209", + "lastExternalIpAddress": "167.220.196.71", + "agentVersion": "10.5830.18209.1001", + "osBuild": 18209, + "healthStatus": "Active", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 140, + "riskScore": "Low", + "aadDeviceId": null + }, + { + "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7", + "computerDnsName": "mymachine2.contoso.com", + "firstSeen": "2018-07-09T13:22:45.1250071Z", + "lastSeen": "2018-07-09T13:22:45.1250071Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "192.168.12.225", + "lastExternalIpAddress": "79.183.65.82", + "agentVersion": "10.5820.17724.1000", + "osBuild": 17724, + "healthStatus": "Inactive", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 140, + "riskScore": "Low", + "aadDeviceId": null + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md index acbfa51a4a..72071848e6 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md @@ -37,8 +37,7 @@ Content type | application/json Empty ## Response -If successful and IP and machines exists - 200 OK. -If IP or machines do not exist - 404 Not Found. +If successful and IP and machines exists - 200 OK. If IP or machines do not exist - 404 Not Found. ## Example diff --git a/windows/security/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..763444713a --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,85 @@ +--- +title: Get IP statistics API +description: Retrieves the prevalence for the given IP. +keywords: apis, graph api, supported apis, get, ip, statistics, prevalence +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Ip.Read.All | 'Read IP address profiles' +Delegated (work or school account) | Ip.Read.All | 'Read IP address profiles' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/ips/{ip}/stats +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and ip exists - 200 OK with statistical data in the body. IP do not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/stats +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgIPStats", + "ipAddress": "10.209.67.177", + "orgPrevalence": "63515", + "orgFirstSeen": "2017-07-30T13:36:06Z", + "orgLastSeen": "2017-08-29T13:32:59Z" +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..4211bbbb1f --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,102 @@ +--- +title: Get machine by ID API +description: Retrieves a machine entity by ID. +keywords: apis, graph api, supported apis, get, machines, entity, id +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get machine by ID API + +[!include[Prerelease information](prerelease.md)] + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) +Retrieves a machine entity by ID. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- User needs to have access to the machine, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + + +## HTTP request +``` +GET /api/machines/{id} +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and machine exists - 200 OK with the [machine](machine-windows-defender-advanced-threat-protection-new.md) entity in the body. +If machine with the specified id was not found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07 +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machine", + "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "computerDnsName": "mymachine1.contoso.com", + "firstSeen": "2018-08-02T14:55:03.7791856Z", + "lastSeen": "2018-08-02T14:55:03.7791856Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "172.17.230.209", + "lastExternalIpAddress": "167.220.196.71", + "agentVersion": "10.5830.18209.1001", + "osBuild": 18209, + "healthStatus": "Active", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 140, + "riskScore": "Low", + "aadDeviceId": null +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection.md index 078641587d..66f525a094 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get machine by ID API +# Get machine by ID API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves a machine entity by ID. diff --git a/windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..31988d7d7b --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,105 @@ +--- +title: Get machine log on users API +description: Retrieves a collection of logged on users. +keywords: apis, graph api, supported apis, get, machine, log on, users +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get machine log on users API + +[!include[Prerelease information](prerelease.md)] + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) +Retrieves a collection of logged on users. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | User.Read.All | 'Read user profiles' +Delegated (work or school account) | User.Read.All | 'Read user profiles' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include users only if the machine is visible to the user, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/machines/{id}/logonusers +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and machine and user exist - 200 OK with list of [user](user-windows-defender-advanced-threat-protection-new.md) entities in the body +If no machine found or no users found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/logonusers +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users", + "value": [ + { + "id": "contoso\\user1", + "firstSeen": "2018-08-02T00:00:00Z", + "lastSeen": "2018-08-04T00:00:00Z", + "mostPrevalentMachineId": null, + "leastPrevalentMachineId": null, + "logonTypes": "Network", + "logOnMachinesCount": 3, + "isDomainAdmin": false, + "isOnlyNetworkUser": null + }, + { + "id": "contoso\\user2", + "firstSeen": "2018-08-02T00:00:00Z", + "lastSeen": "2018-08-05T00:00:00Z", + "mostPrevalentMachineId": null, + "leastPrevalentMachineId": null, + "logonTypes": "Network", + "logOnMachinesCount": 3, + "isDomainAdmin": false, + "isOnlyNetworkUser": null + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection.md index 0bf2c47c64..13530b98e5 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get machine log on users API +# Get machine log on users API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves a collection of logged on users. diff --git a/windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..fc89631378 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,105 @@ +--- +title: Get machine related alerts API +description: Retrieves a collection of alerts related to a given machine ID. +keywords: apis, graph api, supported apis, get, machines, related, alerts +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get machine related alerts API + +[!include[Prerelease information](prerelease.md)] + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) +Retrieves a collection of alerts related to a given machine ID. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alert.Read.All | 'Read all alerts' +Application | Alert.ReadWrite.All | 'Read and write all alerts' +Delegated (work or school account) | Alert.Read | 'Read alerts' +Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- User needs to have access to the machine, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/machines/{id}/alerts +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and machine and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body. If no machine or no alerts found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + + +``` +GET https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/alerts +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts", + "value": [ + { + "id": "636692391408655573_2010598859", + "severity": "Low", + "status": "New", + "description": "test alert", + "recommendedAction": "do this and that", + "alertCreationTime": "2018-08-07T11:45:40.0199932Z", + "category": "None", + "title": "test alert", + "threatFamilyName": null, + "detectionSource": "CustomerTI", + "classification": null, + "determination": null, + "assignedTo": null, + "resolvedTime": null, + "lastEventTime": "2018-08-03T16:45:21.7115182Z", + "firstEventTime": "2018-08-03T16:45:21.7115182Z", + "actorName": null, + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07" + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection.md index 4d976968c0..4803e86973 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get machine related alerts API +# Get machine related alerts API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves a collection of alerts related to a given machine ID. diff --git a/windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..96a4953581 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,90 @@ +--- +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: medium +ms.date: 12/08/2017 +--- + +# Get machineAction API +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Get action performed on a machine. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET https://api.securitycenter.windows.com/api/machineactions/{id} +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200, Ok response code with a [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity. If machine action entity with the specified id was not found - 404 Not Found. + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/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://api.securitycenter.windows.com/api/$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", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z", + "lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z", + "relatedFileInfo": null +} + + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection.md index 2c94ca5628..b3ed113094 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get MachineAction object API +# Get MachineAction object API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Get actions done on a machine. diff --git a/windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..5a137cb5a8 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,169 @@ +--- +title: List machineActions 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: medium +ms.date: 12/08/2017 +--- + +# List MachineActions API + +[!include[Prerelease information](prerelease.md)] + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + Gets collection of actions done on machines. + Get MachineAction collection API supports [OData V4 queries](https://www.odata.org/documentation/). + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET https://api.securitycenter.windows.com/api/machineactions +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200, Ok response code with a collection of [machineAction](machineaction-windows-defender-advanced-threat-protection-new.md) entities. + + +## Example 1 + +**Request** + +Here is an example of the request on an organization that has three MachineActions. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/machineactions +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions", + "value": [ + { + "id": "69dc3630-1ccc-4342-acf3-35286eec741d", + "type": "CollectInvestigationPackage", + "requestor": "Analyst@contoso.com", + "requestorComment": "test", + "status": "Succeeded", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z", + "lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z", + "relatedFileInfo": null + }, + { + "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba", + "type": "RunAntiVirusScan", + "requestor": "Analyst@contoso.com", + "requestorComment": "Check machine for viruses due to alert 3212", + "status": "Succeeded", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z", + "lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z", + "relatedFileInfo": null + }, + { + "id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e", + "type": "StopAndQuarantineFile", + "requestor": "Analyst@contoso.com", + "requestorComment": "test", + "status": "Succeeded", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2018-12-04T12:15:40.6052029Z", + "lastUpdateTimeUtc": "2018-12-04T12:16:14.2899973Z", + "relatedFileInfo": { + "fileIdentifier": "a0c659857ccbe457fdaf5fe21d54efdcbf6f6508", + "fileIdentifierType": "Sha1" + } + } + ] +} +``` + +## 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://api.securitycenter.windows.com/api/machineactions?$filter=machineId eq 'f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f'&$top=2 +``` + +**Response** + +Here is an example of the response. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions", + "value": [ + { + "id": "69dc3630-1ccc-4342-acf3-35286eec741d", + "type": "CollectInvestigationPackage", + "requestor": "Analyst@contoso.com", + "requestorComment": "test", + "status": "Succeeded", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z", + "lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z", + "relatedFileInfo": null + }, + { + "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba", + "type": "RunAntiVirusScan", + "requestor": "Analyst@contoso.com", + "requestorComment": "Check machine for viruses due to alert 3212", + "status": "Succeeded", + "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", + "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z", + "lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z", + "relatedFileInfo": null + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection.md index c86ead0780..0983daee3c 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get MachineActions collection API +# Get MachineActions collection API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Gets collection of actions done on machines. Get MachineAction collection API supports OData V4 queries. diff --git a/windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..5d41431d83 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,124 @@ +--- +title: List machines API +description: Retrieves a collection of recently seen machines. +keywords: apis, graph api, supported apis, get, machines +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# List machines API + +[!include[Prerelease information](prerelease.md)] + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +Retrieves a collection of machines that have communicated with WDATP cloud on the last 30 days. +Get Machines collection API supports [OData V4 queries](https://www.odata.org/documentation/). +The OData's Filter query is supported on: "Id", "ComputerDnsName", "LastSeen", "LastIpAddress", "HealthStatus", "OsPlatform", "RiskScore", "MachineTags" and "RbacGroupId" + +## Permissions + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only machines,that the user have access to, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET https://api.securitycenter.windows.com/api/machines +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. If no recent machines - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/machines +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "computerDnsName": "mymachine1.contoso.com", + "firstSeen": "2018-08-02T14:55:03.7791856Z", + "lastSeen": "2018-08-02T14:55:03.7791856Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "172.17.230.209", + "lastExternalIpAddress": "167.220.196.71", + "agentVersion": "10.5830.18209.1001", + "osBuild": 18209, + "healthStatus": "Active", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 140, + "riskScore": "Low", + "aadDeviceId": null + }, + { + "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7", + "computerDnsName": "mymachine2.contoso.com", + "firstSeen": "2018-07-09T13:22:45.1250071Z", + "lastSeen": "2018-07-09T13:22:45.1250071Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "192.168.12.225", + "lastExternalIpAddress": "79.183.65.82", + "agentVersion": "10.5820.17724.1000", + "osBuild": 17724, + "healthStatus": "Inactive", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 140, + "riskScore": "Low", + "aadDeviceId": null + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md index d442db809b..2aae8e0d5d 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection.md @@ -14,12 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get machines API +# Get machines API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] Retrieves a collection of recently seen machines. diff --git a/windows/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..6b90d0ff62 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,84 @@ +--- +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: medium +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](collect-investigation-package-windows-defender-advanced-threat-protection-new.md). + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.CollectForensics | 'Collect forensics' +Delegated (work or school account) | Machine.CollectForensics | 'Collect forensics' + +>[!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-windows-defender-advanced-threat-protection.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-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET https://api.securitycenter.windows.com/api/machineactions/{machine action id}/getPackageUri +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## 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://api.securitycenter.windows.com/api/machineactions/7327b54fd718525cbca07dacde913b5ac3c85673/GetPackageUri + +``` + +**Response** + +Here is an example of the response. + +[!include[Improve request performance](improverequestperformance-new.md)] + + +``` +HTTP/1.1 200 Ok +Content-type: application/json + +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$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/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection.md index 60f0e29f88..688491a75d 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get package SAS URI API +# Get package SAS URI API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Get a URI that allows downloading of an investigation package. diff --git a/windows/security/threat-protection/windows-defender-atp/get-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..ccd438a908 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,92 @@ +--- +title: Get Ti Indicator by ID API +description: Retrieves Ti Indicator entity by ID. +keywords: apis, public api, supported apis, get, ti indicator, entity, id +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get TI Indicator by ID API + +[!include[Prerelease information](prerelease.md)] + +>[!Note] +> Currently this API is supported only for AppOnly context requests. (See [Get access without a user](exposed-apis-create-app-webapp.md) for more information) + + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) +Retrieves a TI Indicator entity by ID. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Ti.ReadWrite | 'Read and write TI Indicators' + + +## HTTP request +``` +GET https://api.securitycenter.windows.com/api/tiindicators/{id} +``` + +[!include[Improve request performance](improverequestperformance-new.md)] + + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and TI Indicator exists - 200 OK with the [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity in the body. +If TI Indicator with the specified id was not found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +``` +GET https://api.securitycenter.windows.com/api/tiindicators/220e7d15b0b3d7fac48f2bd61114db1022197f7f +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#TiIndicators/$entity", + "indicator": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", + "indicatorType": "FileSha1", + "title": "test", + "creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z", + "createdBy": "45097602-0cfe-4cc6-925f-9f453233e62c", + "expirationTime": "2020-12-12T00:00:00Z", + "action": "AlertAndBlock", + "severity": "Informational", + "description": "test", + "recommendedActions": "TEST" +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-ti-indicators-collection-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-ti-indicators-collection-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..d2c398ee0f --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-ti-indicators-collection-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,109 @@ +--- +title: List TiIndicators API +description: Use this API to create calls related to get TiIndicators collection +keywords: apis, public api, supported apis, TiIndicators collection +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# List TiIndicators API + +[!include[Prerelease information](prerelease.md)] + +>[!Note] +> Currently this API is supported only for AppOnly context requests. (See [Get access without a user](exposed-apis-create-app-webapp.md) for more information) + + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + Gets collection of TI Indicators. + Get TI Indicators collection API supports [OData V4 queries](https://www.odata.org/documentation/). + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Ti.ReadWrite | 'Read and write TI Indicators' + + +## HTTP request +``` +GET https://api.securitycenter.windows.com/api/tiindicators +``` + +[!include[Improve request performance](improverequestperformance-new.md)] + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200, Ok response code with a collection of [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entities. + +>[!Note] +> The response will only include TI Indicators that submitted by the calling Application. + + +## Example + +**Request** + +Here is an example of a request that gets all TI Indicators + +``` +GET https://api.securitycenter.windows.com/api/tiindicators +``` + +**Response** + +Here is an example of the response. + +``` +HTTP/1.1 200 Ok +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#TiIndicators", + "value": [ + { + "indicator": "12.13.14.15", + "indicatorType": "IpAddress", + "title": "test", + "creationTimeDateTimeUtc": "2018-10-24T11:15:35.3688259Z", + "createdBy": "45097602-1234-5678-1234-9f453233e62c", + "expirationTime": "2020-12-12T00:00:00Z", + "action": "AlertAndBlock", + "severity": "Informational", + "description": "test", + "recommendedActions": "test" + }, + { + "indicator": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", + "indicatorType": "FileSha1", + "title": "test", + "creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z", + "createdBy": "45097602-1234-5678-1234-9f453233e62c", + "expirationTime": "2020-12-12T00:00:00Z", + "action": "AlertAndBlock", + "severity": "Informational", + "description": "test", + "recommendedActions": "TEST" + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..ea4a25eca2 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,85 @@ +--- +title: Get user information API +description: Retrieve a User entity by key such as user name or domain. +keywords: apis, graph api, supported apis, get, user, user information +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get user information API + +[!include[Prerelease information](prerelease.md)] + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +Retrieve a User entity by key (user name or domain\user). + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | User.Read.All | 'Read all user profiles' + +## HTTP request +``` +GET /api/users/{id}/ +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and user exists - 200 OK with [user](user-windows-defender-advanced-threat-protection-new.md) entity in the body. If user does not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/users/user1@contoso.com +Content-type: application/json +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users/$entity", + "id": "user1@contoso.com", + "firstSeen": "2018-08-02T00:00:00Z", + "lastSeen": "2018-08-04T00:00:00Z", + "mostPrevalentMachineId": null, + "leastPrevalentMachineId": null, + "logonTypes": "Network", + "logOnMachinesCount": 3, + "isDomainAdmin": false, + "isOnlyNetworkUser": null +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection.md index c4dfae50e6..86880c519e 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get user information API +# Get user information API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieve a User entity by key (user name or domain\user). diff --git a/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..e109d17851 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,125 @@ +--- +title: Get user related alerts API +description: Retrieves a collection of alerts related to a given user ID. +keywords: apis, graph api, supported apis, get, user, related, alerts +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alert.Read.All | 'Read all alerts' +Application | Alert.ReadWrite.All | 'Read and write all alerts' +Delegated (work or school account) | Alert.Read | 'Read alerts' +Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only alerts, associated with machines, that the user have access to, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/users/{id}/alerts +``` + +**Note that the id is not the Full UPN, its only the user name. For example, for user1@contoso.com you will need to send /api/users/user1/alerts** + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and user and alert exists - 200 OK. If user or alerts does not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/users/user1/alerts +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts", + "value": [ + { + "id": "636688558380765161_2136280442", + "severity": "Informational", + "status": "InProgress", + "description": "Some alert description 1", + "recommendedAction": "Some recommended action 1", + "alertCreationTime": "2018-08-03T01:17:17.9516179Z", + "category": "General", + "title": "Some alert title 1", + "threatFamilyName": null, + "detectionSource": "WindowsDefenderAtp", + "classification": "TruePositive", + "determination": null, + "assignedTo": "best secop ever", + "resolvedTime": null, + "lastEventTime": "2018-08-02T07:02:52.0894451Z", + "firstEventTime": "2018-08-02T07:02:52.0894451Z", + "actorName": null, + "machineId": "ff0c3800ed8d66738a514971cd6867166809369f" + }, + { + "id": "636688558380765161_2136280442", + "severity": "Informational", + "status": "InProgress", + "description": "Some alert description 2", + "recommendedAction": "Some recommended action 2", + "alertCreationTime": "2018-08-04T01:17:17.9516179Z", + "category": "General", + "title": "Some alert title 2", + "threatFamilyName": null, + "detectionSource": "WindowsDefenderAtp", + "classification": "TruePositive", + "determination": null, + "assignedTo": "best secop ever", + "resolvedTime": null, + "lastEventTime": "2018-08-03T07:02:52.0894451Z", + "firstEventTime": "2018-08-03T07:02:52.0894451Z", + "actorName": null, + "machineId": "ff0c3800ed8d66738a514971cd6867166809369d" + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md index aadcc3dd2b..6ea6b78d52 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get user related alerts API +# Get user related alerts API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves a collection of alerts related to a given user ID. diff --git a/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..35a87d200a --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,124 @@ +--- +title: Get user related machines API +description: Retrieves a collection of machines related to a given user ID. +keywords: apis, graph api, supported apis, get, user, user related alerts +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Get 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Read.All | 'Read all machine profiles' +Application | Machine.ReadWrite.All | 'Read and write all machine information' +Delegated (work or school account) | Machine.Read | 'Read machine information' +Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) +>- Response will include only machines that the user can access, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/users/{id}/machines +``` + +**Note that the id is not the Full UPN, its only the user name. For example, for user1@contoso.com you will need to send /api/users/user1/machines** + + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. If user or machines does not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/users/user1/machines +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", + "value": [ + { + "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "computerDnsName": "mymachine1.contoso.com", + "firstSeen": "2018-08-02T14:55:03.7791856Z", + "lastSeen": "2018-08-02T14:55:03.7791856Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "172.17.230.209", + "lastExternalIpAddress": "167.220.196.71", + "agentVersion": "10.5830.18209.1001", + "osBuild": 18209, + "healthStatus": "Active", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 140, + "riskScore": "Low", + "aadDeviceId": null + }, + { + "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7", + "computerDnsName": "mymachine2.contoso.com", + "firstSeen": "2018-07-09T13:22:45.1250071Z", + "lastSeen": "2018-07-09T13:22:45.1250071Z", + "osPlatform": "Windows10", + "osVersion": null, + "systemProductName": null, + "lastIpAddress": "192.168.12.225", + "lastExternalIpAddress": "79.183.65.82", + "agentVersion": "10.5820.17724.1000", + "osBuild": 17724, + "healthStatus": "Inactive", + "isAadJoined": true, + "machineTags": [], + "rbacGroupId": 140, + "riskScore": "Low", + "aadDeviceId": null + } + ] +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection.md index 1b66f1961a..11f719ebd8 100644 --- a/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Get user related machines API +# Get user related machines API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Retrieves a collection of machines related to a given user ID. diff --git a/windows/security/threat-protection/windows-defender-atp/images/atp-azure-new-app.png b/windows/security/threat-protection/windows-defender-atp/images/atp-azure-new-app.png index a4a07d3b92..4449661657 100644 Binary files a/windows/security/threat-protection/windows-defender-atp/images/atp-azure-new-app.png and b/windows/security/threat-protection/windows-defender-atp/images/atp-azure-new-app.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-choose-action.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-choose-action.png new file mode 100644 index 0000000000..867fb4d976 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-choose-action.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-define-action.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-define-action.png new file mode 100644 index 0000000000..51588e0bdc Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-define-action.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-e2e.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-e2e.png new file mode 100644 index 0000000000..f33aa04682 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-e2e.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-insert-db.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-insert-db.png new file mode 100644 index 0000000000..1f15b39220 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-insert-db.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-parse-json.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-parse-json.png new file mode 100644 index 0000000000..b42c9ec193 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-parse-json.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/ms-flow-read-db.png b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-read-db.png new file mode 100644 index 0000000000..89e20f3a67 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/ms-flow-read-db.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/nativeapp-add-permission.png b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-add-permission.png new file mode 100644 index 0000000000..1f7f423e49 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-add-permission.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/nativeapp-add-permissions-end.png b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-add-permissions-end.png new file mode 100644 index 0000000000..eb866e3cce Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-add-permissions-end.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/nativeapp-create.png b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-create.png new file mode 100644 index 0000000000..05d76ec807 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-create.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/nativeapp-decoded-token.png b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-decoded-token.png new file mode 100644 index 0000000000..92f46bf116 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-decoded-token.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/nativeapp-get-appid.png b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-get-appid.png new file mode 100644 index 0000000000..859e4fa8a3 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-get-appid.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/nativeapp-select-permissions.png b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-select-permissions.png new file mode 100644 index 0000000000..2114b14c4d Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/nativeapp-select-permissions.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-create-advanced-query.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-create-advanced-query.png new file mode 100644 index 0000000000..d5fdf37ac2 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-create-advanced-query.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-create-blank-query.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-create-blank-query.png new file mode 100644 index 0000000000..d060becd5b Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-create-blank-query.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-edit-credentials.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-edit-credentials.png new file mode 100644 index 0000000000..62c96acf75 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-edit-credentials.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-edit-data-privacy.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-edit-data-privacy.png new file mode 100644 index 0000000000..7098c8a543 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-edit-data-privacy.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-open-advanced-editor.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-open-advanced-editor.png new file mode 100644 index 0000000000..5c340e3138 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-open-advanced-editor.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-query-results.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-query-results.png new file mode 100644 index 0000000000..b94ee3a009 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-query-results.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-credentials-anonymous.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-credentials-anonymous.png new file mode 100644 index 0000000000..dce1698521 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-credentials-anonymous.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-credentials-organizational-cont.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-credentials-organizational-cont.png new file mode 100644 index 0000000000..049d3ed6ee Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-credentials-organizational-cont.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-credentials-organizational.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-credentials-organizational.png new file mode 100644 index 0000000000..054470d70e Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-credentials-organizational.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-data-privacy.png b/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-data-privacy.png new file mode 100644 index 0000000000..00a8756c43 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/power-bi-set-data-privacy.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-2.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-2.png new file mode 100644 index 0000000000..8123965c84 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-2.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-end.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-end.png new file mode 100644 index 0000000000..40f15eb65a Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission-end.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission.png new file mode 100644 index 0000000000..38e98ce07d Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-add-permission.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-create-key.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-create-key.png new file mode 100644 index 0000000000..4ddb1fae83 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-create-key.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-create.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-create.png new file mode 100644 index 0000000000..a091db0189 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-create.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-decoded-token.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-decoded-token.png new file mode 100644 index 0000000000..be98e49216 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-decoded-token.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-edit-multitenant.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-edit-multitenant.png new file mode 100644 index 0000000000..47203a8151 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-edit-multitenant.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-edit-settings.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-edit-settings.png new file mode 100644 index 0000000000..1b8396b50e Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-edit-settings.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-get-appid.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-get-appid.png new file mode 100644 index 0000000000..103081f82c Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-get-appid.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-grant-permissions.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-grant-permissions.png new file mode 100644 index 0000000000..b7c7e0926f Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-grant-permissions.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-select-permission.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-select-permission.png new file mode 100644 index 0000000000..8edc069eaf Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-select-permission.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/images/webapp-validate-token.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-validate-token.png new file mode 100644 index 0000000000..c813929e31 Binary files /dev/null and b/windows/security/threat-protection/windows-defender-atp/images/webapp-validate-token.png differ diff --git a/windows/security/threat-protection/windows-defender-atp/improverequestperformance-new.md b/windows/security/threat-protection/windows-defender-atp/improverequestperformance-new.md new file mode 100644 index 0000000000..afb2f9bbdd --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/improverequestperformance-new.md @@ -0,0 +1,23 @@ +--- +title: +description: +keywords: +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 04/24/2018 +--- + +# Improve request performance + + +>[!NOTE] +>For better performance, you can use server closer to your geo location: +> - api-us.securitycenter.windows.com +> - api-eu.securitycenter.windows.com +> - api-uk.securitycenter.windows.com \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..066dac83dd --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,80 @@ +--- +title: Is domain seen in org API +description: Use this API to create calls related to checking whether a domain was seen in the organization. +keywords: apis, graph api, supported apis, domain, domain seen +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 04/24/2018 +--- + +# Was domain seen in org +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + +[!include[Prerelease information](prerelease.md)] + +Answers whether a domain was seen in the organization. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Url.Read.All | 'Read URLs' +Delegated (work or school account) | URL.Read.All | 'Read URLs' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/domains/{domain} +``` + +## Request headers + +Header | Value +:---|:--- +Authorization | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and domain exists - 200 OK. If domain does not exist - 404 Not Found. + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +GET https://api.securitycenter.windows.com/api/domains/example.com +Content-type: application/json +``` + +**Response** + +Here is an example of the response. + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Domains/$entity", + "host": "example.com" +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection.md index 892fc60bd3..6dee679614 100644 --- a/windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection.md @@ -14,9 +14,14 @@ ms.localizationpriority: medium ms.date: 04/24/2018 --- -# Is domain seen in org +# Is domain seen in org (deprecated) Answers whether a domain was seen in the organization. +[!include[Deprecated information](deprecate.md)] + + + + ## Permissions User needs read permissions. diff --git a/windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..fc6b531fc1 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,81 @@ +--- +title: Is IP seen in org API +description: Answers whether an IP was seen in the organization. +keywords: apis, graph api, supported apis, is, ip, seen, org, organization +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Was 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 +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Ip.Read.All | 'Read IP address profiles' +Delegated (work or school account) | Ip.Read.All | 'Read IP address profiles' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +GET /api/ips/{ip} +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful and IP exists - 200 OK. If IP do not exist - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +``` +GET https://api.securitycenter.windows.com/api/ips/10.209.67.177 +``` + +**Response** + +Here is an example of the response. + +[!include[Improve request performance](improverequestperformance-new.md)] + + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Ips/$entity", + "id": "10.209.67.177" +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection.md index d006cede0b..42887d7fa8 100644 --- a/windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Is IP seen in org +# Is IP seen in org (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Answers whether an IP was seen in the organization. diff --git a/windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..696d961f94 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,108 @@ +--- +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: medium +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. + +[!include[Machine actions note](machineactionsnote.md)] + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Isolate | 'Isolate machine' +Delegated (work or school account) | Machine.Isolate | 'Isolate machine' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'Active remediation actions' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.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-windows-defender-advanced-threat-protection.md) for more information) + + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/machines/{id}/isolate +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. +Content-Type | string | application/json. **Required**. + +## Request body +In the request body, supply a JSON object with the following parameters: + +Parameter | Type | Description +:---|:---|:--- +Comment | String | Comment to associate with the action. **Required**. +IsolationType | String | Type of the isolation. Allowed values are: 'Full' or 'Selective'. + +**IsolationType** controls the type of isolation to perform and can be one of the following: +- Full – Full isolation +- Selective – Restrict only limited set of applications from accessing the network (see [Isolate machines from the network](respond-machine-alerts-windows-defender-advanced-threat-protection.md#isolate-machines-from-the-network) for more details) + + +## Response +If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/isolate +Content-type: application/json +{ + "Comment": "Isolate machine due to alert 1234", + “IsolationType”: “Full” +} + +``` +**Response** + +Here is an example of the response. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity", + "id": "b89eb834-4578-496c-8be0-03f004061435", + "type": "Isolate", + "requestor": "Analyst@contoso.com ", + "requestorComment": "Isolate machine due to alert 1234", + "status": "InProgress", + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "creationDateTimeUtc": "2017-12-04T12:12:18.9725659Z", + "lastUpdateTimeUtc": "2017-12-04T12:12:18.9725659Z", + "relatedFileInfo": null +} + +``` + +To unisolate a machine, see [Release machine from isolation](unisolate-machine-windows-defender-advanced-threat-protection-new.md). diff --git a/windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection.md index 61cfbb1c6f..c7b6c877d3 100644 --- a/windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Isolate machine API +# Isolate machine API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Isolates a machine from accessing external network. diff --git a/windows/security/threat-protection/windows-defender-atp/machine-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/machine-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..8c70bf4419 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/machine-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,47 @@ +--- +title: Machine resource type +description: Retrieves top machines +keywords: apis, supported apis, get, machines +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 11/11/2018 +--- + +# Machine resource type + + +# Methods +Method|Return Type |Description +:---|:---|:--- +[List machines](get-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | List set of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the org. +[Get machine](get-machine-by-id-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) | Get a [machine](machine-windows-defender-advanced-threat-protection-new.md) by its identity. +[Get logged on users](get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md) | [user](user-windows-defender-advanced-threat-protection-new.md) collection | Get the set of [User](user-windows-defender-advanced-threat-protection-new.md) that logged on to the [machine](machine-windows-defender-advanced-threat-protection-new.md). +[Get related alerts](get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | Get the set of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities that were raised on the [machine](machine-windows-defender-advanced-threat-protection-new.md). +[Add or Remove machine tags](add-or-remove-machine-tags-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) | Add or Remove tag to a specific machine. +[Find machines by IP](find-machines-by-ip-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | Find machines seen with IP. + +# Properties +Property | Type | Description +:---|:---|:--- +id | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) identity. +computerDnsName | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) fully qualified name. +firstSeen | DateTimeOffset | First date and time where the [machine](machine-windows-defender-advanced-threat-protection-new.md) was observed by WDATP. +lastSeen | DateTimeOffset | Last date and time where the [machine](machine-windows-defender-advanced-threat-protection-new.md) was observed by WDATP. +osPlatform | String | OS platform. +osVersion | String | OS Version. +lastIpAddress | Ip | Last IP on local NIC on the [machine](machine-windows-defender-advanced-threat-protection-new.md). +lastExternalIpAddress | Ip | Last IP through which the [machine](machine-windows-defender-advanced-threat-protection-new.md) accessed the internet. +agentVersion | String | Version of WDATP agent. +osBuild | Int | OS build number. +healthStatus | Enum | [machine](machine-windows-defender-advanced-threat-protection-new.md) health status. Possible values are: "Active", "Inactive", "ImpairedCommunication", "NoSensorData" and "NoSensorDataImpairedCommunication" +isAadJoined | Boolean | Is [machine](machine-windows-defender-advanced-threat-protection-new.md) AAD joined. +machineTags | String collection | Set of [machine](machine-windows-defender-advanced-threat-protection-new.md) tags. +rbacGroupId | Int | Group ID. +riskScore | String | Risk score as evaludated by WDATP. Possible values are: 'None', 'Low', 'Medium' and 'High'. +aadDeviceId | String | AAD Device ID (when [machine](machine-windows-defender-advanced-threat-protection-new.md) is Aad Joined). \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/machineaction-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/machineaction-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..6c225819b2 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/machineaction-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,48 @@ +--- +title: machineAction resource type +description: Retrieves top recent machineActions. +keywords: apis, supported apis, get, machineaction, recent +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# MachineAction resource type + +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Method|Return Type |Description +:---|:---|:--- +[List MachineActions](get-machineactions-collection-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | List [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entities. +[Get MachineAction](get-machineaction-object-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Get a single [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity. +[Collect investigation package](collect-investigation-package-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Collect investigation package from a [machine](machine-windows-defender-advanced-threat-protection-new.md). +[Get investigation package SAS URI](get-package-sas-uri-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Get URI for downloading the investigation package. +[Isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Isolate [machine](machine-windows-defender-advanced-threat-protection-new.md) from network. +[Release machine from isolation](unisolate-machine-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Release [machine](machine-windows-defender-advanced-threat-protection-new.md) from Isolation. +[Restrict app execution](restrict-code-execution-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Restrict application execution. +[Remove app restriction](unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Remove application execution restriction. +[Run antivirus scan](run-av-scan-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Run an AV scan using Windows Defender (when applicable). +[Offboard machine](offboard-machine-api-windows-defender-advanced-threat-protection-new.md)|[Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Offboard [machine](machine-windows-defender-advanced-threat-protection-new.md) from WDATP. + +# Properties +Property | Type | Description +:---|:---|:--- +id | Guid | Identity of the [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity. +type | Enum | Type of the action. Possible values are: "RunAntiVirusScan", "Offboard", "CollectInvestigationPackage", "Isolate", "Unisolate", "StopAndQuarantineFile", "RestrictCodeExecution" and "UnrestrictCodeExecution" +requestor | String | Identity of the person that executed the action. +requestorComment | String | Comment that was written when issuing the action. +status | Enum | Current status of the command. Possible values are: "InProgress", "Succeeded", "Failed", "TimeOut" and "Cancelled". +machineId | String | Id of the machine on which the action was executed. +creationDateTimeUtc | DateTimeOffset | The date and time when the action was created. +lastUpdateTimeUtc | DateTimeOffset | The last date and time when the action status was updated. +relatedFileInfo | Class | Contains two Properties. 1) string 'fileIdentifier' 2) Enum 'fileIdentifierType' with the possible values: "Sha1" ,"Sha256" and "Md5". + diff --git a/windows/security/threat-protection/windows-defender-atp/machineactionsnote.md b/windows/security/threat-protection/windows-defender-atp/machineactionsnote.md new file mode 100644 index 0000000000..fcbd68ecec --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/machineactionsnote.md @@ -0,0 +1,6 @@ +--- +ms.date: 08/28/2017 +author: zavidor +--- +>[!Note] +> This page focuses on performing a machine action via API. See [take response actions on a machine](respond-machine-alerts-windows-defender-advanced-threat-protection.md) for more information about response actions functionality via WDATP. diff --git a/windows/security/threat-protection/windows-defender-atp/offboard-machine-api-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/offboard-machine-api-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..0200975d55 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/offboard-machine-api-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,98 @@ +--- +title: Offboard machine API +description: Use this API to offboard a machine from WDATP. +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: medium +ms.date: 12/08/2017 +--- + +# Offboard machine API +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Offboard machine from WDATP. + +[!include[Machine actions note](machineactionsnote.md)] + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Offboard | 'Offboard machine' +Delegated (work or school account) | Machine.Offboard | 'Offboard machine' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to 'Global Admin' AD role +>- The user needs to have access to the machine, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/machines/{id}/offboard +``` + +## 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 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/offboard +Content-type: application/json +{ + "Comment": "Offboard machine by automation" +} +``` + +**Response** + +Here is an example of the response. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity", + "id": "c9042f9b-8483-4526-87b5-35e4c2532223", + "type": "OffboardMachine", + "requestor": "Analyst@contoso.com", + "requestorComment": "offboard machine by automation", + "status": "InProgress", + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "creationDateTimeUtc": "2018-12-04T12:09:24.1785079Z", + "lastUpdateTimeUtc": "2018-12-04T12:09:24.1785079Z", + "relatedFileInfo": null +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/post-ti-indicator-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/post-ti-indicator-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..1a2575ea36 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/post-ti-indicator-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,115 @@ +--- +title: Submit or Update Ti Indicator API +description: Use this API to submit or Update Ti Indicator. +keywords: apis, graph api, supported apis, submit, ti, ti indicator, update +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Submit or Update TI Indicator API + +[!include[Prerelease information](prerelease.md)] + +>[!Note] +> Currently this API is supported only for AppOnly context requests. (See [Get access without a user](exposed-apis-create-app-webapp.md) for more information) + + +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +- Submits or Updates new [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity. + + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Ti.ReadWrite | 'Read and write TI Indicators' + + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/tiindicators +``` + +[!include[Improve request performance](improverequestperformance-new.md)] + + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. +Content-Type | string | application/json. **Required**. + +## Request body +In the request body, supply a JSON object with the following parameters: + +Parameter | Type | Description +:---|:---|:--- +indicator | String | Identity of the [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity. **Required** +indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url". **Required** +action | Enum | The action that will be taken if the indicator will be discovered in the organization. Possible values are: "Alert", "AlertAndBlock", and "Allowed". **Required** +title | String | TI indicator alert title. **Optional** +expirationTime | DateTimeOffset | The expiration time of the indicator. **Optional** +severity | Enum | The severity of the indicator. possible values are: "Informational", "Low", "Medium" and "High". **Optional** +description | String | Description of the indicator. **Optional** +recommendedActions | String | TI indicator alert recommended actions. **Optional** + + +## Response +- If successful, this method returns 200 - OK response code and the created / updated [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity in the response body. +- If not successful: this method return 400 - Bad Request / 409 - Conflict with the failure reason. Bad request usually indicates incorrect body and Conflict can happen if you try to submit a TI Indicator with existing indicator value but with different Indicator type or Action. + +## Example + +**Request** + +Here is an example of the request. + +``` +POST https://api.securitycenter.windows.com/api/tiindicators +Content-type: application/json +{ + "indicator": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", + "indicatorType": "FileSha1", + "title": "test", + "expirationTime": "2020-12-12T00:00:00Z", + "action": "AlertAndBlock", + "severity": "Informational", + "description": "test", + "recommendedActions": "TEST" +} + +``` +**Response** + +Here is an example of the response. + +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity", + "indicator": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", + "indicatorType": "FileSha1", + "title": "test", + "creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z", + "createdBy": "45097602-1234-5678-1234-9f453233e62c", + "expirationTime": "2020-12-12T00:00:00Z", + "action": "AlertAndBlock", + "severity": "Informational", + "description": "test", + "recommendedActions": "TEST" +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/powerbi-reports-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/powerbi-reports-windows-defender-advanced-threat-protection.md index 48c6104eb8..2af3d35376 100644 --- a/windows/security/threat-protection/windows-defender-atp/powerbi-reports-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/powerbi-reports-windows-defender-advanced-threat-protection.md @@ -200,5 +200,10 @@ There are a couple of tabs on the report that's generated: In general, if you know of a specific threat name, CVE, or KB, you can identify machines with unpatched vulnerabilities that might be leveraged by threats. This report also helps you determine whether machine-level mitigations are configured correctly on the machines and prioritize those that might need attention. +## Related topic +- [**Beta** Create custom Power BI reports](run-advanced-query-sample-power-bi-app-token.md) + + + diff --git a/windows/security/threat-protection/windows-defender-atp/request-sample-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/request-sample-windows-defender-advanced-threat-protection.md index 8c0f6851d1..94706ede5a 100644 --- a/windows/security/threat-protection/windows-defender-atp/request-sample-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/request-sample-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Request sample API +# Request sample API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Request sample of a file from a specific machine. File will be collected from the machine and uploaded to a secure storage. diff --git a/windows/security/threat-protection/windows-defender-atp/respond-machine-alerts-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/respond-machine-alerts-windows-defender-advanced-threat-protection.md index cdc3c156e4..3ad2b9c1a8 100644 --- a/windows/security/threat-protection/windows-defender-atp/respond-machine-alerts-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/respond-machine-alerts-windows-defender-advanced-threat-protection.md @@ -182,7 +182,7 @@ Depending on the severity of the attack and the sensitivity of the machine, you This machine isolation feature disconnects the compromised machine from the network while retaining connectivity to the Windows Defender ATP service, which continues to monitor the machine. -On Windows 10, version 1709 or later, you'll have additional control over the network isolation level. You can also choose to enable Outlook and Skype for Business connectivity. +On Windows 10, version 1709 or later, you'll have additional control over the network isolation level. You can also choose to enable Outlook and Skype for Business connectivity (a.k.a 'Selective Isolation'). >[!NOTE] >You’ll be able to reconnect the machine back to the network at any time. @@ -198,7 +198,7 @@ On Windows 10, version 1709 or later, you'll have additional control over the ne ![Image of isolate machine](images/atp-actions-isolate-machine.png) -3. Select the check-box if you'd like to enable Outlook and Skype communication while the machine is isolated. +3. Select the check-box if you'd like to enable Outlook and Skype communication while the machine is isolated (a.k.a. 'Selective Isolation'). ![Image of isolation confirmation](images/atp-confirm-isolate.png) diff --git a/windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..d57876fdc0 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,101 @@ +--- +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: medium +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 all applications on the machine except a predefined set (see [Response machine alerts](respond-machine-alerts-windows-defender-advanced-threat-protection.md) for more information) + +[!include[Machine actions note](machineactionsnote.md)] + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.RestrictExecution | 'Restrict code execution' +Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code execution' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'Active remediation actions' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.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-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/machines/{id}/restrictCodeExecution +``` + +## 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 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body. + + +## Example + +**Request** + +Here is an example of the request. + +``` +POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/restrictCodeExecution +Content-type: application/json +{ + "Comment": "Restrict code execution due to alert 1234" +} + +``` +**Response** + +Here is an example of the response. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$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", + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "creationDateTimeUtc": "2018-12-04T12:15:04.3825985Z", + "lastUpdateTimeUtc": "2018-12-04T12:15:04.3825985Z", + "relatedFileInfo": null +} + +``` + +To remove code execution restriction from a machine, see [Remove app restriction](unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md). + diff --git a/windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection.md index 3eb57786f8..1722b1f921 100644 --- a/windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection.md @@ -14,12 +14,12 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Restrict app execution API +# Restrict app execution API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Restrict execution of set of predefined applications. diff --git a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-api.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-api.md new file mode 100644 index 0000000000..8decfce57c --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-api.md @@ -0,0 +1,151 @@ +--- +title: Advanced Hunting API +description: Use this API to run advanced queries +keywords: apis, supported apis, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 09/03/2018 +--- + +# Advanced hunting API +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + +[!include[Prerelease information](prerelease.md)] + + + +This API allows you to run programmatic queries that you are used to running from [Windows Defender ATP Portal](https://securitycenter.windows.com/hunting). + + +## Limitations +This API is a beta version only and is currently restricted to the following actions: +1. ​You can only run a query on data from the last 30 days +2. The results will include a maximum of 10,000 rows +3. The number of executions is limited​ (up to 15 calls per minute, 15 minutes of running time every hour and 4 hours of running time a day) + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | AdvancedQuery.Read.All | 'Run advanced queries' +Delegated (work or school account) | AdvancedQuery.Read | 'Run advanced queries' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have 'Global Admin' AD role (note: will be updated soon to 'View Data') +>- The user needs to have access to the machine, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/advancedqueries/run +``` + +## 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 +:---|:---|:--- +Query | Text | The query to run. **Required**. + +## Response +If successful, this method returns 200 OK, and _QueryResponse_ object in the response body. + + +## Example + +Request + +Here is an example of the request. + +>[!NOTE] +>For better performance, you can use server closer to your geo location: +> - api-us.securitycenter.windows.com +> - api-eu.securitycenter.windows.com +> - api-uk.securitycenter.windows.com + +``` +POST https://api.securitycenter.windows.com/api/advancedqueries/run +Content-type: application/json +{ + "Query":"ProcessCreationEvents +| where InitiatingProcessFileName =~ \"powershell.exe\" +| where ProcessCommandLine contains \"appdata\" +| project EventTime, FileName, InitiatingProcessFileName +| limit 2" +} +``` + +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 200 OK +Content-Type: application/json​ +{ + "Schema": [{ + "Name": "EventTime", + "Type": "DateTime" + }, + { + "Name": "FileName", + "Type": "String" + }, + { + "Name": "InitiatingProcessFileName", + "Type": "String" + }], + "Results": [{ + "EventTime": "2018-07-09T07:16:26.8017265", + "FileName": "csc.exe", + "InitiatingProcessFileName": "powershell.exe" + }, + { + "EventTime": "2018-07-08T19:00:02.7798905", + "FileName": "gpresult.exe", + "InitiatingProcessFileName": "powershell.exe" + }] +} + + +``` + +## T​roubl​eshoot issues + +- Error: (403) Forbidden + + + If you get this error when calling Windows Defender ATP API, your token might not include the necessary permission. + + Check [app permissions](exposed-apis-create-app-webapp.md#validate-the-token) or [delegated permissions](exposed-apis-create-app-nativeapp.md#validate-the-token) included in your token. + + If the 'roles' section in the token does not include the necessary permission: + + - The necessary permission to your app might not have been granted. For more information, see [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md#create-an-app) or [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md#create-an-app) or, + - The app was not authorized in the tenant, see [Application consent](exposed-apis-create-app-webapp.md#application-consent). + + +## Related topic +- [Windows Defender ATP APIs](apis-intro.md) +- [Advanced Hunting from Portal](advanced-hunting-windows-defender-advanced-threat-protection.md) +- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) +- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md) diff --git a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-ms-flow.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-ms-flow.md new file mode 100644 index 0000000000..d5e16fbf5a --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-ms-flow.md @@ -0,0 +1,88 @@ +--- +title: Advanced Hunting API +description: Use this API to run advanced queries +keywords: apis, supported apis, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 09/24/2018 +--- + +# Schedule Advanced Hunting using Microsoft Flow +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Schedule advanced query. + +## Before you begin +You first need to [create an app](apis-intro.md). + +## Use case + +A common scenario is scheduling an advanced query and using the results for follow up actions and processing. +In this section we share sample for this purpose using [Microsoft Flow](https://flow.microsoft.com/) (or [Logic Apps](https://azure.microsoft.com/en-us/services/logic-apps/)). + +## Define a flow to run query and parse results + +Use the following basic flow as an example. + +1. Define the trigger – Recurrence by time. + +2. Add an action: Select HTTP. + + ![Image of MsFlow choose an action](images/ms-flow-choose-action.png) + + - Set method to be POST + - Uri is https://api.securitycenter.windows.com/api/advancedqueries/run or one of the region specific locations + - US: https://api-us.securitycenter.windows.com/api/advancedqueries/run + - Europe: https://api-eu.securitycenter.windows.com/api/advancedqueries/run + - United Kingdom: https://api-uk.securitycenter.windows.com/api/advancedqueries/run + - Add the Header: Content-Type application/json + - In the body write your query surrounded by single quotation mark (') + - In the Advanced options select Authentication to be Active Directory OAuth + - Set the Tenant with proper AAD Tenant Id + - Audience is https://api.securitycenter.windows.com + - Client ID is your application ID + - Credential Type should be Secret + - Secret is the application secret generated in the Azure Active directory. + + ![Image of MsFlow define action](images/ms-flow-define-action.png) + +3. You can use the "Parse JSON" action to get the schema of data – just "use sample payload to generate schema" and copy an output from of the expected result. + + ![Image of MsFlow parse json](images/ms-flow-parse-json.png) + +## Expand the flow to use the query results + +The following section shows how to use the parsed results to insert them in SQL database. + +This is an example only, you can use other actions supported by Microsoft Flow. + +- Add an 'Apply to each' action +- Select the Results json (which was an output of the last parse action) +- Add an 'Insert row' action – you will need to supply the connection details +- Select the table you want to update and define the mapping between the WD-ATP output to the SQL. Note it is possible to manipulate the data inside the flow. In the example I changed the type of the EventTime. + +![Image of insert into DB](images/ms-flow-insert-db.png) + +The output in the SQL DB is getting updates and can be used for correlation with other data sources. You can now read from your table: + +![Image of select from DB](images/ms-flow-read-db.png) + +## Full flow definition + +You can find below the full definition + +![Image of E2E flow](images/ms-flow-e2e.png) + +## Related topic +- [Windows Defender ATP APIs](apis-intro.md) +- [Advanced Hunting API](run-advanced-query-api.md) +- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-app-token.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-app-token.md new file mode 100644 index 0000000000..ce6ccb012c --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-app-token.md @@ -0,0 +1,134 @@ +--- +title: Advanced Hunting API +description: Use this API to run advanced queries +keywords: apis, supported apis, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 30/07/2018 +--- + +# Create custom reports using Power BI (app authentication) + +Run advanced queries and show results in Microsoft Power BI. Please read about [Advanced Hunting API](run-advanced-query-api.md) before. + +In this section we share Power BI query sample to run a query using **application token**. + +If you want to use **user token** instead please refer to [this](run-advanced-query-sample-power-bi-user-token.md) tutorial. + +>**Prerequisite**: You first need to [create an app](exposed-apis-create-app-webapp.md). + +## Run a query + +- Open Microsoft Power BI + +- Click **Get Data** > **Blank Query** + + ![Image of create blank query](images/power-bi-create-blank-query.png) + +- Click **Advanced Editor** + + ![Image of open advanced editor](images/power-bi-open-advanced-editor.png) + +- Copy the below and paste it in the editor, after you update the values of TenantId, AppId, AppSecret, Query + + ``` + let + + TenantId = "00000000-0000-0000-0000-000000000000", // Paste your own tenant ID here + AppId = "11111111-1111-1111-1111-111111111111", // Paste your own app ID here + AppSecret = "22222222-2222-2222-2222-222222222222", // Paste your own app secret here + Query = "MachineInfo | where EventTime > ago(7d) | summarize EventCount=count(), LastSeen=max(EventTime) by MachineId", // Paste your own query here + + ResourceAppIdUrl = "https://api.securitycenter.windows.com", + OAuthUrl = Text.Combine({"https://login.windows.net/", TenantId, "/oauth2/token"}, ""), + + Resource = Text.Combine({"resource", Uri.EscapeDataString(ResourceAppIdUrl)}, "="), + ClientId = Text.Combine({"client_id", AppId}, "="), + ClientSecret = Text.Combine({"client_secret", Uri.EscapeDataString(AppSecret)}, "="), + GrantType = Text.Combine({"grant_type", "client_credentials"}, "="), + + Body = Text.Combine({Resource, ClientId, ClientSecret, GrantType}, "&"), + + AuthResponse= Json.Document(Web.Contents(OAuthUrl, [Content=Text.ToBinary(Body)])), + AccessToken= AuthResponse[access_token], + Bearer = Text.Combine({"Bearer", AccessToken}, " "), + + AdvancedHuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries/run", + + Response = Json.Document(Web.Contents( + AdvancedHuntingUrl, + [ + Headers = [#"Content-Type"="application/json", #"Accept"="application/json", #"Authorization"=Bearer], + Content=Json.FromValue([#"Query"=Query]) + ] + )), + + TypeMap = #table( + { "Type", "PowerBiType" }, + { + { "Double", Double.Type }, + { "Int64", Int64.Type }, + { "Int32", Int32.Type }, + { "Int16", Int16.Type }, + { "UInt64", Number.Type }, + { "UInt32", Number.Type }, + { "UInt16", Number.Type }, + { "Byte", Byte.Type }, + { "Single", Single.Type }, + { "Decimal", Decimal.Type }, + { "TimeSpan", Duration.Type }, + { "DateTime", DateTimeZone.Type }, + { "String", Text.Type }, + { "Boolean", Logical.Type }, + { "SByte", Logical.Type }, + { "Guid", Text.Type } + }), + + Schema = Table.FromRecords(Response[Schema]), + TypedSchema = Table.Join(Table.SelectColumns(Schema, {"Name", "Type"}), {"Type"}, TypeMap , {"Type"}), + Results = Response[Results], + Rows = Table.FromRecords(Results, Schema[Name]), + Table = Table.TransformColumnTypes(Rows, Table.ToList(TypedSchema, (c) => {c{0}, c{2}})) + + in Table + + ``` + +- Click **Done** + + ![Image of create advanced query](images/power-bi-create-advanced-query.png) + +- Click **Edit Credentials** + + ![Image of edit credentials](images/power-bi-edit-credentials.png) + +- Select **Anonymous** and click **Connect** + + ![Image of set credentials](images/power-bi-set-credentials-anonymous.png) + +- Repeat the previous step for the second URL + +- Click **Continue** + + ![Image of edit data privacy](images/power-bi-edit-data-privacy.png) + +- Select the privacy level you want and click **Save** + + ![Image of set data privacy](images/power-bi-set-data-privacy.png) + +- View the results of your query + + ![Image of query results](images/power-bi-query-results.png) + +## Related topic +- [Create custom Power BI reports with user authentication](run-advanced-query-sample-power-bi-user-token.md) +- [Windows Defender ATP APIs](apis-intro.md) +- [Advanced Hunting API](run-advanced-query-api.md) +- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) +- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md) diff --git a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-user-token.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-user-token.md new file mode 100644 index 0000000000..b065578d98 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi-user-token.md @@ -0,0 +1,115 @@ +--- +title: Advanced Hunting API +description: Use this API to run advanced queries +keywords: apis, supported apis, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 30/07/2018 +--- + +# Create custom reports using Power BI (user authentication) +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + + +Run advanced queries and show results in Microsoft Power BI. Please read about [Advanced Hunting API](run-advanced-query-api.md) before. + +In this section we share Power BI query sample to run a query using **user token**. + +If you want to use **application token** instead please refer to [this](run-advanced-query-sample-power-bi-app-token.md) tutorial. + +## Before you begin +You first need to [create an app](exposed-apis-create-app-nativeapp.md). + +## Run a query + +- Open Microsoft Power BI + +- Click **Get Data** > **Blank Query** + + ![Image of create blank query](images/power-bi-create-blank-query.png) + +- Click **Advanced Editor** + + ![Image of open advanced editor](images/power-bi-open-advanced-editor.png) + +- Copy the below and paste it in the editor, after you update the values of Query + + ``` + let + + Query = "MachineInfo | where EventTime > ago(7d) | summarize EventCount=count(), LastSeen=max(EventTime) by MachineId", + + FormattedQuery= Uri.EscapeDataString(Query), + + AdvancedHuntingUrl = "https://api.securitycenter.windows.com/api/advancedqueries?key=" & FormattedQuery, + + Response = Json.Document(Web.Contents(AdvancedHuntingUrl)), + + TypeMap = #table( + { "Type", "PowerBiType" }, + { + { "Double", Double.Type }, + { "Int64", Int64.Type }, + { "Int32", Int32.Type }, + { "Int16", Int16.Type }, + { "UInt64", Number.Type }, + { "UInt32", Number.Type }, + { "UInt16", Number.Type }, + { "Byte", Byte.Type }, + { "Single", Single.Type }, + { "Decimal", Decimal.Type }, + { "TimeSpan", Duration.Type }, + { "DateTime", DateTimeZone.Type }, + { "String", Text.Type }, + { "Boolean", Logical.Type }, + { "SByte", Logical.Type }, + { "Guid", Text.Type } + }), + + Schema = Table.FromRecords(Response[Schema]), + TypedSchema = Table.Join(Table.SelectColumns(Schema, {"Name", "Type"}), {"Type"}, TypeMap , {"Type"}), + Results = Response[Results], + Rows = Table.FromRecords(Results, Schema[Name]), + Table = Table.TransformColumnTypes(Rows, Table.ToList(TypedSchema, (c) => {c{0}, c{2}})) + + in Table + + ``` + +- Click **Done** + + ![Image of create advanced query](images/power-bi-create-advanced-query.png) + +- Click **Edit Credentials** + + ![Image of edit credentials](images/power-bi-edit-credentials.png) + +- Select **Organizational account** > **Sign in** + + ![Image of set credentials](images/power-bi-set-credentials-organizational.png) + +- Enter your credentials and wait to be signed in + +- Click **Connect** + + ![Image of set credentials](images/power-bi-set-credentials-organizational-cont.png) + +- View the results of your query + + ![Image of query results](images/power-bi-query-results.png) + +## Related topic +- [Create custom Power BI reports with app authentication](run-advanced-query-sample-power-bi-app-token.md) +- [Windows Defender ATP APIs](apis-intro.md) +- [Advanced Hunting API](run-advanced-query-api.md) +- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) +- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md) diff --git a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-powershell.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-powershell.md new file mode 100644 index 0000000000..76fa741ab6 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-powershell.md @@ -0,0 +1,119 @@ +--- +title: Advanced Hunting API +description: Use this API to run advanced queries +keywords: apis, supported apis, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 09/24/2018 +--- + +# Advanced Hunting using PowerShell +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + + +Run advanced queries using PowerShell, see [Advanced Hunting API](run-advanced-query-api.md). + +In this section we share PowerShell samples to retrieve a token and use it to run a query. + +## Before you begin +You first need to [create an app](apis-intro.md). + +## Preparation instructions + +- Open a PowerShell window. +- If your policy does not allow you to run the PowerShell commands, you can run the below command: +``` +Set-ExecutionPolicy -ExecutionPolicy Bypass +``` + +>For more details, see [PowerShell documentation](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) + +## Get token + +- Run the following: + +``` +$tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here +$appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here +$appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here + +$resourceAppIdUri = 'https://api.securitycenter.windows.com' +$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token" +$body = [Ordered] @{ + resource = "$resourceAppIdUri" + client_id = "$appId" + client_secret = "$appSecret" + grant_type = 'client_credentials' +} +$response = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $body -ErrorAction Stop +$aadToken = $response.access_token + +``` + +where +- $tenantId: ID of the tenant on behalf of which you want to run the query (i.e., the query will be run on the data of this tenant) +- $appId: ID of your AAD app (the app must have 'Run advanced queries' permission to WDATP) +- $appSecret: Secret of your AAD app + +## Run query + +Run the following query: + +``` +$query = 'RegistryEvents | limit 10' # Paste your own query here + +$url = "https://api.securitycenter.windows.com/api/advancedqueries/run" +$headers = @{ + 'Content-Type' = 'application/json' + Accept = 'application/json' + Authorization = "Bearer $aadToken" +} +$body = ConvertTo-Json -InputObject @{ 'Query' = $query } +$webResponse = Invoke-WebRequest -Method Post -Uri $url -Headers $headers -Body $body -ErrorAction Stop +$response = $webResponse | ConvertFrom-Json +$results = $response.Results +$schema = $response.Schema +``` + +- $results contains the results of your query +- $schema contains the schema of the results of your query + +### Complex queries + +If you want to run complex queries (or multilines queries), save your query in a file and, instead of the first line in the above sample, run the below command: + +``` +$query = [IO.File]::ReadAllText("C:\myQuery.txt"); # Replace with the path to your file +``` + +## Work with query results + +You can now use the query results. + +To output the results of the query in CSV format in file file1.csv do the below: + +``` +$results | ConvertTo-Csv -NoTypeInformation | Set-Content file1.csv +``` + +To output the results of the query in JSON format in file file1.json​ do the below: + +``` +$results | ConvertTo-Json | Set-Content file1.json +``` + + +## Related topic +- [Windows Defender ATP APIs](apis-intro.md) +- [Advanced Hunting API](run-advanced-query-api.md) +- [Advanced Hunting using Python](run-advanced-query-sample-python.md) +- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md) diff --git a/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-python.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-python.md new file mode 100644 index 0000000000..71784d6ccd --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-python.md @@ -0,0 +1,146 @@ +--- +title: Advanced Hunting API +description: Use this API to run advanced queries +keywords: apis, supported apis, advanced hunting, query +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 30/07/2018 +--- + +# Advanced Hunting using Python +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Run advanced queries using Python, see [Advanced Hunting API](run-advanced-query-api.md). + +In this section we share Python samples to retrieve a token and use it to run a query. + +>**Prerequisite**: You first need to [create an app](apis-intro.md). + +## Get token + +- Run the following: + +``` + +import json +import urllib.request +import urllib.parse + +tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here +appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here +appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here + +url = "https://login.windows.net/%s/oauth2/token" % (tenantId) + +resourceAppIdUri = 'https://api.securitycenter.windows.com' + +body = { + 'resource' : resourceAppIdUri, + 'client_id' : appId, + 'client_secret' : appSecret, + 'grant_type' : 'client_credentials' +} + +data = urllib.parse.urlencode(body).encode("utf-8") + +req = urllib.request.Request(url, data) +response = urllib.request.urlopen(req) +jsonResponse = json.loads(response.read()) +aadToken = jsonResponse["access_token"] + +``` + +where +- tenantId: ID of the tenant on behalf of which you want to run the query (i.e., the query will be run on the data of this tenant) +- appId: ID of your AAD app (the app must have 'Run advanced queries' permission to WDATP) +- appSecret: Secret of your AAD app + +## Run query + + Run the following query: + +``` +query = 'RegistryEvents | limit 10' # Paste your own query here + +url = "https://api.securitycenter.windows.com/api/advancedqueries/run" +headers = { + 'Content-Type' : 'application/json', + 'Accept' : 'application/json', + 'Authorization' : "Bearer " + aadToken +} + +data = json.dumps({ 'Query' : query }).encode("utf-8") + +req = urllib.request.Request(url, data, headers) +response = urllib.request.urlopen(req) +jsonResponse = json.loads(response.read()) +schema = jsonResponse["Schema"] +results = jsonResponse["Results"] + +``` + +- schema contains the schema of the results of your query +- results contains the results of your query + +### Complex queries + +If you want to run complex queries (or multilines queries), save your query in a file and, instead of the first line in the above sample, run the below command: + +``` +queryFile = open("D:\\Temp\\myQuery.txt", 'r') # Replace with the path to your file +query = queryFile.read() +queryFile.close() +``` + +## Work with query results + +You can now use the query results. + +To iterate over the results do the below: + +``` +for result in results: + print(result) # Prints the whole result + print(result["EventTime"]) # Prints only the property 'EventTime' from the result + + +``` + + +To output the results of the query in CSV format in file file1.csv do the below: + +``` +import csv + +outputFile = open("D:\\Temp\\file1.csv", 'w') +output = csv.writer(outputFile) +output.writerow(results[0].keys()) +for result in results: + output.writerow(result.values()) + +outputFile.close() +``` + +To output the results of the query in JSON format in file file1.json​ do the below: + +``` +outputFile = open("D:\\Temp\\file1.json", 'w') +json.dump(results, outputFile) +outputFile.close() +``` + + +## Related topic +- [Windows Defender ATP APIs](apis-intro.md) +- [Advanced Hunting API](run-advanced-query-api.md) +- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md) +- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md) diff --git a/windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..c9ae44eb2b --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,107 @@ +--- +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: medium +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 a machine. + +[!include[Machine actions note](machineactionsnote.md)] + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Scan | 'Scan machine' +Delegated (work or school account) | Machine.Scan | 'Scan machine' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'Active remediation actions' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.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-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/machines/{id}/runAntiVirusScan +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. +Content-Type | string | 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| String | Defines the type of the Scan. **Required**. + +**ScanType** controls the type of scan 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://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runAntiVirusScan +Content-type: application/json +{ + "Comment": "Check machine for viruses due to alert 3212", + “ScanType”: “Full” +} +``` + +**Response** + +Here is an example of the response. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$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", + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z", + "lastUpdateTimeUtc": "2018-12-04T12:18:27.1293487Z", + "relatedFileInfo": null +} + +``` diff --git a/windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection.md index 73333ff005..40d0e7da3f 100644 --- a/windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection.md @@ -14,12 +14,12 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Run antivirus scan API +# Run antivirus scan API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Initiate Windows Defender Antivirus scan on the machine. diff --git a/windows/security/threat-protection/windows-defender-atp/stop-quarantine-file-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/stop-quarantine-file-windows-defender-advanced-threat-protection.md index 06af6fc6af..078ced8e48 100644 --- a/windows/security/threat-protection/windows-defender-atp/stop-quarantine-file-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/stop-quarantine-file-windows-defender-advanced-threat-protection.md @@ -14,12 +14,12 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Stop and quarantine file API +# Stop and quarantine file API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Stop execution of a file on a machine and ensure it’s not executed again on that machine. diff --git a/windows/security/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md index e5bb46bc1d..aff0ccd147 100644 --- a/windows/security/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/supported-apis-windows-defender-advanced-threat-protection.md @@ -14,15 +14,14 @@ ms.localizationpriority: medium ms.date: 09/03/2018 --- -# Supported Windows Defender ATP query APIs +# Supported Windows Defender ATP query APIs (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) +[!include[Deprecated information](deprecate.md)] ->Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-supportedapis-abovefoldlink) - Learn more about the individual supported entities where you can run API calls to and details such as HTTP request values, request headers and expected responses. ## In this section @@ -38,5 +37,4 @@ User | Run API calls such as get alert related user information, user informatio KbInfo | Run API call that gets list of Windows KB's information CveKbMap | Run API call that gets mapping of CVE's to corresponding KB's MachineSecurityStates | Run API call that gets list of machines with their security properties and versions -MachineGroups | Run API call that gets list of machine group definitions - +MachineGroups | Run API call that gets list of machine group definitions \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/ti-indicator-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/ti-indicator-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..d8693cd298 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/ti-indicator-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,45 @@ +--- +title: TiIndicator resource type +description: TiIndicator entity description. +keywords: apis, supported apis, get, TiIndicator, recent +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# TI(threat intelligence) Indicator resource type + +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Method|Return Type |Description +:---|:---|:--- +[List TI Indicators](get-ti-indicators-collection-windows-defender-advanced-threat-protection-new.md) | [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) Collection | List [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entities. +[Get TI Indicator by ID](get-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md) | [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) | Gets the requested [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity. +[Submit TI Indicator](post-ti-indicator-windows-defender-advanced-threat-protection-new.md) | [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) | Submits [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity. +[Delete TI Indicator](delete-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md) | No Content | Deletes [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity. + + +# Properties +Property | Type | Description +:---|:---|:--- +indicator | String | Identity of the [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity. +indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url" +title | String | Ti indicator alert title. +creationTimeDateTimeUtc | DateTimeOffset | The date and time when the indicator was created. +createdBy | String | Identity of the user/application that submitted the indicator. +expirationTime | DateTimeOffset | The expiration time of the indicator +action | Enum | The action that will be taken if the indicator will be discovered in the organization. Possible values are: "Alert", "AlertAndBlock", and "Allowed" +severity | Enum | The severity of the indicator. possible values are: "Informational", "Low", "Medium" and "High" +description | String | Description of the indicator. +recommendedActions | String | TI indicator alert recommended actions. + + diff --git a/windows/security/threat-protection/windows-defender-atp/unblock-file-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/unblock-file-windows-defender-advanced-threat-protection.md index fffb9ad229..ad824d3ab2 100644 --- a/windows/security/threat-protection/windows-defender-atp/unblock-file-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/unblock-file-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Unblock file API +# Unblock file API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Allow a file to be executed in the organization, using Windows Defender Antivirus. diff --git a/windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..0b654aa63c --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,105 @@ +--- +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: medium +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. + +[!include[Machine actions note](machineactionsnote.md)] + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.Isolate | 'Isolate machine' +Delegated (work or school account) | Machine.Isolate | 'Isolate machine' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'Active remediation actions' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.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-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/machines/{id}/unisolate +``` + +## 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 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/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://api.securitycenter.windows.com/api/$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", + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "creationDateTimeUtc": "2018-12-04T12:13:15.0104931Z", + "lastUpdateTimeUtc": "2018-12-04T12:13:15.0104931Z", + "relatedFileInfo": null +} + +``` + +To isolate a machine, see [Isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md). + diff --git a/windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection.md index 560416bc51..8898ab6189 100644 --- a/windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Release machine from isolation API +# Release machine from isolation API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Undo isolation of a machine. diff --git a/windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..8ca7430854 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,100 @@ +--- +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: medium +ms.date: 12/08/2017 +--- + +# Remove app restriction API +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +[!include[Prerelease information](prerelease.md)] + +Enable execution of any application on the machine. + +[!include[Machine actions note](machineactionsnote.md)] + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Machine.RestrictExecution | 'Restrict code execution' +Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code execution' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'Active remediation actions' (See [Create and manage roles](user-roles-windows-defender-advanced-threat-protection.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-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +POST https://api.securitycenter.windows.com/api/machines/{id}/unrestrictCodeExecution +``` + +## 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 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/unrestrictCodeExecution +Content-type: application/json +{ + "Comment": "Unrestrict code execution since machine was cleaned and validated" +} + +``` + +**Response** + +Here is an example of the response. + +``` +HTTP/1.1 201 Created +Content-type: application/json +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$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", + "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", + "creationDateTimeUtc": "2018-12-04T12:15:40.6052029Z", + "lastUpdateTimeUtc": "2018-12-04T12:15:40.6052029Z", + "relatedFileInfo": null +} + +``` + +To restrict code execution on a machine, see [Restrict app execution](restrict-code-execution-windows-defender-advanced-threat-protection-new.md). \ No newline at end of file diff --git a/windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection.md index 10def5a55d..e011fa5800 100644 --- a/windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection.md +++ b/windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection.md @@ -14,13 +14,13 @@ ms.localizationpriority: medium ms.date: 12/08/2017 --- -# Remove app restriction API +# Remove app restriction API (deprecated) **Applies to:** - [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf) - +[!include[Deprecated information](deprecate.md)] Unrestrict execution of set of predefined applications. diff --git a/windows/security/threat-protection/windows-defender-atp/update-alert-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/update-alert-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..1ce73605cf --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/update-alert-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,108 @@ +--- +title: Get alert information by ID API +description: Retrieves an alert by its ID. +keywords: apis, graph api, supported apis, get, alert, information, id +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# Update alert +**Applies to:** + +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + + +[!include[Prerelease information](prerelease.md)] +Update the properties of an alert entity. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alerts.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-windows-defender-advanced-threat-protection.md) for more information) +>- The user needs to have access to the machine associated with the alert, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information) + +## HTTP request +``` +PATCH /api/alerts/{id} +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. +Content-Type | String | application/json. **Required**. + + +## Request body +In the request body, supply the values for the relevant fields that should be updated.Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. For best performance you shouldn't include existing values that haven't change. + +Property | Type | Description +:---|:---|:--- +status | String | Specifies the current status of the alert. The property values are: 'New', 'InProgress' and 'Resolved'. +assignedTo | String | Owner of the alert +classification | String | Specifies the specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'. +determination | String | Specifies the determination of the alert. The property values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other' + + +## Response +If successful, this method returns 200 OK, and the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entity in the response body with the updated properties. If alert with the specified id was not found - 404 Not Found. + + +## Example + +**Request** + +Here is an example of the request. + +[!include[Improve request performance](improverequestperformance-new.md)] + +``` +PATCH https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442 +Content-Type: application/json +{ + "assignedTo": "Our designated secop" +} +``` + +**Response** + +Here is an example of the response. + +``` +{ + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts/$entity", + "id": "636688558380765161_2136280442", + "severity": "Medium", + "status": "InProgress", + "description": "An anomalous memory operation appears to be tampering with a process associated with the Windows Defender EDR sensor.", + "recommendedAction": "A. Validate the alert.\n1. Examine the process involved in the memory operation to determine whether the process and the observed activities are normal. \n2. Check for other suspicious activities in the machine timeline.\n3. Locate unfamiliar processes in the process tree. Check files for prevalence, their locations, and digital signatures.\n4. Submit relevant files for deep analysis and review file behaviors. \n5. Identify unusual system activity with system owners. \n\nB. Scope the incident. Find related machines, network addresses, and files in the incident graph. \n\nC. Contain and mitigate the breach. Stop suspicious processes, isolate affected machines, decommission compromised accounts or reset passwords, block IP addresses and URLs, and install security updates.\n\nD. Contact your incident response team, or contact Microsoft support for investigation and remediation services.", + "alertCreationTime": "2018-08-07T10:18:04.2665329Z", + "category": "Installation", + "title": "Possible sensor tampering in memory", + "threatFamilyName": null, + "detectionSource": "WindowsDefenderAtp", + "classification": null, + "determination": null, + "assignedTo": "Our designated secop", + "resolvedTime": null, + "lastEventTime": "2018-08-07T10:14:35.470671Z", + "firstEventTime": "2018-08-07T10:14:35.470671Z", + "actorName": null, + "machineId": "a2250e1cd215af1ea2818ef8d01a564f67542857" +} +``` diff --git a/windows/security/threat-protection/windows-defender-atp/use-apis.md b/windows/security/threat-protection/windows-defender-atp/use-apis.md new file mode 100644 index 0000000000..0232e57b31 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/use-apis.md @@ -0,0 +1,26 @@ +--- +title: Use the Windows Defender Advanced Threat Protection APIs +description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph. +keywords: 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: medium +ms.date: 10/23/2017 +--- + +# Use the Windows Defender ATP exposed APIs + +**Applies to:** +- Windows Defender Advanced Threat Protection (Windows Defender ATP) + +## In this section +Topic | Description +:---|:--- +Create your app | Learn how to create an application to get programmatical access to Windows Defender ATP on behalf of a user or without a user. +Supported Windows Defender ATP APIs | Learn more about the individual supported entities where you can run API calls to and details such as HTTP request values, request headers and expected responses. +How to use APIs - Samples | Learn how to use Advanced hunting APIs and multiple APIs such as PowerShell. diff --git a/windows/security/threat-protection/windows-defender-atp/user-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/user-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..509ded9db9 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/user-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,23 @@ +--- +title: File resource type +description: Retrieves top recent alerts. +keywords: apis, graph api, supported apis, get, alerts, recent +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +ms.date: 12/08/2017 +--- + +# User resource type + +Method|Return Type |Description +:---|:---|:--- +[List User related alerts](get-user-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | List all the alerts that are associated with a [user](user-windows-defender-advanced-threat-protection-new.md). +[List User related machines](get-user-related-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | List all the machines that were logged on by a [user](user-windows-defender-advanced-threat-protection-new.md). + + diff --git a/windows/security/threat-protection/windows-defender-exploit-guard/requirements-and-deployment-planning-guidelines-for-virtualization-based-protection-of-code-integrity.md b/windows/security/threat-protection/windows-defender-exploit-guard/requirements-and-deployment-planning-guidelines-for-virtualization-based-protection-of-code-integrity.md index 1eb3ac9b72..640fe4cc29 100644 --- a/windows/security/threat-protection/windows-defender-exploit-guard/requirements-and-deployment-planning-guidelines-for-virtualization-based-protection-of-code-integrity.md +++ b/windows/security/threat-protection/windows-defender-exploit-guard/requirements-and-deployment-planning-guidelines-for-virtualization-based-protection-of-code-integrity.md @@ -33,9 +33,9 @@ The following tables provide more information about the hardware, firmware, and |--------------------------------|----------------------------------------------------|-------------------| | Hardware: **64-bit CPU** | A 64-bit computer is required for the Windows hypervisor to provide VBS. | | | Hardware: **CPU virtualization extensions**,
plus **extended page tables** | These hardware features are required for VBS:
One of the following virtualization extensions:
• VT-x (Intel) or
• AMD-V
And:
• Extended page tables, also called Second Level Address Translation (SLAT). | VBS provides isolation of the secure kernel from the normal operating system. Vulnerabilities and zero-days in the normal operating system cannot be exploited because of this isolation. | -| Firmware: **UEFI firmware version 2.3.1.c or higher with UEFI Secure Boot** | See the following Windows Hardware Compatibility Program requirement: [System.Fundamentals.Firmware.UEFISecureBoot](https://docs.microsoft.com/windows-hardware/design/compatibility/systems#systemfundamentalsfirmwareuefisecureboot) | UEFI Secure Boot helps ensure that the device boots only authorized code. This can prevent boot kits and root kits from installing and persisting across reboots. | -| Firmware: **Secure firmware update process** | UEFI firmware must support secure firmware update found under the following Windows Hardware Compatibility Program requirement: [System.Fundamentals.Firmware.UEFISecureBoot](https://docs.microsoft.com/windows-hardware/design/compatibility/systems#systemfundamentalsfirmwareuefisecureboot) | UEFI firmware just like software can have security vulnerabilities that, when found, need to be patched through firmware updates. Patching helps prevent root kits from getting installed. | -| Software: **HVCI compatible drivers** | See the Windows Hardware Compatibility Program requirements under [Filter.Driver.DeviceGuard.DriverCompatibility](https://docs.microsoft.com/windows-hardware/design/compatibility/filter#filterdriverdeviceguarddrivercompatibility).| [HVCI Compatible](https://blogs.msdn.microsoft.com/windows_hardware_certification/2015/05/22/driver-compatibility-with-device-guard-in-windows-10/) drivers help ensure that VBS can maintain appropriate memory permissions. This increases resistance to bypassing vulnerable kernel drivers and helps ensure that malware cannot run in kernel. Only code verified through code integrity can run in kernel mode. | +| Firmware: **UEFI firmware version 2.3.1.c or higher with UEFI Secure Boot** | See the System.Fundamentals.Firmware.UEFISecureBoot requirement in the [Windows Hardware Compatibility Specifications for Windows 10, version 1809 and Windows Server 2019 - Systems download](https://go.microsoft.com/fwlink/?linkid=2027110). You can find previous versions of the Windows Hardware Compatibility Program Specifications and Policies [here](https://docs.microsoft.com/en-us/windows-hardware/design/compatibility/whcp-specifications-policies). | UEFI Secure Boot helps ensure that the device boots only authorized code. This can prevent boot kits and root kits from installing and persisting across reboots. | +| Firmware: **Secure firmware update process** | UEFI firmware must support secure firmware update found under the System.Fundamentals.Firmware.UEFISecureBoot requirement in the [Windows Hardware Compatibility Specifications for Windows 10, version 1809 and Windows Server 2019 - Systems download](https://go.microsoft.com/fwlink/?linkid=2027110). You can find previous versions of the Windows Hardware Compatibility Program Specifications and Policies [here](https://docs.microsoft.com/en-us/windows-hardware/design/compatibility/whcp-specifications-policies). | UEFI firmware just like software can have security vulnerabilities that, when found, need to be patched through firmware updates. Patching helps prevent root kits from getting installed. | +| Software: **HVCI compatible drivers** | See the Filter.Driver.DeviceGuard.DriverCompatibility requirement in the [Windows Hardware Compatibility Specifications for Windows 10, version 1809 and Windows Server 2019 - Filter driver download](https://go.microsoft.com/fwlink/?linkid=2027110). You can find previous versions of the Windows Hardware Compatibility Program Specifications and Policies [here](https://docs.microsoft.com/en-us/windows-hardware/design/compatibility/whcp-specifications-policies). | [HVCI Compatible](https://blogs.msdn.microsoft.com/windows_hardware_certification/2015/05/22/driver-compatibility-with-device-guard-in-windows-10/) drivers help ensure that VBS can maintain appropriate memory permissions. This increases resistance to bypassing vulnerable kernel drivers and helps ensure that malware cannot run in kernel. Only code verified through code integrity can run in kernel mode. | | Software: Qualified **Windows operating system** | Windows 10 Enterprise, Windows 10 Education, Windows Server 2016, or Windows 10 IoT Enterprise

Important:
Windows Server 2016 running as a domain controller does not support Windows Defender Credential Guard. Only virtualization-based protection of code integrity is supported in this configuration.

| Support for VBS and for management features that simplify configuration of Windows Defender Device Guard. | > **Important**  The following tables list additional qualifications for improved security. You can use Windows Defender Device Guard with hardware, firmware, and software that support baseline protections, even if they do not support protections for improved security. However, we strongly recommend meeting these additional qualifications to significantly strengthen the level of security that Windows Defender Device Guard can provide. @@ -58,7 +58,7 @@ The following tables describe additional hardware and firmware qualifications, a | Protections for Improved Security | Description | Security benefits | |---------------------------------------------|----------------------------------------------------|-----| -| Firmware: **Hardware Rooted Trust Platform Secure Boot** | • Boot Integrity (Platform Secure Boot) must be supported. See the Windows Hardware Compatibility Program requirements under [System.Fundamentals.Firmware.CS.UEFISecureBoot.ConnectedStandby](https://docs.microsoft.com/windows-hardware/design/compatibility/systems#systemfundamentalsfirmwarecsuefisecurebootconnectedstandby)
• The Hardware Security Test Interface (HSTI) 1.1.a must be implemented. See [Hardware Security Testability Specification](https://docs.microsoft.com/windows-hardware/test/hlk/testref/hardware-security-testability-specification). | • Boot Integrity (Platform Secure Boot) from Power-On provides protections against physically present attackers, and defense-in-depth against malware.
• HSTI 1.1.a provides additional security assurance for correctly secured silicon and platform. | +| Firmware: **Hardware Rooted Trust Platform Secure Boot** | • Boot Integrity (Platform Secure Boot) must be supported. See the System.Fundamentals.Firmware.CS.UEFISecureBoot.ConnectedStandby requirement in the [Windows Hardware Compatibility Specifications for Windows 10, version 1809 and Windows Server 2019 - Systems download](https://go.microsoft.com/fwlink/?linkid=2027110). You can find previous versions of the Windows Hardware Compatibility Program Specifications and Policies [here](https://docs.microsoft.com/en-us/windows-hardware/design/compatibility/whcp-specifications-policies).
• The Hardware Security Test Interface (HSTI) 1.1.a must be implemented. See [Hardware Security Testability Specification](https://docs.microsoft.com/windows-hardware/test/hlk/testref/hardware-security-testability-specification). | • Boot Integrity (Platform Secure Boot) from Power-On provides protections against physically present attackers, and defense-in-depth against malware.
• HSTI 1.1.a provides additional security assurance for correctly secured silicon and platform. | | Firmware: **Firmware Update through Windows Update** | Firmware must support field updates through Windows Update and UEFI encapsulation update. | Helps ensure that firmware updates are fast, secure, and reliable. | | Firmware: **Securing Boot Configuration and Management** | • Required BIOS capabilities: Ability of OEM to add ISV, OEM, or Enterprise Certificate in Secure Boot DB at manufacturing time.
• Required configurations: Microsoft UEFI CA must be removed from Secure Boot DB. Support for 3rd-party UEFI modules is permitted but should leverage ISV-provided certificates or OEM certificate for the specific UEFI software.| • Enterprises can choose to allow proprietary EFI drivers/applications to run.
• Removing Microsoft UEFI CA from Secure Boot DB provides full control to enterprises over software that runs before the operating system boots. |