mirror of
https://github.com/MicrosoftDocs/windows-itpro-docs.git
synced 2025-05-19 00:37:22 +00:00
Merge branch 'atp-api-danm' of https://cpubwin.visualstudio.com/_git/it-client into atp-api-danm
This commit is contained in:
Joey Caparas
commit
02b507d206
@ -157,6 +157,7 @@
|
||||
##### [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.md)
|
||||
|
||||
|
||||
### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -31,6 +31,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Machine.CollectForensics | 'Collect forensics'
|
||||
Delegated (work or school account) | Machine.CollectForensics | 'Collect forensics'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,6 +30,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -41,6 +41,11 @@ In general, you’ll need to take the following steps to use the APIs:
|
||||
|
||||
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 WDATP 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 WDATP, please refer to [Manage portal access using role-based access control](rbac-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
**Rule of thumb for user permissions:** 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).
|
||||
@ -51,16 +56,16 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
3. In the Create window, enter the following information then click **Create**.
|
||||
|
||||
|
||||
|
||||
|
||||
- **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.)
|
||||
- **Name:** -Your app name-
|
||||
- **Application type:** Native
|
||||
- **Redirect URI:** `https://127.0.0.1`
|
||||
|
||||
|
||||
4. Click **Settings** > **Required permissions** > **Add**.
|
||||
|
||||
|
||||
|
||||
|
||||
5. Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
|
||||
|
||||
@ -68,54 +73,35 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
|
||||
|
||||
6. Click **Select permissions** > **Run advanced queries** > **Select**.
|
||||
6. Click **Select permissions** > check **Read alerts** & **Collect forensics** > **Select**.
|
||||
|
||||
**Important note**: You need to select the relevant permission. 'Run advanced queries' is only an example!
|
||||
**Important note**: You need to select the relevant permissions. 'Read alerts' and 'Collect forensics' are only an example!
|
||||
|
||||
|
||||
|
||||
|
||||
For instance,
|
||||
|
||||
- In order to [run advanced queries](run-advanced-query-api.md), check 'Run advanced queries' permission
|
||||
- In order to [isolate a machine](isolate-machine-windows-defender-advanced-threat-protection-new.md), check 'Isolate machine' permission
|
||||
|
||||
To determine which permission you need, please look at the **Permissions** section in the API you are interested to call.
|
||||
|
||||
- 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**
|
||||
|
||||
|
||||
|
||||
|
||||
8. Click **Keys** and type a key name and click **Save**.
|
||||
8. Click **Grant permissions**
|
||||
|
||||
**Important**: After you save, **copy the key value**. You won't be able to retrieve after you leave!
|
||||
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.
|
||||
|
||||
|
||||
|
||||
9. Write down your application ID.
|
||||
|
||||
|
||||
|
||||
9. 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**.
|
||||
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
@ -134,57 +120,52 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co
|
||||
using Microsoft.IdentityModel.Clients.ActiveDirectory;
|
||||
```
|
||||
|
||||
- Copy/Paste the below code in your application (do not forget to update the 3 variables: ```tenantId, appId, appSecret```)
|
||||
- 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 appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here
|
||||
|
||||
const string aadUri = "https://login.windows.net";
|
||||
const string wdatpResourceId = "https://securitycenter.onmicrosoft.com/windowsatpservice";
|
||||
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!
|
||||
|
||||
AuthenticationContext auth = new AuthenticationContext($"{aadUri}/{tenantId}/");
|
||||
ClientCredential clientCredential = new ClientCredential(appId, appSecret);
|
||||
AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
|
||||
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;
|
||||
```
|
||||
|
||||
### 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 <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
|
||||
```
|
||||
|
||||
## Validate the token
|
||||
|
||||
- Copy/paste into [JWT](https://jwt.io/) the token you get in the previous step
|
||||
- Validate you get a 'roles' claim with the desired permission, as shown in the below screenshot
|
||||
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:
|
||||
|
||||
|
||||
|
||||
|
||||
## 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](exposed-apis-intro.md)
|
||||
|
||||
@ -74,25 +74,36 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
|
||||
|
||||
- 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
|
||||
For instance,
|
||||
|
||||
- In order to [run advanced queries](run-advanced-query-api.md), check 'Run advanced queries' permission
|
||||
- In order to [isolate a machine](isolate-machine-windows-defender-advanced-threat-protection-new.md), check '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**
|
||||
|
||||
|
||||
|
||||
8. Click **Keys** and type a key name and click **Save**.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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!
|
||||
|
||||
|
||||
|
||||
9. Write down your application ID.
|
||||
10. Write down your application ID.
|
||||
|
||||
|
||||
|
||||
9. Set your application to be multi-tenanted
|
||||
11. 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).
|
||||
|
||||
@ -103,13 +114,13 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
|
||||
|
||||
## Application consent
|
||||
**Note**:
|
||||
|
||||
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 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.
|
||||
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:
|
||||
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
|
||||
@ -139,12 +150,12 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co
|
||||
```
|
||||
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
|
||||
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 aadUri = "https://login.windows.net";
|
||||
const string wdatpResourceId = "https://securitycenter.onmicrosoft.com/windowsatpservice";
|
||||
const string authority = "https://login.windows.net";
|
||||
const string wdatpResourceId = "https://api.securitycenter.windows.com/";
|
||||
|
||||
AuthenticationContext auth = new AuthenticationContext($"{aadUri}/{tenantId}/");
|
||||
AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
|
||||
ClientCredential clientCredential = new ClientCredential(appId, appSecret);
|
||||
AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
|
||||
string token = authenticationResult.AccessToken;
|
||||
@ -181,11 +192,31 @@ You will get an answer of the form:
|
||||
|
||||
## Validate the token
|
||||
|
||||
- Copy/paste into [JWT](https://jwt.io/) the token you get in the previous step
|
||||
- Validate you get a 'roles' claim with the desired permission, as shown in the below screenshot
|
||||
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:
|
||||
|
||||
|
||||
|
||||
|
||||
## 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](exposed-apis-intro.md)
|
||||
- [Supported Windows Defender ATP APIs](exposed-apis-list.md)
|
||||
|
||||
@ -31,6 +31,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,6 +30,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | URL.Read.All | 'Read URLs'
|
||||
Delegated (work or school account) | URL.Read.All | 'Read URLs'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,6 +30,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | File.Read.All | 'Read file profiles'
|
||||
Delegated (work or school account) | File.Read.All | 'Read file profiles'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -31,6 +31,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,8 +30,10 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Machine.Read.All | 'Read all machine profiles'
|
||||
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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -31,6 +31,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | User.Read.All | 'Read user profiles'
|
||||
Delegated (work or school account) | User.Read.All | 'Read user profiles'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -33,6 +33,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -32,6 +32,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -32,6 +32,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,7 +30,8 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | URL.Read.All | 'Read all machine profiles'
|
||||
Application | URL.Read.All | 'Read URLs'
|
||||
Delegated (work or school account) | URL.Read.All | 'Read URLs'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -32,6 +32,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -32,6 +32,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -32,6 +32,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -31,6 +31,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | File.Read.All | 'Read file profiles'
|
||||
Delegated (work or school account) | File.Read.All | 'Read file profiles'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -32,6 +32,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,6 +30,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,7 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | User.Read.All | 'Read user profiles'
|
||||
|
||||
Delegated (work or school account) | User.Read.All | 'Read user profiles'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,6 +30,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,6 +30,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,6 +30,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Machine.CollectForensics | 'Collect forensics'
|
||||
Delegated (work or school account) | Machine.CollectForensics | 'Collect forensics'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,6 +30,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -30,6 +30,8 @@ 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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 9.9 KiB |
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Url.Read.All | 'Read URLs'
|
||||
Delegated (work or school account) | URL.Read.All | 'Read URLs'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Machine.Isolate | 'Isolate machine'
|
||||
Delegated (work or school account) | Machine.Isolate | 'Isolate machine'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Machine.Offboard | 'Offboard machine'
|
||||
Delegated (work or school account) | Machine.Offboard | 'Offboard machine'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -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.md)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Machine.RestrictExecution | 'Restrict code execution'
|
||||
Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code execution'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -36,6 +36,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | AdvancedQuery.Read.All | 'Run advanced queries'
|
||||
Delegated (work or school account) | AdvancedQuery.Read | 'Run advanced queries'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -0,0 +1,131 @@
|
||||
---
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md).
|
||||
|
||||
## Run a query
|
||||
|
||||
- Open Microsoft Power BI
|
||||
|
||||
- Click **Get Data** > **Blank Query**
|
||||
|
||||
|
||||
|
||||
- Click **Advanced Editor**
|
||||
|
||||
|
||||
|
||||
- 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://securitycenter.onmicrosoft.com/windowsatpservice",
|
||||
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/advancedqueries/query",
|
||||
|
||||
Response = Json.Document(Web.Contents(
|
||||
AdvancedHuntingUrl,
|
||||
[
|
||||
Headers = [#"Content-Type"="application/json", #"Accept"="application/json", #"Authorization"=Bearer],
|
||||
Content=Json.FromValue(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**
|
||||
|
||||
|
||||
|
||||
- Click **Edit Credentials**
|
||||
|
||||
|
||||
|
||||
- Select **Anonymous** and click **Connect**
|
||||
|
||||
|
||||
|
||||
- Repeat the previous step for the second URL
|
||||
|
||||
- Click **Continue**
|
||||
|
||||
|
||||
|
||||
- Select the privacy level you want and click **Save**
|
||||
|
||||
|
||||
|
||||
- View the results of your query
|
||||
|
||||
|
||||
|
||||
## Related topic
|
||||
- [Windows Defender ATP APIs](exposed-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)
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Machine.Scan | 'Scan machine'
|
||||
Delegated (work or school account) | Machine.Scan | 'Scan machine'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Machine.Isolate | 'Isolate machine'
|
||||
Delegated (work or school account) | Machine.Isolate | 'Isolate machine'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Machine.RestrictExecution | 'Restrict code execution'
|
||||
Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code execution'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
|
||||
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'
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user