mirror of
https://github.com/MicrosoftDocs/windows-itpro-docs.git
synced 2025-05-14 14:27:22 +00:00
Merged PR 14806: 3/14 AM Publish
This commit is contained in:
Huaping Yu (Beyondsoft Consulting Inc)
commit
42df55b13c
@ -235,11 +235,13 @@
|
||||
###### [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)
|
||||
##### [Windows Defender ATP API](windows-defender-atp/use-apis.md)
|
||||
###### [Get started](windows-defender-atp/apis-intro.md)
|
||||
####### [Hello World](windows-defender-atp/api-hello-world.md)
|
||||
####### [Get access with application context](windows-defender-atp/exposed-apis-create-app-webapp.md)
|
||||
####### [Get access with user context](windows-defender-atp/exposed-apis-create-app-nativeapp.md)
|
||||
###### [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)
|
||||
@ -253,6 +255,33 @@
|
||||
######## [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)
|
||||
|
||||
####### [Machine](windows-defender-atp/machine-windows-defender-advanced-threat-protection-new.md)
|
||||
######## [List 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 Machine Actions](windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md)
|
||||
######## [Get Machine Action](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)
|
||||
######## [Stop and quarantine file](windows-defender-atp/stop-and-quarantine-file-windows-defender-advanced-threat-protection-new.md)
|
||||
######## [Initiate investigation (preview)](windows-defender-atp/initiate-autoir-investigation-windows-defender-advanced-threat-protection-new.md)
|
||||
|
||||
####### [Indicators (preview)](windows-defender-atp/ti-indicator-windows-defender-advanced-threat-protection-new.md)
|
||||
######## [Submit Indicator](windows-defender-atp/post-ti-indicator-windows-defender-advanced-threat-protection-new.md)
|
||||
######## [List Indicators](windows-defender-atp/get-ti-indicators-collection-windows-defender-advanced-threat-protection-new.md)
|
||||
######## [Delete Indicator](windows-defender-atp/delete-ti-indicator-by-id-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)
|
||||
@ -271,28 +300,6 @@
|
||||
######## [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)
|
||||
######## [List 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 Machine Actions](windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md)
|
||||
######## [Get Machine Action](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)
|
||||
######## [Stop and quarantine file](windows-defender-atp/stop-and-quarantine-file-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)
|
||||
@ -329,8 +336,8 @@
|
||||
###### [Enable SIEM integration](windows-defender-atp/enable-siem-integration-windows-defender-advanced-threat-protection.md)
|
||||
###### [Configure Splunk to pull alerts](windows-defender-atp/configure-splunk-windows-defender-advanced-threat-protection.md)
|
||||
###### [Configure HP ArcSight to pull alerts](windows-defender-atp/configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
###### [Windows Defender ATP alert API fields](windows-defender-atp/api-portal-mapping-windows-defender-advanced-threat-protection.md)
|
||||
###### [Pull alerts using REST API](windows-defender-atp/pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
###### [Windows Defender ATP SIEM alert API fields](windows-defender-atp/api-portal-mapping-windows-defender-advanced-threat-protection.md)
|
||||
###### [Pull alerts using SIEM REST API](windows-defender-atp/pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
###### [Troubleshoot SIEM tool integration issues](windows-defender-atp/troubleshoot-siem-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
|
||||
|
||||
@ -232,11 +232,13 @@
|
||||
###### [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)
|
||||
#### [Windows Defender ATP API](use-apis.md)
|
||||
##### [Get started](apis-intro.md)
|
||||
###### [Hello World](api-hello-world.md)
|
||||
###### [Get access with application context](exposed-apis-create-app-webapp.md)
|
||||
###### [Get access with user context](exposed-apis-create-app-nativeapp.md)
|
||||
##### [APIs](exposed-apis-list.md)
|
||||
|
||||
###### [Advanced Hunting](run-advanced-query-api.md)
|
||||
|
||||
###### [Alert](alerts-windows-defender-advanced-threat-protection-new.md)
|
||||
@ -250,24 +252,6 @@
|
||||
####### [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)
|
||||
####### [List 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)
|
||||
@ -288,6 +272,30 @@
|
||||
####### [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)
|
||||
####### [Stop and quarantine file](stop-and-quarantine-file-windows-defender-advanced-threat-protection-new.md)
|
||||
####### [Initiate investigation (preview)](initiate-autoir-investigation-windows-defender-advanced-threat-protection-new.md)
|
||||
|
||||
###### [Indicators (preview)](ti-indicator-windows-defender-advanced-threat-protection-new.md)
|
||||
####### [Submit Indicator](post-ti-indicator-windows-defender-advanced-threat-protection-new.md)
|
||||
####### [List Indicators](get-ti-indicators-collection-windows-defender-advanced-threat-protection-new.md)
|
||||
####### [Delete Indicator](delete-ti-indicator-by-id-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)
|
||||
|
||||
###### [User](user-windows-defender-advanced-threat-protection-new.md)
|
||||
####### [Get user related alerts](get-user-related-alerts-windows-defender-advanced-threat-protection-new.md)
|
||||
@ -318,8 +326,8 @@
|
||||
##### [Enable SIEM integration](enable-siem-integration-windows-defender-advanced-threat-protection.md)
|
||||
##### [Configure Splunk to pull alerts](configure-splunk-windows-defender-advanced-threat-protection.md)
|
||||
##### [Configure HP ArcSight to pull alerts](configure-arcsight-windows-defender-advanced-threat-protection.md)
|
||||
##### [Windows Defender ATP alert API fields](api-portal-mapping-windows-defender-advanced-threat-protection.md)
|
||||
##### [Pull alerts using REST API](pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
##### [Windows Defender ATP SIEM alert API fields](api-portal-mapping-windows-defender-advanced-threat-protection.md)
|
||||
##### [Pull alerts using SIEM REST API](pull-alerts-using-rest-api-windows-defender-advanced-threat-protection.md)
|
||||
##### [Troubleshoot SIEM tool integration issues](troubleshoot-siem-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
|
||||
|
||||
@ -104,7 +104,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2" ]
|
||||
}
|
||||
|
||||
@ -0,0 +1,190 @@
|
||||
---
|
||||
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
|
||||
manager: dansimp
|
||||
audience: ITPro
|
||||
ms.collection: M365-security-compliance
|
||||
ms.topic: article
|
||||
ms.date: 09/24/2018
|
||||
---
|
||||
|
||||
# Windows Defender ATP API - Hello Word
|
||||
|
||||
**Applies to:** [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf)
|
||||
|
||||
> 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)
|
||||
|
||||
|
||||
## Get Alerts using a simple PowerShell script
|
||||
|
||||
### How long it takes to go through this example?
|
||||
It only takes 5 minutes done in two steps:
|
||||
- Application registration
|
||||
- Use examples: only requires copy/paste of a short PowerShell script
|
||||
|
||||
### Do I need a permission to connect?
|
||||
For the App registration stage, you must have a Global administrator role in your Azure Active Directory (Azure AD) tenant.
|
||||
|
||||
### Step 1 - Create an App in Azure Active Directory
|
||||
|
||||
1. Log on to [Azure](https://portal.azure.com) With your Global administrator user.
|
||||
|
||||
2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**.
|
||||
|
||||
|
||||
|
||||
3. In the registration form, enter the following information, then click **Create**.
|
||||
|
||||
- **Name:** Choose your own name.
|
||||
- **Application type:** Web app / API
|
||||
- **Redirect URI:** `https://127.0.0.1`
|
||||
|
||||
|
||||
|
||||
4. Allow your App to access Windows Defender ATP and assign it 'Read all alerts' permission:
|
||||
|
||||
- Click **Settings** > **Required permissions** > **Add**.
|
||||
|
||||
|
||||
|
||||
- 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.
|
||||
|
||||
|
||||
|
||||
- Click **Select permissions** > **Read all alerts** > **Select**.
|
||||
|
||||
|
||||
|
||||
- Click **Done**
|
||||
|
||||
|
||||
|
||||
- Click **Grant permissions**
|
||||
|
||||
**Note**: Every time you add permission you must click on **Grant permissions**.
|
||||
|
||||
|
||||
|
||||
5. Create a key for your App:
|
||||
|
||||
- Click **Keys**, type a key name and click **Save**.
|
||||
|
||||
|
||||
|
||||
6. Write down your App ID and your Tenant ID:
|
||||
|
||||
- App ID:
|
||||
|
||||
|
||||
|
||||
- Tenant ID: Navigate to **Azure Active Directory** > **Properties**
|
||||
|
||||
|
||||
|
||||
|
||||
Done! You have successfully registered an application!
|
||||
|
||||
### Step 2 - Get a token using the App and use this token to access the API.
|
||||
|
||||
- Copy the script below to PowerShell ISE or to a text editor, and save it as "**Get-Token.ps1**"
|
||||
- Running this script will generate a token and will save it in the working folder under the name "**Latest-token.txt**".
|
||||
|
||||
```
|
||||
# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
|
||||
# Paste below your Tenant ID, App ID and App Secret (App key).
|
||||
|
||||
$tenantId = '' ### Paste your tenant ID here
|
||||
$appId = '' ### Paste your app ID here
|
||||
$appSecret = '' ### Paste your app key here
|
||||
|
||||
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
|
||||
$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
|
||||
$token = $authResponse.access_token
|
||||
Out-File -FilePath "./Latest-token.txt" -InputObject $token
|
||||
return $token
|
||||
|
||||
```
|
||||
|
||||
- Sanity Check:<br>
|
||||
Run the script.<br>
|
||||
In your browser go to: https://jwt.ms/ <br>
|
||||
Copy the token (the content of the Latest-token.txt file).<br>
|
||||
Paste in the top box.<br>
|
||||
Look for the "roles" section. Find the Alert.Read.All role.
|
||||
|
||||
|
||||
|
||||
### Lets get the Alerts!
|
||||
|
||||
- The script below will use **Get-Token.ps1** to access the API and will get the past 48 hours Alerts.
|
||||
- Save this script in the same folder you saved the previous script **Get-Token.ps1**.
|
||||
- The script creates two files (json and csv) with the data in the same folder as the scripts.
|
||||
|
||||
```
|
||||
# Returns Alerts created in the past 48 hours.
|
||||
|
||||
$token = ./Get-Token.ps1 #run the script Get-Token.ps1 - make sure you are running this script from the same folder of Get-Token.ps1
|
||||
|
||||
# Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
|
||||
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
|
||||
|
||||
# The URL contains the type of query and the time filter we create above
|
||||
# Read more about other query options and filters at Https://TBD- add the documentation link
|
||||
$url = "https://api.securitycenter.windows.com/api/alerts?`$filter=alertCreationTime ge $dateTime"
|
||||
|
||||
# Set the WebRequest headers
|
||||
$headers = @{
|
||||
'Content-Type' = 'application/json'
|
||||
Accept = 'application/json'
|
||||
Authorization = "Bearer $token"
|
||||
}
|
||||
|
||||
# Send the webrequest and get the results.
|
||||
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
|
||||
|
||||
# Extract the alerts from the results.
|
||||
$alerts = ($response | ConvertFrom-Json).value | ConvertTo-Json
|
||||
|
||||
# Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
|
||||
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
|
||||
|
||||
# Save the result as json and as csv
|
||||
$outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
|
||||
$outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"
|
||||
|
||||
Out-File -FilePath $outputJsonPath -InputObject $alerts
|
||||
($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation
|
||||
|
||||
```
|
||||
|
||||
You’re all done! You have just successfully:
|
||||
- Created and registered and application
|
||||
- Granted permission for that application to read alerts
|
||||
- Connected the API
|
||||
- Used a PowerShell script to return alerts created in the past 48 hours
|
||||
|
||||
Well done!
|
||||
|
||||
|
||||
## Related topic
|
||||
- [Windows Defender ATP APIs](exposed-apis-list.md)
|
||||
- [Access Windows Defender ATP with application context](exposed-apis-create-app-webapp.md)
|
||||
- [Access Windows Defender ATP with user context](exposed-apis-create-app-nativeapp.md)
|
||||
@ -18,7 +18,7 @@ ms.topic: article
|
||||
ms.date: 10/16/2017
|
||||
---
|
||||
|
||||
# Windows Defender ATP alert API fields
|
||||
# Windows Defender ATP SIEM alert API fields
|
||||
|
||||
**Applies to:**
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
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
|
||||
keywords: apis, api, wdatp, open api, windows defender atp api, public api, supported apis, alerts, machine, user, domain, ip, file, advanced hunting, query
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
ms.mktglfcycl: deploy
|
||||
@ -19,43 +19,46 @@ ms.date: 09/03/2018
|
||||
|
||||
# Windows Defender ATP API overview
|
||||
|
||||
**Applies to:**
|
||||
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||
**Applies to:** [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf)
|
||||
|
||||
|
||||
>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)]
|
||||
> 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 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
|
||||
- Create an AAD application
|
||||
- Get an access token using this application
|
||||
- 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.
|
||||
You can access Windows Defender ATP API with **Application Context** or **User Context**.
|
||||
|
||||
## Delegated permissions, application permissions, and effective permissions
|
||||
- **Application Context: (Recommended)** <br>
|
||||
Used by apps that run without a signed-in user present. for example, apps that run as background services or daemons.
|
||||
|
||||
Windows Defender ATP has two types of permissions: delegated permissions and application permissions.
|
||||
Steps that needs to be taken to access Windows Defender ATP API with application context:
|
||||
1) Create AAD Web-Application.
|
||||
2) Assign the desired permission to the application, e.g 'Read Alerts', 'Isolate Machines' etc.
|
||||
3) Create a key for this Application.
|
||||
4) Get token using the application with its key.
|
||||
5) Use the token to access Windows Defender ATP API
|
||||
|
||||
- **Delegated permissions** <br>
|
||||
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** <br>
|
||||
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.
|
||||
See - [Get access with application context](exposed-apis-create-app-webapp.md).
|
||||
|
||||
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).
|
||||
- **User Context:** <br>
|
||||
Used to perform actions in the API on behalf of a user.
|
||||
|
||||
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.
|
||||
Steps that needs to be taken to access Windows Defender ATP API with application context:
|
||||
1) Create AAD Native-Application.
|
||||
2) Assign the desired permission to the application, e.g 'Read Alerts', 'Isolate Machines' etc.
|
||||
3) Get token using the application with user credentials.
|
||||
4) Use the token to access Windows Defender ATP API
|
||||
|
||||
- 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.
|
||||
See - [Get access with user context](exposed-apis-create-app-nativeapp.md).
|
||||
|
||||
|
||||
## 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)
|
||||
- [Windows Defender ATP APIs](exposed-apis-list.md)
|
||||
- [Access Windows Defender ATP with application context](exposed-apis-create-app-webapp.md)
|
||||
- [Access Windows Defender ATP with user context](exposed-apis-create-app-nativeapp.md)
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Delete Ti Indicator.
|
||||
description: Deletes Ti Indicator entity by ID.
|
||||
title: Delete Indicator.
|
||||
description: Deletes Indicator entity by ID.
|
||||
keywords: apis, public api, supported apis, delete, ti indicator, entity, id
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
@ -17,30 +17,30 @@ ms.topic: article
|
||||
ms.date: 12/08/2017
|
||||
---
|
||||
|
||||
# Delete TI Indicator API
|
||||
# Delete Indicator API
|
||||
|
||||
**Applies to:** Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||
|
||||
[!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)
|
||||
> Currently this API is supported only for AppOnly context requests. (See [Get access with application context](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.
|
||||
- Deletes an 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)
|
||||
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Get started](apis-intro.md)
|
||||
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Ti.ReadWrite | 'Read and write TI Indicators'
|
||||
Application | Ti.ReadWrite.All | 'Read and write Indicators'
|
||||
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
Delete https://api.securitycenter.windows.com/api/tiindicators/{id}
|
||||
Delete https://api.securitycenter.windows.com/api/indicators/{id}
|
||||
```
|
||||
|
||||
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||
@ -57,8 +57,8 @@ Authorization | String | Bearer {token}. **Required**.
|
||||
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.
|
||||
If Indicator exist and deleted successfully - 204 OK without content.
|
||||
If Indicator with the specified id was not found - 404 Not Found.
|
||||
|
||||
## Example
|
||||
|
||||
@ -67,7 +67,7 @@ If TI Indicator with the specified id was not found - 404 Not Found.
|
||||
Here is an example of the request.
|
||||
|
||||
```
|
||||
DELETE https://api.securitycenter.windows.com/api/tiindicators/220e7d15b0b3d7fac48f2bd61114db1022197f7f
|
||||
DELETE https://api.securitycenter.windows.com/api/indicators/220e7d15b0b3d7fac48f2bd61114db1022197f7f
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
@ -19,33 +19,30 @@ 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)
|
||||
**Applies to:** [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf)
|
||||
|
||||
> 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.
|
||||
This page describe how to create an application to get programmatic 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 need programmatic access Windows Defender ATP without a user, refer to [Access Windows Defender ATP with application context](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).
|
||||
Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate work flows 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
|
||||
- Create an AAD application
|
||||
- Get an access token using this application
|
||||
- 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.
|
||||
This page explains how to create an AAD application, get an access token to Windows Defender ATP and validate the token.
|
||||
|
||||
>[!NOTE]
|
||||
> When accessing Windows Defender ATP API on behalf of a user, you will need the correct app permission and user permission.
|
||||
> 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]
|
||||
@ -53,7 +50,7 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
## Create an app
|
||||
|
||||
1. Log on to [Azure](https://portal.azure.com).
|
||||
1. Log on to [Azure](https://portal.azure.com) with user that has Global Administrator role.
|
||||
|
||||
2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**.
|
||||
|
||||
@ -78,13 +75,10 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
|
||||
|
||||
6. Click **Select permissions** > check **Read alerts** and **Collect forensics** > **Select**.
|
||||
6. Click **Select permissions** > **Check the desired permissions** > **Select**.
|
||||
|
||||
>[!IMPORTANT]
|
||||
>You need to select the relevant permissions. 'Read alerts' and 'Collect forensics' are only an example.
|
||||
|
||||
|
||||
|
||||
For instance,
|
||||
|
||||
- To [run advanced queries](run-advanced-query-api.md), select 'Run advanced queries' permission
|
||||
@ -92,6 +86,8 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
To determine which permission you need, look at the **Permissions** section in the API you are interested to call.
|
||||
|
||||
|
||||
|
||||
|
||||
7. Click **Done**
|
||||
|
||||
@ -116,39 +112,51 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co
|
||||
|
||||
### 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
|
||||
- Copy/Paste the below class in your application.
|
||||
- Use **AcquireUserTokenAsync** method with the your application ID, tenant ID, user name and password to acquire a token.
|
||||
|
||||
```
|
||||
using Microsoft.IdentityModel.Clients.ActiveDirectory;
|
||||
```
|
||||
namespace WindowsDefenderATP
|
||||
{
|
||||
using System.Net.Http;
|
||||
using System.Text;
|
||||
using System.Threading.Tasks;
|
||||
using Newtonsoft.Json.Linq;
|
||||
|
||||
- Copy/Paste the below code in your application (pay attention to the comments in the code)
|
||||
public static class WindowsDefenderATPUtils
|
||||
{
|
||||
private const string Authority = "https://login.windows.net";
|
||||
|
||||
```
|
||||
const string authority = "https://login.windows.net";
|
||||
const string wdatpResourceId = "https://api.securitycenter.windows.com";
|
||||
private 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
|
||||
public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
|
||||
{
|
||||
using (var httpClient = new HttpClient())
|
||||
{
|
||||
var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
|
||||
|
||||
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!
|
||||
var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
|
||||
|
||||
UserPasswordCredential userCreds = new UserPasswordCredential(username, password);
|
||||
using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
|
||||
{
|
||||
response.EnsureSuccessStatusCode();
|
||||
|
||||
AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}");
|
||||
AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, appId, userCreds).GetAwaiter().GetResult();
|
||||
string token = authenticationResult.AccessToken;
|
||||
var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
|
||||
|
||||
var jObject = JObject.Parse(json);
|
||||
|
||||
return jObject["access_token"].Value<string>();
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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
|
||||
- Copy/paste into [JWT](https://jwt.ms) the token you got 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:
|
||||
|
||||
@ -168,12 +176,11 @@ Sanity check to make sure you got a correct token:
|
||||
|
||||
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
|
||||
|
||||
var response = await httpClient.SendAsync(request).ConfigureAwait(false);
|
||||
var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
|
||||
|
||||
// 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)
|
||||
- [Windows Defender ATP APIs](exposed-apis-list.md)
|
||||
- [Access Windows Defender ATP with application context](exposed-apis-create-app-webapp.md)
|
||||
@ -19,32 +19,30 @@ 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)
|
||||
**Applies to:** [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf)
|
||||
|
||||
|
||||
>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)
|
||||
> 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.
|
||||
This page describes how to create an application to get programmatic 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 need programmatic access Windows Defender ATP on behalf of a user, see [Get access wtih user context](exposed-apis-create-app-nativeapp.md)
|
||||
|
||||
If you are not sure which access you need, see [Use Windows Defender ATP APIs](apis-intro.md).
|
||||
If you are not sure which access you need, see [Get started](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
|
||||
- Create an AAD application
|
||||
- Get an access token using this application
|
||||
- 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.
|
||||
This page explains how to create an AAD application, get an access token to Windows Defender ATP and validate the token.
|
||||
|
||||
## Create an app
|
||||
|
||||
1. Log on to [Azure](https://portal.azure.com).
|
||||
1. Log on to [Azure](https://portal.azure.com) with user that has Global Administrator role.
|
||||
|
||||
2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**.
|
||||
|
||||
@ -54,9 +52,9 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
|
||||
|
||||
- **Name:** WdatpEcosystemPartner
|
||||
- **Name:** Choose your own name.
|
||||
- **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.)
|
||||
- **Redirect URI:** `https://127.0.0.1`
|
||||
|
||||
|
||||
4. Click **Settings** > **Required permissions** > **Add**.
|
||||
@ -69,18 +67,17 @@ 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 the desired permissions** > **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. 'Run advanced queries' is only an example!
|
||||
|
||||
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.
|
||||
|
||||
To determine which permission you need, please look at the **Permissions** section in the API you are interested to call.
|
||||
|
||||
|
||||
7. Click **Done**
|
||||
|
||||
@ -94,7 +91,7 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
|
||||
|
||||
9. Click **Keys** and type a key name and click **Save**.
|
||||
9. Click **Keys**, 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!
|
||||
|
||||
@ -102,9 +99,9 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
10. Write down your application ID.
|
||||
|
||||
|
||||
|
||||
|
||||
11. Set your application to be multi-tenanted
|
||||
11. **For WDATP Partners only** - 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).
|
||||
|
||||
@ -114,26 +111,54 @@ This page explains how to create an app, get an access token to Windows Defender
|
||||
|
||||
|
||||
|
||||
- Application consent for your multi-tenant App:
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
```
|
||||
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
|
||||
where 00000000-0000-0000-0000-000000000000 should be replaced with your Azure application ID
|
||||
|
||||
|
||||
## Get an access token
|
||||
- **Done!** You have successfully registered an application!
|
||||
- See examples below for token acquisition and validation.
|
||||
|
||||
## Get an access token examples:
|
||||
|
||||
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#
|
||||
### Using PowerShell
|
||||
|
||||
```
|
||||
# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
|
||||
# Paste below your Tenant ID, App ID and App Secret (App key).
|
||||
|
||||
$tenantId = '' ### Paste your tenant ID here
|
||||
$appId = '' ### Paste your app ID here
|
||||
$appSecret = '' ### Paste your app key here
|
||||
|
||||
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
|
||||
$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
|
||||
$token = $authResponse.access_token
|
||||
Out-File -FilePath "./Latest-token.txt" -InputObject $token
|
||||
return $token
|
||||
|
||||
```
|
||||
|
||||
### Using C#:
|
||||
|
||||
>The below code was tested with nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8
|
||||
|
||||
@ -161,9 +186,6 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co
|
||||
string token = authenticationResult.AccessToken;
|
||||
```
|
||||
|
||||
### Using PowerShell
|
||||
|
||||
Refer to [Get token using PowerShell](run-advanced-query-sample-powershell.md#get-token)
|
||||
|
||||
### Using Python
|
||||
|
||||
@ -213,12 +235,11 @@ Sanity check to make sure you got a correct token:
|
||||
|
||||
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
|
||||
|
||||
var response = await httpClient.SendAsync(request).ConfigureAwait(false);
|
||||
var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
|
||||
|
||||
// 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)
|
||||
@ -64,7 +64,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "High",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ]
|
||||
},
|
||||
@ -149,7 +148,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "High",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ]
|
||||
},
|
||||
@ -191,7 +189,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "High",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ]
|
||||
},
|
||||
@ -233,7 +230,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "High",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ]
|
||||
},
|
||||
@ -278,5 +274,23 @@ Content-type: application/json
|
||||
}
|
||||
```
|
||||
|
||||
### Example 7
|
||||
|
||||
- Get the count of open alerts for a specific machine:
|
||||
|
||||
```
|
||||
HTTP GET https://api.securitycenter.windows.com/api/machines/123321d0c675eaa415b8e5f383c6388bff446c62/alerts/$count?$filter=status ne 'Resolved'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```
|
||||
HTTP/1.1 200 OK
|
||||
Content-type: application/json
|
||||
|
||||
4
|
||||
|
||||
```
|
||||
|
||||
## Related topic
|
||||
- [Windows Defender ATP APIs](apis-intro.md)
|
||||
|
||||
@ -102,7 +102,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2" ]
|
||||
}
|
||||
|
||||
@ -98,7 +98,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2" ]
|
||||
},
|
||||
@ -117,7 +116,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": false,
|
||||
"aadDeviceId": null,
|
||||
"machineTags": [ "test tag 1" ]
|
||||
}
|
||||
|
||||
@ -98,7 +98,6 @@ Content-type: application/json
|
||||
"healthStatus": "Active",
|
||||
"rbacGroupId": 140,
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2" ]
|
||||
},
|
||||
@ -116,7 +115,6 @@ Content-type: application/json
|
||||
"healthStatus": "Inactive",
|
||||
"rbacGroupId": 140,
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": false,
|
||||
"aadDeviceId": null,
|
||||
"machineTags": [ "test tag 1" ]
|
||||
}
|
||||
|
||||
@ -98,7 +98,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"riskScore": "Low",
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2" ]
|
||||
},
|
||||
@ -117,7 +116,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": false,
|
||||
"aadDeviceId": null,
|
||||
"machineTags": [ "test tag 1" ]
|
||||
}
|
||||
|
||||
@ -99,7 +99,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2" ]
|
||||
}
|
||||
|
||||
@ -1,96 +0,0 @@
|
||||
---
|
||||
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
|
||||
manager: dansimp
|
||||
audience: ITPro
|
||||
ms.collection: M365-security-compliance
|
||||
ms.topic: article
|
||||
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"
|
||||
}
|
||||
|
||||
```
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: List TiIndicators API
|
||||
description: Use this API to create calls related to get TiIndicators collection
|
||||
keywords: apis, public api, supported apis, TiIndicators collection
|
||||
title: List Indicators API
|
||||
description: Use this API to create calls related to get Indicators collection
|
||||
keywords: apis, public api, supported apis, Indicators collection
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
ms.mktglfcycl: deploy
|
||||
@ -17,32 +17,31 @@ ms.topic: article
|
||||
ms.date: 12/08/2017
|
||||
---
|
||||
|
||||
# List TiIndicators API
|
||||
# List Indicators API
|
||||
|
||||
**Applies to:** - Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||
|
||||
[!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)
|
||||
> Currently this API is supported only for AppOnly context requests. (See [Get access with application context](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/).
|
||||
- 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)
|
||||
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Get started](apis-intro.md)
|
||||
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Ti.ReadWrite | 'Read and write TI Indicators'
|
||||
Application | Ti.ReadWrite | 'Read and write Indicators'
|
||||
Application | Ti.ReadWrite.All | 'Read and write All Indicators'
|
||||
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
GET https://api.securitycenter.windows.com/api/tiindicators
|
||||
GET https://api.securitycenter.windows.com/api/indicators
|
||||
```
|
||||
|
||||
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||
@ -58,20 +57,19 @@ Authorization | String | Bearer {token}. **Required**.
|
||||
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.
|
||||
If successful, this method returns 200, Ok response code with a collection of [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.
|
||||
> If the Application has 'Ti.ReadWrite.All' permission, it will be exposed to all Indicators. Otherwise, it will be exposed only to the Indicators it created.
|
||||
|
||||
|
||||
## Example
|
||||
## Example 1:
|
||||
|
||||
**Request**
|
||||
|
||||
Here is an example of a request that gets all TI Indicators
|
||||
Here is an example of a request that gets all Indicators
|
||||
|
||||
```
|
||||
GET https://api.securitycenter.windows.com/api/tiindicators
|
||||
GET https://api.securitycenter.windows.com/api/indicators
|
||||
```
|
||||
|
||||
**Response**
|
||||
@ -82,22 +80,23 @@ 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",
|
||||
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators",
|
||||
"value": [
|
||||
{
|
||||
"indicator": "12.13.14.15",
|
||||
"indicatorValue": "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",
|
||||
"action": "Alert",
|
||||
"severity": "Informational",
|
||||
"description": "test",
|
||||
"recommendedActions": "test"
|
||||
"recommendedActions": "test",
|
||||
"rbacGroupNames": []
|
||||
},
|
||||
{
|
||||
"indicator": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
|
||||
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
|
||||
"indicatorType": "FileSha1",
|
||||
"title": "test",
|
||||
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
|
||||
@ -106,8 +105,48 @@ Content-type: application/json
|
||||
"action": "AlertAndBlock",
|
||||
"severity": "Informational",
|
||||
"description": "test",
|
||||
"recommendedActions": "TEST"
|
||||
"recommendedActions": "TEST",
|
||||
"rbacGroupNames": [ "Group1", "Group2" ]
|
||||
}
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Example 2:
|
||||
|
||||
**Request**
|
||||
|
||||
Here is an example of a request that gets all Indicators with 'AlertAndBlock' action
|
||||
|
||||
```
|
||||
GET https://api.securitycenter.windows.com/api/indicators?$filter=action eq 'AlertAndBlock'
|
||||
```
|
||||
|
||||
**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#Indicators",
|
||||
"value": [
|
||||
{
|
||||
"indicatorValue": "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",
|
||||
"rbacGroupNames": [ "Group1", "Group2" ]
|
||||
}
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
@ -101,7 +101,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": true,
|
||||
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
|
||||
"machineTags": [ "test tag 1", "test tag 2" ]
|
||||
},
|
||||
@ -120,7 +119,6 @@ Content-type: application/json
|
||||
"rbacGroupId": 140,
|
||||
"rbacGroupName": "The-A-Team",
|
||||
"riskScore": "Low",
|
||||
"isAadJoined": false,
|
||||
"aadDeviceId": null,
|
||||
"machineTags": [ "test tag 1" ]
|
||||
}
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 272 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 180 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 7.6 KiB After Width: | Height: | Size: 6.9 KiB |
@ -0,0 +1,98 @@
|
||||
---
|
||||
title: Initiate machine investigation API
|
||||
description: Use this API to create calls related to initiating an investigation on a machine.
|
||||
keywords: apis, graph api, supported apis, initiate AutoIR investigation
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
ms.mktglfcycl: deploy
|
||||
ms.sitesec: library
|
||||
ms.pagetype: security
|
||||
ms.author: macapara
|
||||
author: mjcaparas
|
||||
ms.localizationpriority: medium
|
||||
manager: dansimp
|
||||
audience: ITPro
|
||||
ms.collection: M365-security-compliance
|
||||
ms.topic: article
|
||||
---
|
||||
|
||||
# Initiate machine investigation API (Preview)
|
||||
**Applies to:**
|
||||
- [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
|
||||
|
||||
Initiate AutoIR investigation on a machine.
|
||||
|
||||
>[!Note]
|
||||
> This page focuses on performing an automated investigation on a machine. See [Automated Investigation](automated-investigations-windows-defender-advanced-threat-protection.md) for more information.
|
||||
|
||||
## Limitations
|
||||
1. The number of executions is limited (up to 5 calls per hour).
|
||||
2. For Automated Investigation limitations, see [Automated Investigation](automated-investigations-windows-defender-advanced-threat-protection.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 | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||
|
||||
>[!Note]
|
||||
> When obtaining a token using user credentials:
|
||||
>- The user needs to have at least the following role permission: 'Alerts Investigation' (See [Create and manage roles](user-roles-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}/InitiateInvestigation
|
||||
```
|
||||
|
||||
## Request headers
|
||||
|
||||
Name | Type | Description
|
||||
:---|:---|:---
|
||||
Authorization | String | Bearer {token}. **Required**.
|
||||
Content-Type | string | application/json. **Required**.
|
||||
|
||||
## Request body
|
||||
In the request body, supply a JSON object with the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:---|:---|:---
|
||||
Comment | String | Comment to associate with the action. **Required**.
|
||||
|
||||
## Response
|
||||
If successful, this method returns 200 OK response code with object that holds the investigation ID in the "value" parameter. If machine was not found - 404 Not Found.
|
||||
|
||||
## Example
|
||||
|
||||
**Request**
|
||||
|
||||
Here is an example of the request.
|
||||
|
||||
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||
|
||||
```
|
||||
POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/InitiateInvestigation
|
||||
Content-type: application/json
|
||||
{
|
||||
"Comment": "Initiate an investigation on machine fb9ab6be3965095a09c057be7c90f0a2"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
Here is an example of the response.
|
||||
|
||||
```
|
||||
HTTP/1.1 200 Created
|
||||
Content-type: application/json
|
||||
{
|
||||
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Edm.Int64",
|
||||
"value": 5146
|
||||
}
|
||||
|
||||
```
|
||||
@ -47,6 +47,5 @@ healthStatus | Enum | [machine](machine-windows-defender-advanced-threat-protect
|
||||
rbacGroupId | Int | RBAC Group ID.
|
||||
rbacGroupName | String | RBAC Group Name.
|
||||
riskScore | Nullable Enum | Risk score as evaluated by WDATP. Possible values are: 'None', 'Low', 'Medium' and 'High'.
|
||||
isAadJoined | Nullable Boolean | Is [machine](machine-windows-defender-advanced-threat-protection-new.md) AAD joined.
|
||||
aadDeviceId | Nullable Guid | AAD Device ID (when [machine](machine-windows-defender-advanced-threat-protection-new.md) is Aad Joined).
|
||||
machineTags | String collection | Set of [machine](machine-windows-defender-advanced-threat-protection-new.md) tags.
|
||||
@ -61,7 +61,7 @@ Managed security service provider | Get a quick overview on managed security ser
|
||||
## Related topics
|
||||
- [Onboard machines](onboard-configure-windows-defender-advanced-threat-protection.md)
|
||||
- [Enable the custom threat intelligence application](enable-custom-ti-windows-defender-advanced-threat-protection.md)
|
||||
- [Use the Windows Defender ATP exposed APIs](use-apis.md)
|
||||
- [Windows Defender ATP Public API](use-apis.md)
|
||||
- [Pull alerts to your SIEM tools](configure-siem-windows-defender-advanced-threat-protection.md)
|
||||
- [Create and build Power BI reports using Windows Defender ATP data](powerbi-reports-windows-defender-advanced-threat-protection.md)
|
||||
- [Role-based access control](rbac-windows-defender-advanced-threat-protection.md)
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
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
|
||||
title: Submit or Update Indicator API
|
||||
description: Use this API to submit or Update Indicator.
|
||||
keywords: apis, graph api, supported apis, submit, ti, indicator, update
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
ms.mktglfcycl: deploy
|
||||
@ -17,32 +17,31 @@ ms.topic: article
|
||||
ms.date: 12/08/2017
|
||||
---
|
||||
|
||||
# Submit or Update TI Indicator API
|
||||
# Submit or Update Indicator API
|
||||
|
||||
**Applies to:** Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||
|
||||
[!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)
|
||||
> Currently this API is supported only for AppOnly context requests. (See [Get access with application context](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.
|
||||
- Submits or Updates new [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)
|
||||
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Get started](apis-intro.md)
|
||||
|
||||
Permission type | Permission | Permission display name
|
||||
:---|:---|:---
|
||||
Application | Ti.ReadWrite | 'Read and write TI Indicators'
|
||||
Application | Ti.ReadWrite | 'Read and write Indicators'
|
||||
Application | Ti.ReadWrite.All | 'Read and write All Indicators'
|
||||
|
||||
|
||||
## HTTP request
|
||||
```
|
||||
POST https://api.securitycenter.windows.com/api/tiindicators
|
||||
POST https://api.securitycenter.windows.com/api/indicators
|
||||
```
|
||||
|
||||
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||
@ -60,10 +59,10 @@ 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**
|
||||
indicatorValue | String | Identity of the [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**
|
||||
title | String | 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**
|
||||
@ -71,8 +70,8 @@ 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.
|
||||
- If successful, this method returns 200 - OK response code and the created / updated [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 an Indicator that conflicts with an existing Indicator type or Action.
|
||||
|
||||
## Example
|
||||
|
||||
@ -81,10 +80,10 @@ recommendedActions | String | TI indicator alert recommended actions. **Optional
|
||||
Here is an example of the request.
|
||||
|
||||
```
|
||||
POST https://api.securitycenter.windows.com/api/tiindicators
|
||||
POST https://api.securitycenter.windows.com/api/indicators
|
||||
Content-type: application/json
|
||||
{
|
||||
"indicator": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
|
||||
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
|
||||
"indicatorType": "FileSha1",
|
||||
"title": "test",
|
||||
"expirationTime": "2020-12-12T00:00:00Z",
|
||||
@ -103,8 +102,8 @@ 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",
|
||||
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators/$entity",
|
||||
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
|
||||
"indicatorType": "FileSha1",
|
||||
"title": "test",
|
||||
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
|
||||
@ -113,7 +112,8 @@ Content-type: application/json
|
||||
"action": "AlertAndBlock",
|
||||
"severity": "Informational",
|
||||
"description": "test",
|
||||
"recommendedActions": "TEST"
|
||||
"recommendedActions": "TEST",
|
||||
"rbacGroupNames": []
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
ms.date: 08/28/2017
|
||||
---
|
||||
>[!IMPORTANT]
|
||||
|
||||
>[!IMPORTANT]
|
||||
>Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
|
||||
@ -17,7 +17,7 @@ ms.collection: M365-security-compliance
|
||||
ms.topic: article
|
||||
---
|
||||
|
||||
# Pull Windows Defender ATP alerts using REST API
|
||||
# Pull Windows Defender ATP alerts using SIEM REST API
|
||||
|
||||
**Applies to:**
|
||||
- [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
|
||||
|
||||
@ -18,22 +18,19 @@ ms.date: 09/03/2018
|
||||
---
|
||||
|
||||
# Advanced hunting API
|
||||
**Applies to:**
|
||||
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||
|
||||
**Applies to:** [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf)
|
||||
|
||||
[!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
|
||||
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)
|
||||
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)
|
||||
4. The maximal execution time of a single request is 10 minutes.
|
||||
|
||||
## 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)
|
||||
@ -45,7 +42,7 @@ 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 'View Data' 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
|
||||
@ -135,7 +132,7 @@ Content-Type: application/json
|
||||
|
||||
## Troubleshoot issues
|
||||
|
||||
- Error: (403) Forbidden
|
||||
- Error: (403) Forbidden / (401) Unauthorized
|
||||
|
||||
|
||||
If you get this error when calling Windows Defender ATP API, your token might not include the necessary permission.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: TiIndicator resource type
|
||||
description: TiIndicator entity description.
|
||||
keywords: apis, supported apis, get, TiIndicator, recent
|
||||
title: Indicator resource type
|
||||
description: Indicator entity description.
|
||||
keywords: apis, supported apis, get, TiIndicator, Indicator, recent
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
ms.mktglfcycl: deploy
|
||||
@ -17,33 +17,33 @@ ms.topic: article
|
||||
ms.date: 12/08/2017
|
||||
---
|
||||
|
||||
# TI(threat intelligence) Indicator resource type
|
||||
# Indicator resource type
|
||||
|
||||
**Applies to:**
|
||||
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||
**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.
|
||||
[List Indicators](get-ti-indicators-collection-windows-defender-advanced-threat-protection-new.md) | [Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) Collection | List [Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entities.
|
||||
[Submit Indicator](post-ti-indicator-windows-defender-advanced-threat-protection-new.md) | [Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) | Submits [Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity.
|
||||
[Delete Indicator](delete-ti-indicator-by-id-windows-defender-advanced-threat-protection-new.md) | No Content | Deletes [Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity.
|
||||
|
||||
- See the corresponding [page](https://securitycenter.windows.com/preferences2/custom_ti_indicators/files) in the portal:
|
||||
|
||||
# Properties
|
||||
Property | Type | Description
|
||||
:---|:---|:---
|
||||
indicator | String | Identity of the [TI Indicator](ti-indicator-windows-defender-advanced-threat-protection-new.md) entity.
|
||||
indicatorValue | String | Identity of the [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.
|
||||
title | String | 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.
|
||||
recommendedActions | String | Indicator alert recommended actions.
|
||||
rbacGroupNames | List of strings | RBAC group names where the indicator is exposed. Empty list in case it exposed to all groups.
|
||||
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Use the Windows Defender Advanced Threat Protection APIs
|
||||
title: Windows Defender ATP Public API
|
||||
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
|
||||
keywords: apis, api, wdatp, open api, windows defender atp api, public api, alerts, machine, user, domain, ip, file
|
||||
search.product: eADQiWindows 10XVcnh
|
||||
ms.prod: w10
|
||||
ms.mktglfcycl: deploy
|
||||
@ -17,14 +17,15 @@ ms.topic: conceptual
|
||||
ms.date: 11/28/2018
|
||||
---
|
||||
|
||||
# Use the Windows Defender ATP exposed APIs
|
||||
# Windows Defender ATP Public API
|
||||
|
||||
**Applies to:**
|
||||
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||
**Applies to:** [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://wincom.blob.core.windows.net/documents/Windows10_Commercial_Comparison.pdf)
|
||||
|
||||
> 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)
|
||||
|
||||
## 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](exposed-apis-create-app-nativeapp.md) or [without a user](exposed-apis-create-app-webapp.md).
|
||||
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. Examples include APIs for [alert resource type](alerts-windows-defender-advanced-threat-protection-new.md), [domain related alerts](get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md), or even actions such as [isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md).
|
||||
[Windows Defender ATP API overview](apis-intro.md) | Learn how to access to Windows Defender ATP Public API and on which context.
|
||||
[Supported Windows Defender ATP APIs](exposed-apis-list.md) | 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. Examples include APIs for [alert resource type](alerts-windows-defender-advanced-threat-protection-new.md), [domain related alerts](get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md), or even actions such as [isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md).
|
||||
How to use APIs - Samples | Learn how to use Advanced hunting APIs and multiple APIs such as PowerShell. Other examples include [schedule advanced hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md) or [OData queries](exposed-apis-odata-samples.md).
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user