diff --git a/windows/security/threat-protection/windows-defender-atp/TOC.md b/windows/security/threat-protection/windows-defender-atp/TOC.md index fa8be23611..1111f8ad04 100644 --- a/windows/security/threat-protection/windows-defender-atp/TOC.md +++ b/windows/security/threat-protection/windows-defender-atp/TOC.md @@ -95,6 +95,12 @@ #### [Python code examples](python-example-code-windows-defender-advanced-threat-protection.md) #### [Experiment with custom threat intelligence alerts](experiment-custom-ti-windows-defender-advanced-threat-protection.md) #### [Troubleshoot custom threat intelligence issues](troubleshoot-custom-ti-windows-defender-advanced-threat-protection.md) + +### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection-new.md) +#### Supported Windows Defender ATP APIs +##### [Advanced Hunting](run-advanced-query-windows-defender-advanced-threat-protection) + + ### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md) #### [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection.md) #####Actor diff --git a/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection-new.md b/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection-new.md new file mode 100644 index 0000000000..26c7a3be1c --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection-new.md @@ -0,0 +1,96 @@ +--- +title: Use the Windows Defender Advanced Threat Protection exposed 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: 10/23/2017 +--- + +# Use the Windows Defender ATP exposed APIs + +**Applies to:** + +- Windows 10 Enterprise +- Windows 10 Education +- Windows 10 Pro +- Windows 10 Pro Education +- 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) + +Windows Defender ATP exposes much of the available data and actions using 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 Windows Defender ATP API + +### Before you begin +Before using the APIs, you’ll need to create an app that you’ll use to authenticate against the graph. You’ll need to create a web app to use for the adhoc queries. + +## 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) + +In order to send telemetry events to WDATP, check 'Write timeline events' permission +In order to send TI events to WDATP, check 'Read and write IOCs belonging to the app' permission +In order to run advanced queries in WDATP, check 'Run advanced queries' permission + +7. Click **Done** + + ![Image of add permissions completion](images/webapp-add-permission-end.png) + +8. Click **Keys** and type a key name and click **Save**. +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) + +9. Write down your application ID. + + ![Image of app ID](images/webapp-get-appid.png) + +9. (**Optional**)Set your application to be multi-tenanted + +This is required for 3rd party apps (i.e., 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 (i.e., 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) + + 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..24e449a94c 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..e0fb6d5cb8 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..4b955fc3c0 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..2784135cc4 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..3d61af07e9 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-edit-multitenant.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-edit-multitenant.png new file mode 100644 index 0000000000..83ce5da068 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..d18950bfd1 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-select-permission.png b/windows/security/threat-protection/windows-defender-atp/images/webapp-select-permission.png new file mode 100644 index 0000000000..7f5fb81063 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/run-advanced-query-windows-defender-advanced-threat-protection.md b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection.md new file mode 100644 index 0000000000..b71d2fe199 --- /dev/null +++ b/windows/security/threat-protection/windows-defender-atp/run-advanced-query-windows-defender-advanced-threat-protection.md @@ -0,0 +1,106 @@ +--- +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) + + + +Run advanced query. + +## Permissions +Application needs 'Run advanced queries' role. + +## HTTP request +``` +POST /advancedqueries/query +``` + +## 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. + +``` +POST https://api.securitycenter.windows.com/advancedqueries/query +Content-type: application/json +{ + "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" + }] +} + + +```