mirror of
https://github.com/MicrosoftDocs/windows-itpro-docs.git
synced 2025-05-16 07:17:24 +00:00
merge from api-danm
This commit is contained in:
Joey Caparas
commit
928c6304ea
@ -508,6 +508,10 @@
|
|||||||
"master": [
|
"master": [
|
||||||
"Publish",
|
"Publish",
|
||||||
"Pdf"
|
"Pdf"
|
||||||
|
],
|
||||||
|
"atp-api-danm": [
|
||||||
|
"Publish",
|
||||||
|
"Pdf"
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"need_generate_pdf_url_template": true,
|
"need_generate_pdf_url_template": true,
|
||||||
|
|||||||
@ -0,0 +1,79 @@
|
|||||||
|
---
|
||||||
|
title: Get alerts API
|
||||||
|
description: Retrieves top recent alerts.
|
||||||
|
keywords: apis, graph api, supported apis, get, alerts, recent
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Alert resource type
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
Represents an alert entity in WDATP.
|
||||||
|
|
||||||
|
# Methods
|
||||||
|
Method|Return Type |Description
|
||||||
|
:---|:---|:---
|
||||||
|
[Get alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) | Get a single [alert](alerts-windows-defender-advanced-threat-protection-new.md) object.
|
||||||
|
[List alerts](get-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | List [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection.
|
||||||
|
[Create alert](create-alert-by-reference-windows-defender-advanced-threat-protection-new.md)|[alert](alerts-windows-defender-advanced-threat-protection-new.md)|Create an alert based on event data obtained from [Advanced Hunting](run-advanced-query-api.md)
|
||||||
|
[List related domains](get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md)|Domain collection|List Urls associated with the alert.
|
||||||
|
[List related files](get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md) | [file](files-windows-defender-advanced-threat-protection-new.md) collection | List the [file](files-windows-defender-advanced-threat-protection-new.md) entities that are associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
[List related IPs](get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md) | IP collection | List IPs that are associated witht the alert.
|
||||||
|
[Get related machines](get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) | The [machine](machine-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
[Get related users](get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md) | [user](user-windows-defender-advanced-threat-protection-new.md) | The [user](user-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
|
||||||
|
|
||||||
|
# Properties
|
||||||
|
Property | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
id | String | alert id.
|
||||||
|
severity | String | severity of the alert. Allowed values are: 'Low', 'Medium' and 'High'.
|
||||||
|
status | String | Specifies the current status of the alert. The property values are: 'New', 'InProgress' and 'Resolved'.
|
||||||
|
description | String | Description of the threat, identified by the alert.
|
||||||
|
recommendedAction | String | Action recommended for handling the suspected threat.
|
||||||
|
alertCreationTime | DateTimeOffset | The date and time (in UTC) the alert was created.
|
||||||
|
category| String | Category of the alert. The property values are: 'None', 'SuspiciousActivity', 'Malware', 'CredentialTheft', 'Exploit', 'WebExploit', 'DocumentExploit', 'PrivilegeEscalation', 'Persistence', 'RemoteAccessTool', 'CommandAndControl', 'SuspiciousNetworkTraffic', 'Ransomware', 'MalwareDownload', 'Reconnaissance', 'WebFingerprinting', 'Weaponization', 'Delivery', 'SocialEngineering', 'CredentialStealing', 'Installation', 'Backdoor', 'Trojan', 'TrojanDownloader', 'LateralMovement', 'ExplorationEnumeration', 'NetworkPropagation', 'Exfiltration', 'NotApplicable', 'EnterprisePolicy' and 'General'.
|
||||||
|
title | string | Alert title.
|
||||||
|
threatFamilyName | string | Threat family.
|
||||||
|
detectionSource | string | detection source
|
||||||
|
assignedTo | String | Owner of the alert
|
||||||
|
classification | String | Speficies the specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'.
|
||||||
|
determination | String | Specifies the determination of the alert. The property values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other'
|
||||||
|
resolvedTime | DateTimeOffset | The date and time in which the status of the alert was changed to 'Resolved'.
|
||||||
|
lastEventTime | DateTimeOffset | The last occurance of the event that triggered the alert on the same machine.
|
||||||
|
firstEventTime | DateTimeOffset | The first occurance of the event that triggered the alert on that machine.
|
||||||
|
machineId | String | id of a [machine](machine-windows-defender-advanced-threat-protection-new.md) entity that is associated with the alert.
|
||||||
|
|
||||||
|
# JSON representation
|
||||||
|
```
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
|
||||||
|
"id": "636688558380765161_2136280442",
|
||||||
|
"severity": "Informational",
|
||||||
|
"status": "InProgress",
|
||||||
|
"description": "Some alert description 1",
|
||||||
|
"recommendedAction": "Some recommended action 1",
|
||||||
|
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
|
||||||
|
"category": "General",
|
||||||
|
"title": "Some alert title 1",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "WindowsDefenderAtp",
|
||||||
|
"classification": "TruePositive",
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": "best secop ever",
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,95 @@
|
|||||||
|
---
|
||||||
|
title: Collect investigation package API
|
||||||
|
description: Use this API to create calls related to the collecting an investigation package from a machine.
|
||||||
|
keywords: apis, graph api, supported apis, collect investigation package
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Collect investigation package API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Collect investigation package from a machine.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.CollectForensics | 'Collect forensics'
|
||||||
|
Delegated (work or school account) | Machine.CollectForensics | 'Collect forensics'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
POST /api/machines/{id}/collectInvestigationPackage
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
Content-Type | string | application/json. **Required**.
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply a JSON object with the following parameters:
|
||||||
|
|
||||||
|
Parameter | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Comment | String | Comment to associate with the action. **Required**.
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/collectInvestigationPackage
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"Comment": "Collect forensics due to alert 1234"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 201 Created
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
|
||||||
|
"id": "c9042f9b-8483-4526-87b5-35e4c2532223",
|
||||||
|
"type": "CollectInvestigationPackage",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": " Collect forensics due to alert 1234",
|
||||||
|
"status": "InProgress",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:09:24.1785079Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:09:24.1785079Z"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
@ -0,0 +1,88 @@
|
|||||||
|
---
|
||||||
|
title: Create alert from event API
|
||||||
|
description: Creates an alert using event details
|
||||||
|
keywords: apis, graph api, supported apis, get, alert, information, id
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create alert from event API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
Enables using event data, as obtained from the [Advanced Hunting](run-advanced-query-api.md) for creating a new alert entity.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Alerts.ReadWrite.All | 'Read and write all alerts'
|
||||||
|
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
POST /api/CreateAlertByReference
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
Content-Type | String | application/json. **Required**.
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply the following values (all are required):
|
||||||
|
|
||||||
|
Property | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
machineId | String | Id of the machine on which the event was identified. **Required**.
|
||||||
|
severity | String | Severity of the alert. The property values are: 'Low', 'Medium' and 'High'. **Required**.
|
||||||
|
title | String | Title for the alert. **Required**.
|
||||||
|
description | String | Description of the alert. **Required**.
|
||||||
|
recommendedAction| String | Action that is recommended to be taken by security officer when analyzing the alert.
|
||||||
|
eventTime | DateTime(UTC) | The time of the event, as obtained from the advanced query. **Required**.
|
||||||
|
reportId | String | The reportId, as obtained from the advanced query. **Required**.
|
||||||
|
category| String | Category of the alert. The property values are: 'None', 'SuspiciousActivity', 'Malware', 'CredentialTheft', 'Exploit', 'WebExploit', 'DocumentExploit', 'PrivilegeEscalation', 'Persistence', 'RemoteAccessTool', 'CommandAndControl', 'SuspiciousNetworkTraffic', 'Ransomware', 'MalwareDownload', 'Reconnaissance', 'WebFingerprinting', 'Weaponization', 'Delivery', 'SocialEngineering', 'CredentialStealing', 'Installation', 'Backdoor', 'Trojan', 'TrojanDownloader', 'LateralMovement', 'ExplorationEnumeration', 'NetworkPropagation', 'Exfiltration', 'NotApplicable', 'EnterprisePolicy' and 'General'.
|
||||||
|
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 200 OK, and a new [alert](alerts-windows-defender-advanced-threat-protection-new.md) object in the response body. If event with the specified properties (_reportId_, _eventTime_ and _machineId_) was not found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.securitycenter.windows.com/api/CreateAlertByReference
|
||||||
|
Content-Length: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"severity": "Low",
|
||||||
|
"title": "test alert",
|
||||||
|
"description": "redalert",
|
||||||
|
"recommendedAction": "white alert",
|
||||||
|
"eventTime": "2018-08-03T16:45:21.7115183Z",
|
||||||
|
"reportId": "20776",
|
||||||
|
"category": "None"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,172 @@
|
|||||||
|
---
|
||||||
|
title: Use Windows Defender Advanced Threat Protection APIs
|
||||||
|
description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph.
|
||||||
|
keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 09/03/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Use Windows Defender ATP APIs
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
>Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
|
||||||
|
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
|
||||||
|
This pages describes how to create an application to get programmatical access to Windows Defender ATP on behalf of a user.
|
||||||
|
|
||||||
|
If you need programmatical access Windows Defender ATP without a user, please refer to [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md)
|
||||||
|
|
||||||
|
If you are not sure which access you need, you'd better read the [Introduction page](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
|
||||||
|
|
||||||
|
In general, you’ll need to take the following steps to use the APIs:
|
||||||
|
- Create an app
|
||||||
|
- Get an access token
|
||||||
|
- Use the token to access Windows Defender ATP API
|
||||||
|
|
||||||
|
This page explains how to create an app, get an access token to Windows Defender ATP and validate the token includes the required permission.
|
||||||
|
|
||||||
|
**Note**: When accessing 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).
|
||||||
|
|
||||||
|
2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
3. In the Create window, enter the following information then click **Create**.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- **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**.
|
||||||
|
|
||||||
|
**Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
6. Click **Select permissions** > check **Read alerts** & **Collect forensics** > **Select**.
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
|
||||||
|
7. Click **Done**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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. Write down your application ID.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Get an access token
|
||||||
|
|
||||||
|
For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds)
|
||||||
|
|
||||||
|
### Using C#
|
||||||
|
|
||||||
|
The code was below tested with nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8
|
||||||
|
|
||||||
|
- Create a new Console Application
|
||||||
|
- Install Nuget [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/)
|
||||||
|
- Add the below using
|
||||||
|
|
||||||
|
```
|
||||||
|
using Microsoft.IdentityModel.Clients.ActiveDirectory;
|
||||||
|
```
|
||||||
|
|
||||||
|
- Copy/Paste the below code in your application (pay attention to the comments in the code)
|
||||||
|
|
||||||
|
```
|
||||||
|
const string authority = "https://login.windows.net";
|
||||||
|
const string wdatpResourceId = "https://api.securitycenter.windows.com";
|
||||||
|
|
||||||
|
string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
|
||||||
|
string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
|
||||||
|
|
||||||
|
string username = "SecurityAdmin123@microsoft.com"; // Paste your username here
|
||||||
|
string password = GetPasswordFromSafePlace(); // Paste your own password here for a test, and then store it in a safe place!
|
||||||
|
|
||||||
|
UserPasswordCredential userCreds = new UserPasswordCredential(username, password);
|
||||||
|
|
||||||
|
AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}");
|
||||||
|
AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, appId, userCreds).GetAwaiter().GetResult();
|
||||||
|
string token = authenticationResult.AccessToken;
|
||||||
|
```
|
||||||
|
|
||||||
|
## Validate the token
|
||||||
|
|
||||||
|
Sanity check to make sure you got a correct token:
|
||||||
|
- Copy/paste into [JWT](https://jwt.ms) the token you get in the previous step in order to decode it
|
||||||
|
- Validate you get a 'scp' claim with the desired app permissions
|
||||||
|
- In the screenshot below you can see a decoded token acquired from the app in the tutorial:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 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)
|
||||||
|
- [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md)
|
||||||
@ -0,0 +1,220 @@
|
|||||||
|
---
|
||||||
|
title: Create an app to access Windows Defender ATP without a user
|
||||||
|
description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph.
|
||||||
|
keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 09/03/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create an app to access Windows Defender ATP without a user
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
>Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
This pages describes how to create an application to get programmatical access to Windows Defender ATP without a user.
|
||||||
|
|
||||||
|
If you need programmatical access Windows Defender ATP on behalf of a user, please refer to [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md)
|
||||||
|
|
||||||
|
If you are not sure which access you need, see [Use Windows Defender ATP APIs](exposed-apis-intro.md).
|
||||||
|
|
||||||
|
Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will help you automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
|
||||||
|
|
||||||
|
In general, you’ll need to take the following steps to use the APIs:
|
||||||
|
- Create an app
|
||||||
|
- Get an access token
|
||||||
|
- Use the token to access Windows Defender ATP API
|
||||||
|
|
||||||
|
This page explains how to create an app, get an access token to Windows Defender ATP and validate the token includes the required permission.
|
||||||
|
|
||||||
|
## Create an app
|
||||||
|
|
||||||
|
1. Log on to [Azure](https://portal.azure.com).
|
||||||
|
|
||||||
|
2. Navigate to **Azure Active Directory** > **App registrations** > **New application registration**.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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.)
|
||||||
|
|
||||||
|
|
||||||
|
4. Click **Settings** > **Required permissions** > **Add**.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
5. Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
|
||||||
|
|
||||||
|
**Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
6. Click **Select permissions** > **Run advanced queries** > **Select**.
|
||||||
|
|
||||||
|
**Important note**: You need to select the relevant permission. 'Run advanced queries' is 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.
|
||||||
|
|
||||||
|
7. Click **Done**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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!
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
10. Write down your application ID.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds)
|
||||||
|
|
||||||
|
### Using C#
|
||||||
|
|
||||||
|
>The below code was tested with nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8
|
||||||
|
|
||||||
|
- Create a new Console Application
|
||||||
|
- Install Nuget [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/)
|
||||||
|
- Add the below using
|
||||||
|
|
||||||
|
```
|
||||||
|
using Microsoft.IdentityModel.Clients.ActiveDirectory;
|
||||||
|
```
|
||||||
|
|
||||||
|
- Copy/Paste the below code in your application (do not forget to update the 3 variables: ```tenantId, appId, appSecret```)
|
||||||
|
|
||||||
|
```
|
||||||
|
string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
|
||||||
|
string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
|
||||||
|
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place!
|
||||||
|
|
||||||
|
const string authority = "https://login.windows.net";
|
||||||
|
const string wdatpResourceId = "https://api.securitycenter.windows.com";
|
||||||
|
|
||||||
|
AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
|
||||||
|
ClientCredential clientCredential = new ClientCredential(appId, appSecret);
|
||||||
|
AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
|
||||||
|
string token = authenticationResult.AccessToken;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using PowerShell
|
||||||
|
|
||||||
|
Refer to [Get token using PowerShell](run-advanced-query-sample-powershell.md#get-token)
|
||||||
|
|
||||||
|
### Using Python
|
||||||
|
|
||||||
|
Refer to [Get token using Python](run-advanced-query-sample-python.md#get-token)
|
||||||
|
|
||||||
|
### Using Curl
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> The below procedure supposed Curl for Windows is already installed on your computer
|
||||||
|
|
||||||
|
- Open a command window
|
||||||
|
- Set CLIENT_ID to your Azure application ID
|
||||||
|
- Set CLIENT_SECRET to your Azure application secret
|
||||||
|
- Set TENANT_ID to the Azure tenant ID of the customer that wants to use your application to access WDATP application
|
||||||
|
- Run the below command:
|
||||||
|
|
||||||
|
```
|
||||||
|
curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
|
||||||
|
```
|
||||||
|
|
||||||
|
You will get an answer of the form:
|
||||||
|
|
||||||
|
```
|
||||||
|
{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Validate the token
|
||||||
|
|
||||||
|
Sanity check to make sure you got a correct token:
|
||||||
|
- Copy/paste into [JWT](https://jwt.ms) the token you get in the previous step in order to decode it
|
||||||
|
- Validate you get a 'roles' claim with the desired permissions
|
||||||
|
- In the screenshot below you can see a decoded token acquired from an app with permissions to all of Wdatp's roles:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Use the token to access Windows Defender ATP API
|
||||||
|
|
||||||
|
- Choose the API you want to use, for more information, see [Supported Windows Defender ATP APIs](exposed-apis-list.md)
|
||||||
|
- Set the Authorization header in the Http request you send to "Bearer {token}" (Bearer is the Authorization scheme)
|
||||||
|
- The Expiration time of the token is 1 hour (you can send more then one request with the same token)
|
||||||
|
|
||||||
|
- Example of sending a request to get a list of alerts **using C#**
|
||||||
|
```
|
||||||
|
var httpClient = new HttpClient();
|
||||||
|
|
||||||
|
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.windows.com/api/alerts");
|
||||||
|
|
||||||
|
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
|
||||||
|
|
||||||
|
var response = await httpClient.SendAsync(request).ConfigureAwait(false);
|
||||||
|
|
||||||
|
// Do something useful with the response
|
||||||
|
```
|
||||||
|
|
||||||
|
## Related topics
|
||||||
|
- [Windows Defender ATP APIs](exposed-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)
|
||||||
@ -0,0 +1,113 @@
|
|||||||
|
---
|
||||||
|
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
|
||||||
|
---
|
||||||
|
|
||||||
|
# Windows Defender ATP APIs using PowerShell
|
||||||
|
|
||||||
|
Full scenario using multiple APIs from Windows Defender ATP.
|
||||||
|
|
||||||
|
In this section we share PowerShell samples to
|
||||||
|
- Retrieve a token
|
||||||
|
- Use token to retrieve the latest alerts in Windows Defender ATP
|
||||||
|
- For each alert, if the alert has medium or high priority and is still in progress, check how many times the machine has connected to suspicious URL.
|
||||||
|
|
||||||
|
>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md).
|
||||||
|
|
||||||
|
## Preparation Instructions
|
||||||
|
|
||||||
|
- Open a PowerShell window.
|
||||||
|
- If your policy does not allow you to run the PowerShell commands, you can run the below command:
|
||||||
|
```
|
||||||
|
Set-ExecutionPolicy -ExecutionPolicy Bypass
|
||||||
|
```
|
||||||
|
|
||||||
|
>For more details, refer to [PowerShell documentation](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy)
|
||||||
|
|
||||||
|
## Get token
|
||||||
|
|
||||||
|
- Run the below
|
||||||
|
|
||||||
|
> - $tenantId: ID of the tenant on behalf of which you want to run the query (i.e., the query will be run on the data of this tenant)
|
||||||
|
> - $appId: ID of your AAD app (the app must have 'Run advanced queries' permission to WDATP)
|
||||||
|
> - $appSecret: Secret of your AAD app
|
||||||
|
> - $suspiciousUrl: The URL
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
$tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here
|
||||||
|
$appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here
|
||||||
|
$appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here
|
||||||
|
$suspiciousUrl = 'www.suspiciousUrl.com' # Paste your own URL here
|
||||||
|
|
||||||
|
$resourceAppIdUri = 'https://securitycenter.onmicrosoft.com/windowsatpservice'
|
||||||
|
$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
|
||||||
|
$authBody = [Ordered] @{
|
||||||
|
resource = "$resourceAppIdUri"
|
||||||
|
client_id = "$appId"
|
||||||
|
client_secret = "$appSecret"
|
||||||
|
grant_type = 'client_credentials'
|
||||||
|
}
|
||||||
|
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
|
||||||
|
$aadToken = $authResponse.access_token
|
||||||
|
|
||||||
|
|
||||||
|
#Get latest alert
|
||||||
|
$alertUrl = "https://api.securitycenter.windows.com/api/alerts?`$top=10"
|
||||||
|
$headers = @{
|
||||||
|
'Content-Type' = 'application/json'
|
||||||
|
Accept = 'application/json'
|
||||||
|
Authorization = "Bearer $aadToken"
|
||||||
|
}
|
||||||
|
$alertResponse = Invoke-WebRequest -Method Get -Uri $alertUrl -Headers $headers -ErrorAction Stop
|
||||||
|
$alerts = ($alertResponse | ConvertFrom-Json).value
|
||||||
|
|
||||||
|
$machinesToInvestigate = New-Object System.Collections.ArrayList
|
||||||
|
|
||||||
|
Foreach($alert in $alerts)
|
||||||
|
{
|
||||||
|
#echo $alert.id $alert.machineId $alert.severity $alert.status
|
||||||
|
|
||||||
|
$isSevereAlert = $alert.severity -in 'Medium', 'High'
|
||||||
|
$isOpenAlert = $alert.status -in 'InProgress', 'New'
|
||||||
|
if($isOpenAlert -and $isSevereAlert)
|
||||||
|
{
|
||||||
|
if (-not $machinesToInvestigate.Contains($alert.machineId))
|
||||||
|
{
|
||||||
|
$machinesToInvestigate.Add($alert.machineId) > $null
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
$commaSeparatedMachines = '"{0}"' -f ($machinesToInvestigate -join '","')
|
||||||
|
|
||||||
|
$query = "NetworkCommunicationEvents
|
||||||
|
| where MachineId in ($commaSeparatedMachines)
|
||||||
|
| where RemoteUrl == `"$suspiciousUrl`"
|
||||||
|
| summarize ConnectionsCount = count() by MachineId"
|
||||||
|
|
||||||
|
$queryUrl = "https://api.securitycenter.windows.com/advancedqueries/query"
|
||||||
|
|
||||||
|
$queryBody = ConvertTo-Json -InputObject @{ 'Query' = $query }
|
||||||
|
$queryResponse = Invoke-WebRequest -Method Post -Uri $queryUrl -Headers $headers -Body $queryBody -ErrorAction Stop
|
||||||
|
$response = ($queryResponse | ConvertFrom-Json).Results
|
||||||
|
$response
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
## Related topic
|
||||||
|
- [Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
- [Advanced Hunting API](run-advanced-query-api.md)
|
||||||
|
- [Advanced Hunting using Python](run-advanced-query-sample-python.md)
|
||||||
|
- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)
|
||||||
@ -0,0 +1,55 @@
|
|||||||
|
---
|
||||||
|
title: Use Windows Defender Advanced Threat Protection APIs
|
||||||
|
description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph.
|
||||||
|
keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 09/03/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Use Windows Defender ATP APIs
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
>Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
|
||||||
|
|
||||||
|
In general, you’ll need to take the following steps to use the APIs:
|
||||||
|
- Create an app
|
||||||
|
- Get an access token
|
||||||
|
- Use the token to access Windows Defender ATP API
|
||||||
|
|
||||||
|
|
||||||
|
As a developer, you decide which permissions for Windows Defender ATP your app requests. When a user signs in to your app they (or, in some cases, an administrator) are given a chance to give consent to these permissions. If the user provides consent, your app is given access to the resources and APIs that it has requested. For apps that don't take a signed-in user, permissions can be pre-approved to by an administrator when the app is installed or during sign-up.
|
||||||
|
|
||||||
|
# #Delegated permissions, application permissions, and effective permissions
|
||||||
|
|
||||||
|
Windows Defender ATP has two types of permissions: delegated permissions and application permissions.
|
||||||
|
|
||||||
|
- Delegated permissions are 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 are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. Application permissions can only be consented by an administrator.
|
||||||
|
|
||||||
|
Effective permissions are the permissions that your app will have when making requests to Windows Defender ATP. It is important to understand the difference between the delegated and application permissions that your app is granted and its effective permissions when making calls to Windows Defender ATP.
|
||||||
|
|
||||||
|
- For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (via consent) and the privileges of the currently signed-in user. Your app can never have more privileges than the signed-in user. Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. For more information about administrator roles, see [Assigning administrator roles in Azure Active Directory](https://docs.microsoft.com/azure/active-directory/active-directory-assign-admin-roles).
|
||||||
|
|
||||||
|
For example, assume your app has been granted the Machine.CollectForensics delegated permission. This permission nominally grants your app permission to collect investigation package from a machine. If the signed-in user has 'Alerts Investigation' permission, your app will be able to collect investigation package from a machine, if the machine belongs to a group the user is exposed to. However, if the signed-in user doesn't have 'Alerts Investigation' permission, your app won't be able to collect investigation package from any machine.
|
||||||
|
|
||||||
|
- For application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. For example, an app that has the Machine.CollectForensics application permission can collect investigation package from any machine in the organization.
|
||||||
|
|
||||||
|
|
||||||
|
## Related topics
|
||||||
|
- [Supported Windows Defender ATP APIs](exposed-apis-list.md)
|
||||||
|
- [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md)
|
||||||
|
- [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md)
|
||||||
@ -0,0 +1,44 @@
|
|||||||
|
---
|
||||||
|
title: Supported Windows Defender Advanced Threat Protection query APIs
|
||||||
|
description: Learn about the specific supported Windows Defender Advanced Threat Protection entities where you can create API calls to.
|
||||||
|
keywords: apis, supported apis, actor, alerts, machine, user, domain, ip, file, advanced queries, advanced hunting
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 30/07/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Supported Windows Defender ATP query APIs
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows 10 Enterprise
|
||||||
|
- Windows 10 Education
|
||||||
|
- Windows 10 Pro
|
||||||
|
- Windows 10 Pro Education
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
>Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-supportedapis-abovefoldlink)
|
||||||
|
|
||||||
|
Learn more about the individual supported entities where you can run API calls to and details such as HTTP request values, request headers and expected responses.
|
||||||
|
|
||||||
|
## In this section
|
||||||
|
Topic | Description
|
||||||
|
:---|:---
|
||||||
|
Advanced Hunting | Run queries from API.
|
||||||
|
Alerts | Run API calls such as get alerts, alert information by ID, alert related actor information, alert related IP information, and alert related machine information.
|
||||||
|
Domain |Run API calls such as get domain related machines, domain related machines, statistics, and check if a domain is seen in your organization.
|
||||||
|
File | Run API calls such as get file information, file related alerts, file related machines, and file statistics.
|
||||||
|
IP | Run API calls such as get IP related alerts, IP related machines, IP statistics, and check if and IP is seen in your organization.
|
||||||
|
Machines | Run API calls such as find machine information by IP, get machines, get machines by ID, information about logged on users, and alerts related to a given machine ID.
|
||||||
|
User | Run API calls such as get alert related user information, user information, user related alerts, and user related machines.
|
||||||
|
|
||||||
|
## Related topic
|
||||||
|
- [Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
@ -0,0 +1,49 @@
|
|||||||
|
---
|
||||||
|
title: File resource type
|
||||||
|
description: Retrieves top recent alerts.
|
||||||
|
keywords: apis, graph api, supported apis, get, alerts, recent
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# File resource type
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
Represent a file entity in WDATP.
|
||||||
|
|
||||||
|
# Methods
|
||||||
|
Method|Return Type |Description
|
||||||
|
:---|:---|:---
|
||||||
|
[Get file](get-file-information-windows-defender-advanced-threat-protection-new.md) | [file](files-windows-defender-advanced-threat-protection-new.md) | Get a single file
|
||||||
|
[List file related alerts](get-file-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | Get the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities that are associated with the file.
|
||||||
|
[List file related machines](get-file-related-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | Get the [machine](machine-windows-defender-advanced-threat-protection-new.md) entities associated with the alert.
|
||||||
|
[file statistics](get-file-statistics-windows-defender-advanced-threat-protection-new.md) | Statistics summary | Retrieves the prevalence for the given file.
|
||||||
|
|
||||||
|
|
||||||
|
# Properties
|
||||||
|
Property | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
sha1 | String | Sha1 hash of the file content
|
||||||
|
sha256 | String | Sha256 hash of the file content
|
||||||
|
md5 | String | md5 hash of the file content
|
||||||
|
globalPrevalence | Integer | File prevalence accross organization
|
||||||
|
globalFirstObserved | DateTimeOffset | First time the file was observed.
|
||||||
|
globalLastObserved | DateTimeOffset | Last time the file was observed.
|
||||||
|
size | Integer | Size of the file.
|
||||||
|
fileType | String | Type of the file.
|
||||||
|
isPeFile | Boolean | true if the file is portable executable (e.g. "DLL", "EXE", etc.)
|
||||||
|
filePublisher | String | File publisher.
|
||||||
|
fileProductName | String | Product name.
|
||||||
|
signer | String | File signer.
|
||||||
|
issuer | String | File issuer.
|
||||||
|
signerHash | String | Hash of the signing certificate.
|
||||||
|
isValidCertificate | Boolean | Was signing certificate successfully verified by WDATP agent.
|
||||||
|
|
||||||
@ -0,0 +1,88 @@
|
|||||||
|
---
|
||||||
|
title: Find machine information by internal IP API
|
||||||
|
description: Use this API to create calls related to finding a machine entry around a specific timestamp by internal IP.
|
||||||
|
keywords: ip, apis, graph api, supported apis, find machine, machine information
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: high
|
||||||
|
ms.date: 07/25/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Find machine information by internal IP API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
Find a machine by internal IP.
|
||||||
|
|
||||||
|
>[!NOTE]
|
||||||
|
>The timestamp must be within the last 30 days.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine profiles'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/machines/find(timestamp={time},key={IP})
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and machine exists - 200 OK.
|
||||||
|
If no machine found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://graph.microsoft.com/testwdatppreview/machines/find(timestamp=2018-06-19T10:00:00Z,key='10.166.93.61')
|
||||||
|
Content-type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
The response will return a list of all machines that reported this IP address within sixteen minutes prior and after the timestamp.
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://graph.microsoft.com/testwdatppreview/$metadata#Machines",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "04c99d46599f078f1c3da3783cf5b95f01ac61bb",
|
||||||
|
"computerDnsName": "",
|
||||||
|
"firstSeen": "2017-07-06T01:25:04.9480498Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
…
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,96 @@
|
|||||||
|
---
|
||||||
|
title: Get alert information by ID API
|
||||||
|
description: Retrieves an alert by its ID.
|
||||||
|
keywords: apis, graph api, supported apis, get, alert, information, id
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get alert information by ID API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves an alert by its ID.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Alert.Read.All | 'Read all alerts'
|
||||||
|
Application | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||||
|
Delegated (work or school account) | Alert.Read | 'Read alerts'
|
||||||
|
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/alerts/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 200 OK, and the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entity in the response body. If alert with the specified id was not found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
|
||||||
|
"id": "636688558380765161_2136280442",
|
||||||
|
"severity": "Informational",
|
||||||
|
"status": "InProgress",
|
||||||
|
"description": "Some alert description 1",
|
||||||
|
"recommendedAction": "Some recommended action 1",
|
||||||
|
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
|
||||||
|
"category": "General",
|
||||||
|
"title": "Some alert title 1",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "WindowsDefenderAtp",
|
||||||
|
"classification": "TruePositive",
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": "best secop ever",
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
@ -0,0 +1,85 @@
|
|||||||
|
---
|
||||||
|
title: Get alert related domains information
|
||||||
|
description: Retrieves all domains related to a specific alert.
|
||||||
|
keywords: apis, graph api, supported apis, get alert information, alert information, related domain
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get alert related domain information API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves all domains related to a specific alert.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | URL.Read.All | 'Read URLs'
|
||||||
|
Delegated (work or school account) | URL.Read.All | 'Read URLs'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/alerts/{id}/domains
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and alert and domain exist - 200 OK.
|
||||||
|
If alert not found or domain not found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/alerts/636688558380765161_2136280442/domains
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/$metadata#Domains",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"host": "www.example.com"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
@ -0,0 +1,98 @@
|
|||||||
|
---
|
||||||
|
title: Get alert related files information
|
||||||
|
description: Retrieves all files related to a specific alert.
|
||||||
|
keywords: apis, graph api, supported apis, get alert information, alert information, related files
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get alert related files information API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves all files related to a specific alert.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | File.Read.All | 'Read file profiles'
|
||||||
|
Delegated (work or school account) | File.Read.All | 'Read file profiles'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/alerts/{id}/files
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and alert and files exist - 200 OK.
|
||||||
|
If alert not found or files not found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/files
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"sha1": "654f19c41d9662cf86be21bf0af5a88c38c56a9d",
|
||||||
|
"sha256": "2f905feec2798cee6f63da2c26758d86bfeaab954c01e20ac7085bf55fedde87",
|
||||||
|
"md5": "82849dc81d94056224445ea73dc6153a",
|
||||||
|
"globalPrevalence": 33,
|
||||||
|
"globalFirstObserved": "2018-07-17T18:17:27.5909748Z",
|
||||||
|
"globalLastObserved": "2018-08-06T16:07:12.9414137Z",
|
||||||
|
"windowsDefenderAVThreatName": null,
|
||||||
|
"size": 801112,
|
||||||
|
"fileType": "PortableExecutable",
|
||||||
|
"isPeFile": true,
|
||||||
|
"filePublisher": null,
|
||||||
|
"fileProductName": null,
|
||||||
|
"signer": "Microsoft Windows",
|
||||||
|
"issuer": "Microsoft Development PCA 2014",
|
||||||
|
"signerHash": "9e284231a4d1c53fc8d4492b09f65116bf97447f",
|
||||||
|
"isValidCertificate": true
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,87 @@
|
|||||||
|
---
|
||||||
|
title: Get alert related IPs information
|
||||||
|
description: Retrieves all IPs related to a specific alert.
|
||||||
|
keywords: apis, graph api, supported apis, get alert information, alert information, related ip
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get alert related IP information API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves all IPs related to a specific alert.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Ip.Read.All | 'Read IP address profiles'
|
||||||
|
Delegated (work or school account) | Ip.Read.All | 'Read IP address profiles'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/alerts/{id}/ips
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and alert and an IP exist - 200 OK. If alert not found or IPs not found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/alerts/636688558380765161_2136280442/ips
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/$metadata#Ips",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "104.80.104.128"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "23.203.232.228
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
@ -0,0 +1,98 @@
|
|||||||
|
---
|
||||||
|
title: Get alert related machine information
|
||||||
|
description: Retrieves all machines related to a specific alert.
|
||||||
|
keywords: apis, graph api, supported apis, get alert information, alert information, related machine
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get alert related machine information API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves machine that is related to a specific alert.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine information'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
Delegated (work or school account) | Machine.Read | 'Read machine information'
|
||||||
|
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/alerts/{id}/machine
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and alert and machine exist - 200 OK.
|
||||||
|
If alert not found or machine not found - 404 Not Found.
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/machine
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines/$entity",
|
||||||
|
"id": "ff0c3800ed8d66738a514971cd6867166809369f",
|
||||||
|
"computerDnsName": "amazingmachine.contoso.com",
|
||||||
|
"firstSeen": "2017-12-10T07:47:34.4269783Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": "10.0.0.0",
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "172.17.0.0",
|
||||||
|
"lastExternalIpAddress": "167.220.0.0",
|
||||||
|
"agentVersion": "10.5830.17732.1001",
|
||||||
|
"groupName": "ContosoGroup",
|
||||||
|
"osBuild": 17732,
|
||||||
|
"healthStatus": "Active",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 75,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": "80fe8ff8-0000-0000-9591-41f0491218f9"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,89 @@
|
|||||||
|
---
|
||||||
|
title: Get alert related user information
|
||||||
|
description: Retrieves the user associated to a specific alert.
|
||||||
|
keywords: apis, graph api, supported apis, get, alert, information, related, user
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get alert related user information API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves the user associated to a specific alert.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | User.Read.All | 'Read user profiles'
|
||||||
|
Delegated (work or school account) | User.Read.All | 'Read user profiles'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/alerts/{id}/user
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and alert and a user exists - 200 OK with user in the body.
|
||||||
|
If alert not found or user not found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/user
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users/$entity",
|
||||||
|
"id": "contoso\\user1",
|
||||||
|
"firstSeen": "2018-08-02T00:00:00Z",
|
||||||
|
"lastSeen": "2018-08-04T00:00:00Z",
|
||||||
|
"mostPrevalentMachineId": null,
|
||||||
|
"leastPrevalentMachineId": null,
|
||||||
|
"logonTypes": "Network",
|
||||||
|
"logOnMachinesCount": 3,
|
||||||
|
"isDomainAdmin": false,
|
||||||
|
"isOnlyNetworkUser": null
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,127 @@
|
|||||||
|
---
|
||||||
|
title: List alerts API
|
||||||
|
description: Retrieves top recent alerts.
|
||||||
|
keywords: apis, graph api, supported apis, get, alerts, recent
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# List alerts API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves top recent alerts.
|
||||||
|
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Alert.Read.All | 'Read all alerts'
|
||||||
|
Application | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||||
|
Delegated (work or school account) | Alert.Read | 'Read alerts'
|
||||||
|
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Optional query parameters
|
||||||
|
Method supports $skip and $top query parameters.
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 200 OK, and a list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) objects in the response body. If no recent alerts found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
>[!NOTE]
|
||||||
|
>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "636688558380765161_2136280442",
|
||||||
|
"severity": "Informational",
|
||||||
|
"status": "InProgress",
|
||||||
|
"description": "Some alert description 1",
|
||||||
|
"recommendedAction": "Some recommended action 1",
|
||||||
|
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
|
||||||
|
"category": "General",
|
||||||
|
"title": "Some alert title 1",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "WindowsDefenderAtp",
|
||||||
|
"classification": "TruePositive",
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": "best secop ever",
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "636688558380765161_2136280442",
|
||||||
|
"severity": "Informational",
|
||||||
|
"status": "InProgress",
|
||||||
|
"description": "Some alert description 2",
|
||||||
|
"recommendedAction": "Some recommended action 2",
|
||||||
|
"alertCreationTime": "2018-08-04T01:17:17.9516179Z",
|
||||||
|
"category": "General",
|
||||||
|
"title": "Some alert title 2",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "WindowsDefenderAtp",
|
||||||
|
"classification": "TruePositive",
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": "best secop ever",
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-03T07:02:52.0894451Z",
|
||||||
|
"firstEventTime": "2018-08-03T07:02:52.0894451Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "ff0c3800ed8d66738a514971cd6867166809369d"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,123 @@
|
|||||||
|
---
|
||||||
|
title: Get domain related alerts API
|
||||||
|
description: Retrieves a collection of alerts related to a given domain address.
|
||||||
|
keywords: apis, graph api, supported apis, get, domain, related, alerts
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get domain related alerts API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves a collection of alerts related to a given domain address.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Alert.Read.All | 'Read all alerts'
|
||||||
|
Application | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||||
|
Delegated (work or school account) | Alert.Read | 'Read alerts'
|
||||||
|
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/domains/{domain}/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Header | Value
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and domain and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities. If domain or alert does not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/domains/client.wns.windows.com/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "636688558380765161_2136280442",
|
||||||
|
"severity": "Informational",
|
||||||
|
"status": "InProgress",
|
||||||
|
"description": "Some alert description 1",
|
||||||
|
"recommendedAction": "Some recommended action 1",
|
||||||
|
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
|
||||||
|
"category": "General",
|
||||||
|
"title": "Some alert title 1",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "WindowsDefenderAtp",
|
||||||
|
"classification": "TruePositive",
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": "best secop ever",
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "636688558380765161_2136280442",
|
||||||
|
"severity": "Informational",
|
||||||
|
"status": "InProgress",
|
||||||
|
"description": "Some alert description 2",
|
||||||
|
"recommendedAction": "Some recommended action 2",
|
||||||
|
"alertCreationTime": "2018-08-04T01:17:17.9516179Z",
|
||||||
|
"category": "General",
|
||||||
|
"title": "Some alert title 2",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "WindowsDefenderAtp",
|
||||||
|
"classification": "TruePositive",
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": "best secop ever",
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-03T07:02:52.0894451Z",
|
||||||
|
"firstEventTime": "2018-08-03T07:02:52.0894451Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "ff0c3800ed8d66738a514971cd6867166809369d"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
@ -0,0 +1,121 @@
|
|||||||
|
---
|
||||||
|
title: Get domain related machines API
|
||||||
|
description: Retrieves a collection of machines related to a given domain address.
|
||||||
|
keywords: apis, graph api, supported apis, get, domain, related, machines
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get domain related machines API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves a collection of machines that have communicated to or from a given domain address.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine profiles'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
Delegated (work or school account) | Machine.Read | 'Read machine information'
|
||||||
|
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/domains/{domain}/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and domain and machine exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities. If domain or machines do not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/domains/api.securitycenter.windows.com/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "02ea9a24e8bd39c247ed7ca0edae879c321684e5",
|
||||||
|
"computerDnsName": "testMachine1",
|
||||||
|
"firstSeen": "2018-07-30T20:12:00.3708661Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "10.209.67.177",
|
||||||
|
"lastExternalIpAddress": "167.220.1.210",
|
||||||
|
"agentVersion": "10.5830.18208.1000",
|
||||||
|
"groupName": null,
|
||||||
|
"osBuild": 18208,
|
||||||
|
"healthStatus": "Inactive",
|
||||||
|
"isAadJoined": false,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 75,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "02efb9a9b85f07749a018fbf3f962b4700b3b949",
|
||||||
|
"computerDnsName": "testMachine2",
|
||||||
|
"firstSeen": "2018-07-30T19:50:47.3618349Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "10.209.70.231",
|
||||||
|
"lastExternalIpAddress": "167.220.0.28",
|
||||||
|
"agentVersion": "10.5830.18208.1000",
|
||||||
|
"groupName": null,
|
||||||
|
"osBuild": 18208,
|
||||||
|
"healthStatus": "Inactive",
|
||||||
|
"isAadJoined": false,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 75,
|
||||||
|
"riskScore": "None",
|
||||||
|
"aadDeviceId": null
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,83 @@
|
|||||||
|
---
|
||||||
|
title: Get domain statistics API
|
||||||
|
description: Retrieves the prevalence for the given domain.
|
||||||
|
keywords: apis, graph api, supported apis, get, domain, domain related machines
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get domain statistics API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves the prevalence for the given domain.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | URL.Read.All | 'Read URLs'
|
||||||
|
Delegated (work or school account) | URL.Read.All | 'Read URLs'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/domains/{domain}/stats
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Header | Value
|
||||||
|
:---|:---
|
||||||
|
Authorization | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and domain exists - 200 OK, with statistics object in the response body.
|
||||||
|
If domain does not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/domains/example.com/stats
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgDomainStats",
|
||||||
|
"host": "example.com",
|
||||||
|
"orgPrevalence": "4070",
|
||||||
|
"orgFirstSeen": "2017-07-30T13:23:48Z",
|
||||||
|
"orgLastSeen": "2017-08-29T13:09:05Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,96 @@
|
|||||||
|
---
|
||||||
|
title: Get file information API
|
||||||
|
description: Retrieves a file by identifier Sha1, Sha256, or MD5.
|
||||||
|
keywords: apis, graph api, supported apis, get, file, information, sha1, sha256, md5
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get file information API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves a file by identifier Sha1, Sha256, or MD5.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | File.Read.All | 'Read all file profiles'
|
||||||
|
Delegated (work or school account) | File.Read.All | 'Read all file profiles'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/files/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and file exists - 200 OK with the [file](files-windows-defender-advanced-threat-protection-new.md) entity in the body.
|
||||||
|
If file does not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files/$entity",
|
||||||
|
"sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1",
|
||||||
|
"sha256": "d4447dffdbb2889b4b4e746b0bc882df1b854101614b0aa83953ef3cb66904cf",
|
||||||
|
"md5": "7f05a371d2beffb3784fd2199f81d730",
|
||||||
|
"globalPrevalence": 7329,
|
||||||
|
"globalFirstObserved": "2018-04-08T05:50:29.4459725Z",
|
||||||
|
"globalLastObserved": "2018-08-07T23:35:11.1361328Z",
|
||||||
|
"windowsDefenderAVThreatName": null,
|
||||||
|
"size": 391680,
|
||||||
|
"fileType": "PortableExecutable",
|
||||||
|
"isPeFile": true,
|
||||||
|
"filePublisher": null,
|
||||||
|
"fileProductName": null,
|
||||||
|
"signer": null,
|
||||||
|
"issuer": null,
|
||||||
|
"signerHash": null,
|
||||||
|
"isValidCertificate": null
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,103 @@
|
|||||||
|
---
|
||||||
|
title: Get file related alerts API
|
||||||
|
description: Retrieves a collection of alerts related to a given file hash.
|
||||||
|
keywords: apis, graph api, supported apis, get, file, hash
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get file related alerts API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves a collection of alerts related to a given file hash.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Alert.Read.All | 'Read all alerts'
|
||||||
|
Application | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||||
|
Delegated (work or school account) | Alert.Read | 'Read alerts'
|
||||||
|
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/files/{id}/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and file and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body.
|
||||||
|
If file or alerts do not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "636692391408655573_2010598859",
|
||||||
|
"severity": "Low",
|
||||||
|
"status": "New",
|
||||||
|
"description": "test alert",
|
||||||
|
"recommendedAction": "do this and that",
|
||||||
|
"alertCreationTime": "2018-08-07T11:45:40.0199932Z",
|
||||||
|
"category": "None",
|
||||||
|
"title": "test alert",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "CustomerTI",
|
||||||
|
"classification": null,
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": null,
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-03T16:45:21.7115182Z",
|
||||||
|
"firstEventTime": "2018-08-03T16:45:21.7115182Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,121 @@
|
|||||||
|
---
|
||||||
|
title: Get file related machines API
|
||||||
|
description: Retrieves a collection of machines related to a given file hash.
|
||||||
|
keywords: apis, graph api, supported apis, get, machines, hash
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get file related machines API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves a collection of machines related to a given file hash.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine profiles'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
Delegated (work or school account) | Machine.Read | 'Read machine information'
|
||||||
|
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/files/{id}/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and file and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body.
|
||||||
|
If file or machines do not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/files/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"computerDnsName": "mymachine1.contoso.com",
|
||||||
|
"firstSeen": "2018-08-02T14:55:03.7791856Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "172.17.230.209",
|
||||||
|
"lastExternalIpAddress": "167.220.196.71",
|
||||||
|
"agentVersion": "10.5830.18209.1001",
|
||||||
|
"groupName": null,
|
||||||
|
"osBuild": 18209,
|
||||||
|
"healthStatus": "Active",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 140,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
|
||||||
|
"computerDnsName": "mymachine2.contoso.com",
|
||||||
|
"firstSeen": "2018-07-09T13:22:45.1250071Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "192.168.12.225",
|
||||||
|
"lastExternalIpAddress": "79.183.65.82",
|
||||||
|
"agentVersion": "10.5820.17724.1000",
|
||||||
|
"groupName": "WDATPClientTeam",
|
||||||
|
"osBuild": 17724,
|
||||||
|
"healthStatus": "Inactive",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 140,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,88 @@
|
|||||||
|
---
|
||||||
|
title: Get file statistics API
|
||||||
|
description: Retrieves the prevalence for the given file.
|
||||||
|
keywords: apis, graph api, supported apis, get, file, statistics
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get file statistics API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves the prevalence for the given file.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | File.Read.All | 'Read file profiles'
|
||||||
|
Delegated (work or school account) | File.Read.All | 'Read file profiles'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/files/{id}/stats
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and file exists - 200 OK with statistical data in the body.
|
||||||
|
If file do not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/stats
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgFileStats",
|
||||||
|
"sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1",
|
||||||
|
"orgPrevalence": "3",
|
||||||
|
"orgFirstSeen": "2018-07-15T06:13:59Z",
|
||||||
|
"orgLastSeen": "2018-08-03T16:45:21Z",
|
||||||
|
"topFileNames": [
|
||||||
|
"chrome_1.exe",
|
||||||
|
"chrome_2.exe"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
@ -0,0 +1,104 @@
|
|||||||
|
---
|
||||||
|
title: Get IP related alerts API
|
||||||
|
description: Retrieves a collection of alerts related to a given IP address.
|
||||||
|
keywords: apis, graph api, supported apis, get, ip, related, alerts
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get IP related alerts API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Retrieves a collection of alerts related to a given IP address.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Alert.Read.All | 'Read all alerts'
|
||||||
|
Application | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||||
|
Delegated (work or school account) | Alert.Read | 'Read alerts'
|
||||||
|
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/ips/{ip}/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and IP and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body.
|
||||||
|
If IP and alerts do not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "636692391408655573_2010598859",
|
||||||
|
"severity": "Low",
|
||||||
|
"status": "New",
|
||||||
|
"description": "test alert",
|
||||||
|
"recommendedAction": "do this and that",
|
||||||
|
"alertCreationTime": "2018-08-07T11:45:40.0199932Z",
|
||||||
|
"category": "None",
|
||||||
|
"title": "test alert",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "CustomerTI",
|
||||||
|
"classification": null,
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": null,
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-03T16:45:21.7115182Z",
|
||||||
|
"firstEventTime": "2018-08-03T16:45:21.7115182Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,118 @@
|
|||||||
|
---
|
||||||
|
title: Get IP related machines API
|
||||||
|
description: Retrieves a collection of machines related to a given IP address.
|
||||||
|
keywords: apis, graph api, supported apis, get, ip, related, machines
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get IP related machines API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Retrieves a collection of machines that communicated with or from a particular IP.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine profiles'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
Delegated (work or school account) | Machine.Read | 'Read machine information'
|
||||||
|
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/ips/{ip}/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and IP and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body.
|
||||||
|
If IP or machines do not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"computerDnsName": "mymachine1.contoso.com",
|
||||||
|
"firstSeen": "2018-08-02T14:55:03.7791856Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "172.17.230.209",
|
||||||
|
"lastExternalIpAddress": "167.220.196.71",
|
||||||
|
"agentVersion": "10.5830.18209.1001",
|
||||||
|
"groupName": null,
|
||||||
|
"osBuild": 18209,
|
||||||
|
"healthStatus": "Active",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 140,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
|
||||||
|
"computerDnsName": "mymachine2.contoso.com",
|
||||||
|
"firstSeen": "2018-07-09T13:22:45.1250071Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "192.168.12.225",
|
||||||
|
"lastExternalIpAddress": "79.183.65.82",
|
||||||
|
"agentVersion": "10.5820.17724.1000",
|
||||||
|
"groupName": "WDATPClientTeam",
|
||||||
|
"osBuild": 17724,
|
||||||
|
"healthStatus": "Inactive",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 140,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -36,8 +36,7 @@ Content type | application/json
|
|||||||
Empty
|
Empty
|
||||||
|
|
||||||
## Response
|
## Response
|
||||||
If successful and IP and machines exists - 200 OK.
|
If successful and IP and machines exists - 200 OK. If IP or machines do not exist - 404 Not Found.
|
||||||
If IP or machines do not exist - 404 Not Found.
|
|
||||||
|
|
||||||
|
|
||||||
## Example
|
## Example
|
||||||
|
|||||||
@ -0,0 +1,80 @@
|
|||||||
|
---
|
||||||
|
title: Get IP statistics API
|
||||||
|
description: Retrieves the prevalence for the given IP.
|
||||||
|
keywords: apis, graph api, supported apis, get, ip, statistics, prevalence
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get IP statistics API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Retrieves the prevalence for the given IP.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Ip.Read.All | 'Read IP address profiles'
|
||||||
|
Delegated (work or school account) | Ip.Read.All | 'Read IP address profiles'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/ips/{ip}/stats
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and ip exists - 200 OK with statistical data in the body. IP do not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/stats
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgIPStats",
|
||||||
|
"ipAddress": "10.209.67.177",
|
||||||
|
"orgPrevalence": "63515",
|
||||||
|
"orgFirstSeen": "2017-07-30T13:36:06Z",
|
||||||
|
"orgLastSeen": "2017-08-29T13:32:59Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,97 @@
|
|||||||
|
---
|
||||||
|
title: Get machine by ID API
|
||||||
|
description: Retrieves a machine entity by ID.
|
||||||
|
keywords: apis, graph api, supported apis, get, machines, entity, id
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get machine by ID API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Retrieves a machine entity by ID.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine profiles'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
Delegated (work or school account) | Machine.Read | 'Read machine information'
|
||||||
|
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/machines/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and machine exists - 200 OK with the [machine](machine-windows-defender-advanced-threat-protection-new.md) entity in the body.
|
||||||
|
If machine with the specified id was not found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machine",
|
||||||
|
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"computerDnsName": "mymachine1.contoso.com",
|
||||||
|
"firstSeen": "2018-08-02T14:55:03.7791856Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "172.17.230.209",
|
||||||
|
"lastExternalIpAddress": "167.220.196.71",
|
||||||
|
"agentVersion": "10.5830.18209.1001",
|
||||||
|
"groupName": null,
|
||||||
|
"osBuild": 18209,
|
||||||
|
"healthStatus": "Active",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 140,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
@ -0,0 +1,101 @@
|
|||||||
|
---
|
||||||
|
title: Get machine log on users API
|
||||||
|
description: Retrieves a collection of logged on users.
|
||||||
|
keywords: apis, graph api, supported apis, get, machine, log on, users
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get machine log on users API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Retrieves a collection of logged on users.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | User.Read.All | 'Read user profiles'
|
||||||
|
Delegated (work or school account) | User.Read.All | 'Read user profiles'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/machines/{id}/logonusers
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and machine and user exist - 200 OK with list of [user](user-windows-defender-advanced-threat-protection-new.md) entities in the body
|
||||||
|
If no machine found or no users found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/logonusers
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "contoso\\user1",
|
||||||
|
"firstSeen": "2018-08-02T00:00:00Z",
|
||||||
|
"lastSeen": "2018-08-04T00:00:00Z",
|
||||||
|
"mostPrevalentMachineId": null,
|
||||||
|
"leastPrevalentMachineId": null,
|
||||||
|
"logonTypes": "Network",
|
||||||
|
"logOnMachinesCount": 3,
|
||||||
|
"isDomainAdmin": false,
|
||||||
|
"isOnlyNetworkUser": null
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "contoso\\user2",
|
||||||
|
"firstSeen": "2018-08-02T00:00:00Z",
|
||||||
|
"lastSeen": "2018-08-05T00:00:00Z",
|
||||||
|
"mostPrevalentMachineId": null,
|
||||||
|
"leastPrevalentMachineId": null,
|
||||||
|
"logonTypes": "Network",
|
||||||
|
"logOnMachinesCount": 3,
|
||||||
|
"isDomainAdmin": false,
|
||||||
|
"isOnlyNetworkUser": null
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,101 @@
|
|||||||
|
---
|
||||||
|
title: Get machine related alerts API
|
||||||
|
description: Retrieves a collection of alerts related to a given machine ID.
|
||||||
|
keywords: apis, graph api, supported apis, get, machines, related, alerts
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get machine related alerts API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Retrieves a collection of alerts related to a given machine ID.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Alert.Read.All | 'Read all alerts'
|
||||||
|
Application | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||||
|
Delegated (work or school account) | Alert.Read | 'Read alerts'
|
||||||
|
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/machines/{id}/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and machine and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body. If no machine or no alerts found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "636692391408655573_2010598859",
|
||||||
|
"severity": "Low",
|
||||||
|
"status": "New",
|
||||||
|
"description": "test alert",
|
||||||
|
"recommendedAction": "do this and that",
|
||||||
|
"alertCreationTime": "2018-08-07T11:45:40.0199932Z",
|
||||||
|
"category": "None",
|
||||||
|
"title": "test alert",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "CustomerTI",
|
||||||
|
"classification": null,
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": null,
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-03T16:45:21.7115182Z",
|
||||||
|
"firstEventTime": "2018-08-03T16:45:21.7115182Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,88 @@
|
|||||||
|
---
|
||||||
|
title: Get MachineAction object API
|
||||||
|
description: Use this API to create calls related to get machineaction object
|
||||||
|
keywords: apis, graph api, supported apis, machineaction object
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get machineAction API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Get action performed on a machine.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine profiles'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
Delegated (work or school account) | Machine.Read | 'Read machine information'
|
||||||
|
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/machineactions/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 200, Ok response code with a [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity. If machine action entity with the specified id was not found - 404 Not Found.
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/machineactions/2e9da30d-27f6-4208-81f2-9cd3d67893ba
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 Ok
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
|
||||||
|
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
|
||||||
|
"type": "RunAntiVirusScan",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": "Check machine for viruses due to alert 3212",
|
||||||
|
"status": "Succeeded",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:18:57.5511934Z"
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
@ -0,0 +1,161 @@
|
|||||||
|
---
|
||||||
|
title: List machineActions API
|
||||||
|
description: Use this API to create calls related to get machineactions collection
|
||||||
|
keywords: apis, graph api, supported apis, machineaction collection
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# List machineActions API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Gets collection of actions done on machines. Get MachineAction collection API supports [OData V4 queries](https://www.odata.org/documentation/odata-version-2-0/uri-conventions/#FilterSystemQueryOption).
|
||||||
|
|
||||||
|
## 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](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine profiles'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
Delegated (work or school account) | Machine.Read | 'Read machine information'
|
||||||
|
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/machineactions
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 200, Ok response code with a collection of [machineAction](machineaction-windows-defender-advanced-threat-protection-new.md) entities.
|
||||||
|
|
||||||
|
|
||||||
|
## Example 1
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request on an organization that has three MachineActions.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/machineactions
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 Ok
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "69dc3630-1ccc-4342-acf3-35286eec741d",
|
||||||
|
"type": "CollectInvestigationPackage",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": "test",
|
||||||
|
"status": "Succeeded",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:43:57.2011911Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:45:25.4049122Z"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
|
||||||
|
"type": "RunAntiVirusScan",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": "Check machine for viruses due to alert 3212",
|
||||||
|
"status": "Succeeded",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:18:57.5511934Z"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e",
|
||||||
|
"type": "UnrestrictCodeExecution",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": "test",
|
||||||
|
"status": "Succeeded",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:15:40.6052029Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:16:14.2899973Z"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example 2
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of a request that filters the MachineActions by machine ID and shows the latest two MachineActions.
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/machineactions?$filter=machineId eq 'f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f'&$top=2
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 Ok
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/testwdatppreview/$metadata#MachineActions",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "69dc3630-1ccc-4342-acf3-35286eec741d",
|
||||||
|
"type": "CollectInvestigationPackage",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": "test",
|
||||||
|
"status": "Succeeded",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:43:57.2011911Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:45:25.4049122Z"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
|
||||||
|
"type": "RunAntiVirusScan",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": "Check machine for viruses due to alert 3212",
|
||||||
|
"status": "Succeeded",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:18:57.5511934Z"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,117 @@
|
|||||||
|
---
|
||||||
|
title: List machines API
|
||||||
|
description: Retrieves a collection of recently seen machines.
|
||||||
|
keywords: apis, graph api, supported apis, get, machines
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# List machines API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Retrieves a collection of machines that have communicated with WDATP cloud on the last 30 days.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine profiles'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
Delegated (work or school account) | Machine.Read | 'Read machine information'
|
||||||
|
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. If no recent machines - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"computerDnsName": "mymachine1.contoso.com",
|
||||||
|
"firstSeen": "2018-08-02T14:55:03.7791856Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "172.17.230.209",
|
||||||
|
"lastExternalIpAddress": "167.220.196.71",
|
||||||
|
"agentVersion": "10.5830.18209.1001",
|
||||||
|
"groupName": null,
|
||||||
|
"osBuild": 18209,
|
||||||
|
"healthStatus": "Active",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 140,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
|
||||||
|
"computerDnsName": "mymachine2.contoso.com",
|
||||||
|
"firstSeen": "2018-07-09T13:22:45.1250071Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "192.168.12.225",
|
||||||
|
"lastExternalIpAddress": "79.183.65.82",
|
||||||
|
"agentVersion": "10.5820.17724.1000",
|
||||||
|
"groupName": "WDATPClientTeam",
|
||||||
|
"osBuild": 17724,
|
||||||
|
"healthStatus": "Inactive",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 140,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,81 @@
|
|||||||
|
---
|
||||||
|
title: Get package SAS URI API
|
||||||
|
description: Use this API to get a URI that allows downloading an investigation package.
|
||||||
|
keywords: apis, graph api, supported apis, get package, sas, uri
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get package SAS URI API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Get a URI that allows downloading of an [investigation package](collect-investigation-package-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.CollectForensics | 'Collect forensics'
|
||||||
|
Delegated (work or school account) | Machine.CollectForensics | 'Collect forensics'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/machineactions/{machine action id}/getPackageUri
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 200, Ok response code with object that holds the link to the package in the “value” parameter. This link is valid for a very short time and should be used immediately for downloading the package to a local storage.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/machineactions/7327b54fd718525cbca07dacde913b5ac3c85673/GetPackageUri
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 Ok
|
||||||
|
Content-type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Edm.String",
|
||||||
|
"value": "\"https://userrequests-us.securitycenter.windows.com:443/safedownload/WDATP_Investigation_Package.zip?token=gbDyj7y%2fbWGAZjn2sFiZXlliBTXOCVG7yiJ6mXNaQ9pLByC2Wxeno9mENsPFP3xMk5l%2bZiJXjLvqAyNEzUNROxoM2I1er9dxzfVeBsxSmclJjPsAx%2btiNyxSz1Ax%2b5jaT5cL5bZg%2b8wgbwY9urXbTpGjAKh6FB1e%2b0ypcWkPm8UkfOwsmtC%2biZJ2%2bPqnkkeQk7SKMNoAvmh9%2fcqDIPKXGIBjMa0D9auzypOqd8bQXp7p2BnLSH136BxST8n9IHR4PILvRjAYW9kvtHkBpBitfydAsUW4g2oDZSPN3kCLBOoo1C4w4Lkc9Bc3GNU2IW6dfB7SHcp7G9p4BDkeJl3VuDs6esCaeBorpn9FKJ%2fXo7o9pdcI0hUPZ6Ds9hiPpwPUtz5J29CBE3QAopCK%2fsWlf6OW2WyXsrNRSnF1tVE5H3wXpREzuhD7S4AIA3OIEZKzC4jIPLeMu%2bazZU9xGwuc3gICOaokbwMJiZTqcUuK%2fV9YdBdjdg8wJ16NDU96Pl6%2fgew2KYuk6Wo7ZuHotgHI1abcsvdlpe4AvixDbqcRJthsg2PpLRaFLm5av44UGkeK6TJpFvxUn%2f9fg6Zk5yM1KUTHb8XGmutoCM8U9er6AzXZlY0gGc3D3bQOg41EJZkEZLyUEbk1hXJB36ku2%2bW01cG71t7MxMBYz7%2bdXobxpdo%3d%3bRWS%2bCeoDfTyDcfH5pkCg6hYDmCOPr%2fHYQuaUWUBNVnXURYkdyOzVHqp%2fe%2f1BNyPdVoVkpQHpz1pPS3b5g9h7IMmNKCk5gFq5m2nPx6kk9EYtzx8Ndoa2m9Yj%2bSaf8zIFke86YnfQL4AYewsnQNJJh4wc%2bXxGlBq7axDcoiOdX91rKzVicH3GSBkFoLFAKoegWWsF%2fEDZcVpF%2fXUA1K8HvB6dwyfy4y0sAqnNPxYTQ97mG7yHhxPt4Pe9YF2UPPAJVuEf8LNlQ%2bWHC9%2f7msF6UUI4%2fca%2ftpjFs%2fSNeRE8%2fyQj21TI8YTF1SowvaJuDc1ivEoeopNNGG%2bGI%2fX0SckaVxU9Hdkh0zbydSlT5SZwbSwescs0IpzECitBbaLUz4aT8KTs8T0lvx8D7Te3wVsKAJ1r3iFMQZrlk%2bS1WW8rvac7oHRx2HKURn1v7fDIQWgJr9aNsNlFz4fLJ50T2qSHuuepkLVbe93Va072aMGhvr09WVKoTpAf1j2bcFZZU6Za5PxI32mr0k90FgiYFJ1F%2f1vRDrGwvWVWUkR3Z33m4g0gHa52W1FMxQY0TJIwbovD6FaSNDx7xhKZSd5IJ7r6P91Gez49PaZRcAZPjd%2bfbul3JNm1VqQPTLohT7wa0ymRiXpSST74xtFzuEBzNSNATdbngj3%2fwV4JesTjZjIj5Dc%3d%3blumqauVlFuuO8MQffZgs0tLJ4Fq6fpeozPTdDf8Ll6XLegi079%2b4mSPFjTK0y6eohstxdoOdom2wAHiZwk0u4KLKmRkfYOdT1wHY79qKoBQ3ZDHFTys9V%2fcwKGl%2bl8IenWDutHygn5IcA1y7GTZj4g%3d%3d\""
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
@ -0,0 +1,85 @@
|
|||||||
|
---
|
||||||
|
title: Get user information API
|
||||||
|
description: Retrieve a User entity by key such as user name or domain.
|
||||||
|
keywords: apis, graph api, supported apis, get, user, user information
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get user information API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Retrieve a User entity by key (user name or domain\user).
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | User.Read.All | 'Read all user profiles'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/users/{id}/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and user exists - 200 OK with [user](user-windows-defender-advanced-threat-protection-new.md) entity in the body. If user does not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/users/user1@contoso.com
|
||||||
|
Content-type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users/$entity",
|
||||||
|
"id": "user1@contoso.com",
|
||||||
|
"firstSeen": "2018-08-02T00:00:00Z",
|
||||||
|
"lastSeen": "2018-08-04T00:00:00Z",
|
||||||
|
"mostPrevalentMachineId": null,
|
||||||
|
"leastPrevalentMachineId": null,
|
||||||
|
"logonTypes": "Network",
|
||||||
|
"logOnMachinesCount": 3,
|
||||||
|
"isDomainAdmin": false,
|
||||||
|
"isOnlyNetworkUser": null
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,120 @@
|
|||||||
|
---
|
||||||
|
title: Get user related alerts API
|
||||||
|
description: Retrieves a collection of alerts related to a given user ID.
|
||||||
|
keywords: apis, graph api, supported apis, get, user, related, alerts
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get user related alerts API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Retrieves a collection of alerts related to a given user ID.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Alert.Read.All | 'Read all alerts'
|
||||||
|
Application | Alert.ReadWrite.All | 'Read and write all alerts'
|
||||||
|
Delegated (work or school account) | Alert.Read | 'Read alerts'
|
||||||
|
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/users/{id}/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and user and alert exists - 200 OK. If user or alerts does not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/users/user1@contoso.com/alerts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "636688558380765161_2136280442",
|
||||||
|
"severity": "Informational",
|
||||||
|
"status": "InProgress",
|
||||||
|
"description": "Some alert description 1",
|
||||||
|
"recommendedAction": "Some recommended action 1",
|
||||||
|
"alertCreationTime": "2018-08-03T01:17:17.9516179Z",
|
||||||
|
"category": "General",
|
||||||
|
"title": "Some alert title 1",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "WindowsDefenderAtp",
|
||||||
|
"classification": "TruePositive",
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": "best secop ever",
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"firstEventTime": "2018-08-02T07:02:52.0894451Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "ff0c3800ed8d66738a514971cd6867166809369f"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "636688558380765161_2136280442",
|
||||||
|
"severity": "Informational",
|
||||||
|
"status": "InProgress",
|
||||||
|
"description": "Some alert description 2",
|
||||||
|
"recommendedAction": "Some recommended action 2",
|
||||||
|
"alertCreationTime": "2018-08-04T01:17:17.9516179Z",
|
||||||
|
"category": "General",
|
||||||
|
"title": "Some alert title 2",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "WindowsDefenderAtp",
|
||||||
|
"classification": "TruePositive",
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": "best secop ever",
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-03T07:02:52.0894451Z",
|
||||||
|
"firstEventTime": "2018-08-03T07:02:52.0894451Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "ff0c3800ed8d66738a514971cd6867166809369d"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,118 @@
|
|||||||
|
---
|
||||||
|
title: Get user related machines API
|
||||||
|
description: Retrieves a collection of machines related to a given user ID.
|
||||||
|
keywords: apis, graph api, supported apis, get, user, user related alerts
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Get user related machines API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Retrieves a collection of machines related to a given user ID.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Read.All | 'Read all machine profiles'
|
||||||
|
Application | Machine.ReadWrite.All | 'Read and write all machine information'
|
||||||
|
Delegated (work or school account) | Machine.Read | 'Read machine information'
|
||||||
|
Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/users/{id}/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. If user or machines does not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/users/user1@contoso.com/machines
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
|
||||||
|
"value": [
|
||||||
|
{
|
||||||
|
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"computerDnsName": "mymachine1.contoso.com",
|
||||||
|
"firstSeen": "2018-08-02T14:55:03.7791856Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "172.17.230.209",
|
||||||
|
"lastExternalIpAddress": "167.220.196.71",
|
||||||
|
"agentVersion": "10.5830.18209.1001",
|
||||||
|
"groupName": null,
|
||||||
|
"osBuild": 18209,
|
||||||
|
"healthStatus": "Active",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 140,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
|
||||||
|
"computerDnsName": "mymachine2.contoso.com",
|
||||||
|
"firstSeen": "2018-07-09T13:22:45.1250071Z",
|
||||||
|
"osPlatform": "Windows10",
|
||||||
|
"osVersion": null,
|
||||||
|
"systemProductName": null,
|
||||||
|
"lastIpAddress": "192.168.12.225",
|
||||||
|
"lastExternalIpAddress": "79.183.65.82",
|
||||||
|
"agentVersion": "10.5820.17724.1000",
|
||||||
|
"groupName": "WDATPClientTeam",
|
||||||
|
"osBuild": 17724,
|
||||||
|
"healthStatus": "Inactive",
|
||||||
|
"isAadJoined": true,
|
||||||
|
"machineTags": [],
|
||||||
|
"rbacGroupId": 140,
|
||||||
|
"riskScore": "Low",
|
||||||
|
"aadDeviceId": null
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 62 KiB After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 65 KiB |
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: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.7 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 7.6 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 9.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 55 KiB |
@ -0,0 +1,23 @@
|
|||||||
|
---
|
||||||
|
title:
|
||||||
|
description:
|
||||||
|
keywords:
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 04/24/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Improve request performance
|
||||||
|
|
||||||
|
|
||||||
|
>[!NOTE]
|
||||||
|
>For better performance, you can use server closer to your geo location:
|
||||||
|
> - api-us.securitycenter.windows.com
|
||||||
|
> - api-eu.securitycenter.windows.com
|
||||||
|
> - api-uk.securitycenter.windows.com
|
||||||
@ -0,0 +1,77 @@
|
|||||||
|
---
|
||||||
|
title: Is domain seen in org API
|
||||||
|
description: Use this API to create calls related to checking whether a domain was seen in the organization.
|
||||||
|
keywords: apis, graph api, supported apis, domain, domain seen
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 04/24/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Was domain seen in org
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Answers whether a domain was seen in the organization.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Url.Read.All | 'Read URLs'
|
||||||
|
Delegated (work or school account) | URL.Read.All | 'Read URLs'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/domains/{domain}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Header | Value
|
||||||
|
:---|:---
|
||||||
|
Authorization | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and domain exists - 200 OK. If domain does not exist - 404 Not Found.
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/domains/example.com
|
||||||
|
Content-type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Domains/$entity",
|
||||||
|
"host": "example.com"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,77 @@
|
|||||||
|
---
|
||||||
|
title: Is IP seen in org API
|
||||||
|
description: Answers whether an IP was seen in the organization.
|
||||||
|
keywords: apis, graph api, supported apis, is, ip, seen, org, organization
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Was IP seen in org
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Answers whether an IP was seen in the organization.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Ip.Read.All | 'Read IP address profiles'
|
||||||
|
Delegated (work or school account) | Ip.Read.All | 'Read IP address profiles'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
GET /api/ips/{ip}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
Empty
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful and IP exists - 200 OK. If IP do not exist - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
```
|
||||||
|
GET https://api.securitycenter.windows.com/api/ips/10.209.67.177
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Ips/$entity",
|
||||||
|
"id": "10.209.67.177"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,102 @@
|
|||||||
|
---
|
||||||
|
title: Isolate machine API
|
||||||
|
description: Use this API to create calls related isolating a machine.
|
||||||
|
keywords: apis, graph api, supported apis, isolate machine
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Isolate machine API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Isolates a machine from accessing external network.
|
||||||
|
|
||||||
|
## 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](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Isolate | 'Isolate machine'
|
||||||
|
Delegated (work or school account) | Machine.Isolate | 'Isolate machine'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
POST /api/machines/{id}/isolate
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
Content-Type | string | application/json. **Required**.
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply a JSON object with the following parameters:
|
||||||
|
|
||||||
|
Parameter | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Comment | String | Comment to associate with the action. **Required**.
|
||||||
|
IsolationType | String | Type of the isolation. Allowed values are: 'Full' or 'Selective'.
|
||||||
|
|
||||||
|
**IsolationType** controls the type of isolation to perform and can be one of the following:
|
||||||
|
- Full – Full isolation
|
||||||
|
- Selective – Restrict only limited set of applications from accessing the network
|
||||||
|
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/isolate
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"Comment": "Isolate machine due to alert 1234",
|
||||||
|
“IsolationType”: “Full”
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 201 Created
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
|
||||||
|
"id": "b89eb834-4578-496c-8be0-03f004061435",
|
||||||
|
"type": "Isolate",
|
||||||
|
"requestor": "Analyst@contoso.com ",
|
||||||
|
"requestorComment": "Isolate machine due to alert 1234",
|
||||||
|
"status": "InProgress",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:12:18.9725659Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:12:18.9725659Z"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
To unisolate a machine, see [Release machine from isolation](unisolate-machine-windows-defender-advanced-threat-protection-new.md).
|
||||||
@ -0,0 +1,45 @@
|
|||||||
|
---
|
||||||
|
title: machine resource type
|
||||||
|
description: Retrieves top machines.
|
||||||
|
keywords: apis, supported apis, get, machines
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# machine resource type
|
||||||
|
|
||||||
|
|
||||||
|
# Methods
|
||||||
|
Method|Return Type |Description
|
||||||
|
:---|:---|:---
|
||||||
|
[List machines](get-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | List set of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the org.
|
||||||
|
[Get machine](get-machine-by-id-windows-defender-advanced-threat-protection.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) | Get a [machine](machine-windows-defender-advanced-threat-protection-new.md) by its identity.
|
||||||
|
[Get logged on users](get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md) | [user](user-windows-defender-advanced-threat-protection-new.md) collection | Get the set of [User](user-windows-defender-advanced-threat-protection-new.md) that logged on to the [machine](machine-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
[Get related alerts](get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | Get the set of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities that were raised on the [machine](machine-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
|
||||||
|
# Properties
|
||||||
|
Property | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
id | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) identity.
|
||||||
|
computerDnsName | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) fully qualified name.
|
||||||
|
firstSeen | DateTimeOffset | First date and time where the [machine](machine-windows-defender-advanced-threat-protection-new.md) was observed by WDATP.
|
||||||
|
osPlatform | String | OS platform.
|
||||||
|
osVersion | String | OS Version.
|
||||||
|
lastIpAddress | Ip | Last IP on local NIC on the [machine](machine-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
lastExternalIpAddress | Ip | Last IP through which the [machine](machine-windows-defender-advanced-threat-protection-new.md) accessed the internet.
|
||||||
|
agentVersion | String | Version of WDATP agent.
|
||||||
|
groupName | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) group name (when defined).
|
||||||
|
osBuild | Int | OS build number.
|
||||||
|
healthStatus | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) health status.
|
||||||
|
isAadJoined | Boolean | Is [machine](machine-windows-defender-advanced-threat-protection-new.md) AAD joined.
|
||||||
|
machineTags | String collection | Set of [machine](machine-windows-defender-advanced-threat-protection-new.md) tags.
|
||||||
|
rbacGroupId | Int | Group ID.
|
||||||
|
riskScore | String | Risk score as evaludated by WDATP. Possible values are: 'None', 'Low', 'Medium' and 'High'.
|
||||||
|
aadDeviceId | String | AAD Device ID (when [machine](machine-windows-defender-advanced-threat-protection-new.md) is Aad Joined).
|
||||||
@ -0,0 +1,42 @@
|
|||||||
|
---
|
||||||
|
title: machineAction resource type
|
||||||
|
description: Retrieves top recent machineActions.
|
||||||
|
keywords: apis, supported apis, get, machineaction, recent
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# MachineAction resource type
|
||||||
|
|
||||||
|
Method|Return Type |Description
|
||||||
|
:---|:---|:---
|
||||||
|
[List MachineActions](get-machineactions-collection-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | List [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entities.
|
||||||
|
[Get MachineAction](get-machineaction-object-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Get a single [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity.
|
||||||
|
[Collect investigation package](collect-investigation-package-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Collect investigation package from a [machine](machine-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
[Get investigation package SAS URI](get-package-sas-uri-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Get URI for downloading the investigation package.
|
||||||
|
[Isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Isolate [machine](machine-windows-defender-advanced-threat-protection-new.md) from network.
|
||||||
|
[Release machine from isolation](unisolate-machine-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Release [machine](machine-windows-defender-advanced-threat-protection-new.md) from Isolation.
|
||||||
|
[Restrict app execution](restrict-code-execution-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Restrict application execution.
|
||||||
|
[Remove app restriction](unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Remove application execution restriction.
|
||||||
|
[Run antivirus scan](run-av-scan-windows-defender-advanced-threat-protection-new.md) | [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Run an AV scan using Windows Defender (when applicable).
|
||||||
|
[Offboard machine](offboard-machine-api-windows-defender-advanced-threat-protection-new.md)|[Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) | Offboard [machine](machine-windows-defender-advanced-threat-protection-new.md) from WDATP.
|
||||||
|
|
||||||
|
# Properties
|
||||||
|
Property | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
id | Guid | Identity of the [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity.
|
||||||
|
type | String | Type of the action.
|
||||||
|
requestor | String | Identity of the person that executed the action.
|
||||||
|
requestorComment | String | Comment that was written when issuing the action.
|
||||||
|
status | String | Current status of the command. Possible values are: "InProgress", "Succeeded", "Failed" and "Cancelled".
|
||||||
|
error | String | Error code providing more insight as to what have caused the command to fail.
|
||||||
|
machineId | String | Id of the machine on which the action was executed.
|
||||||
|
creationDateTimeUtc | DateTimeOffset | The date and time when the action was created.
|
||||||
|
lastUpdateTimeUtc | DateTimeOffset | The last date and time when the action status was updated.
|
||||||
@ -0,0 +1,93 @@
|
|||||||
|
---
|
||||||
|
title: Offboard machine API
|
||||||
|
description: Use this API to offboard a machine from WDATP.
|
||||||
|
keywords: apis, graph api, supported apis, collect investigation package
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Offboard machine API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Offboard machine from WDATP.
|
||||||
|
|
||||||
|
## 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](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Offboard | 'Offboard machine'
|
||||||
|
Delegated (work or school account) | Machine.Offboard | 'Offboard machine'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
POST /api/machines/{id}/offboard
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
Content-Type | string | application/json. **Required**.
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply a JSON object with the following parameters:
|
||||||
|
|
||||||
|
Parameter | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Comment | String | Comment to associate with the action. **Required**.
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/offboard
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"Comment": "Offboard machine by automation"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 201 Created
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
|
||||||
|
"id": "c9042f9b-8483-4526-87b5-35e4c2532223",
|
||||||
|
"type": "OffboardMachine",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": "offboard machine by automation",
|
||||||
|
"status": "InProgress",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:09:24.1785079Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:09:24.1785079Z"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
@ -195,5 +195,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.
|
In general, if you know of a specific threat name, CVE, or KB, you can identify machines with unpatched vulnerabilities that might be leveraged by threats. This report also helps you determine whether machine-level mitigations are configured correctly on the machines and prioritize those that might need attention.
|
||||||
|
|
||||||
|
|
||||||
|
## Related topic
|
||||||
|
- [**Beta** Create custom Power BI reports](run-advanced-query-sample-power-bi-app-token.md)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@ -0,0 +1,96 @@
|
|||||||
|
---
|
||||||
|
title: Restrict app execution API
|
||||||
|
description: Use this API to create calls related to restricting an application from executing.
|
||||||
|
keywords: apis, graph api, supported apis, collect investigation package
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Restrict app execution API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Restrict execution of all applications on the machine except a predefined set (see [Response machine alerts](respond-machine-alerts-windows-defender-advanced-threat-protection.md) for more information)
|
||||||
|
|
||||||
|
## 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](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.RestrictExecution | 'Restrict code execution'
|
||||||
|
Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code execution'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
POST /api/machines/{id}/restrictCodeExecution
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
Content-Type | string | application/json. **Required**.
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply a JSON object with the following parameters:
|
||||||
|
|
||||||
|
Parameter | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Comment | String | Comment to associate with the action. **Required**.
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/restrictCodeExecution
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"Comment": "Restrict code execution due to alert 1234"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 201 Created
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
|
||||||
|
"id": "78d408d1-384c-4c19-8b57-ba39e378011a",
|
||||||
|
"type": "RestrictCodeExecution",
|
||||||
|
"requestor": "Analyst@contoso.com ",
|
||||||
|
"requestorComment": "Restrict code execution due to alert 1234",
|
||||||
|
"status": "InProgress",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:15:04.3825985Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:15:04.3825985Z"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
To remove code execution restriction from a machine, see [Remove app restriction](unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
|
||||||
@ -0,0 +1,145 @@
|
|||||||
|
---
|
||||||
|
title: Advanced Hunting API
|
||||||
|
description: Use this API to run advanced queries
|
||||||
|
keywords: apis, supported apis, advanced hunting, query
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 09/03/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Advanced hunting API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
This API allows you to run programatically queries that you are used to run from [Windows Defender ATP Portal](https://securitycenter.windows.com/hunting)
|
||||||
|
|
||||||
|
|
||||||
|
## Limitations
|
||||||
|
This API is a beta version only and is currently restricted
|
||||||
|
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 minutes every hour and 4 hours a day)
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | AdvancedQuery.Read.All | 'Run advanced queries'
|
||||||
|
Delegated (work or school account) | AdvancedQuery.Read | 'Run advanced queries'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
POST /advancedqueries/query
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Header | Value
|
||||||
|
:---|:---
|
||||||
|
Authorization | Bearer {token}. **Required**.
|
||||||
|
Content-Type | application/json
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply a JSON object with the following parameters:
|
||||||
|
|
||||||
|
Parameter | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Query | Text | The query to run. **Required**.
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 200 OK, and _QueryResponse_ object in the response body.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
Request
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
>[!NOTE]
|
||||||
|
>For better performance, you can use server closer to your geo location:
|
||||||
|
> - api-us.securitycenter.windows.com
|
||||||
|
> - api-eu.securitycenter.windows.com
|
||||||
|
> - api-uk.securitycenter.windows.com
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.securitycenter.windows.com/advancedqueries/query
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"Query":"ProcessCreationEvents
|
||||||
|
| where InitiatingProcessFileName =~ \"powershell.exe\"
|
||||||
|
| where ProcessCommandLine contains \"appdata\"
|
||||||
|
| project EventTime, FileName, InitiatingProcessFileName
|
||||||
|
| limit 2"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Response
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
>[!NOTE]
|
||||||
|
>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Content-Type: application/json
|
||||||
|
{
|
||||||
|
"Schema": [{
|
||||||
|
"Name": "EventTime",
|
||||||
|
"Type": "DateTime"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"Name": "FileName",
|
||||||
|
"Type": "String"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"Name": "InitiatingProcessFileName",
|
||||||
|
"Type": "String"
|
||||||
|
}],
|
||||||
|
"Results": [{
|
||||||
|
"EventTime": "2018-07-09T07:16:26.8017265",
|
||||||
|
"FileName": "csc.exe",
|
||||||
|
"InitiatingProcessFileName": "powershell.exe"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"EventTime": "2018-07-08T19:00:02.7798905",
|
||||||
|
"FileName": "gpresult.exe",
|
||||||
|
"InitiatingProcessFileName": "powershell.exe"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting:
|
||||||
|
|
||||||
|
- Error: (403) Forbidden
|
||||||
|
|
||||||
|
|
||||||
|
If you get this error when calling WDATP API, your token probably does not include the necessary permission.
|
||||||
|
|
||||||
|
Check [app permissions](exposed-apis-create-app-webapp.md#validate-the-token) or [delegated permissions](exposed-apis-create-app-nativeapp.md#validate-the-token) included in your token.
|
||||||
|
|
||||||
|
If the 'roles' section in the token does not include the necessary permission:
|
||||||
|
|
||||||
|
- The necessary permission to your app might not have been granted. For more information, see [Access Windows Defender ATP without a user](exposed-apis-create-app-webapp.md#create-an-app) or [Access Windows Defender ATP on behalf of a user](exposed-apis-create-app-nativeapp.md#create-an-app) or,
|
||||||
|
- The app was not authorized in the tenant, see [Application consent](exposed-apis-create-app-webapp.md#application-consent).
|
||||||
|
|
||||||
|
|
||||||
|
## Related topic
|
||||||
|
- [Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
- [Advanced Hunting from Portal](advanced-hunting-windows-defender-advanced-threat-protection.md)
|
||||||
|
- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
|
||||||
|
- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)
|
||||||
@ -0,0 +1,86 @@
|
|||||||
|
---
|
||||||
|
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
|
||||||
|
---
|
||||||
|
|
||||||
|
# Schedule Advanced Hunting using Microsoft Flow
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Schedule advanced query.
|
||||||
|
|
||||||
|
>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md).
|
||||||
|
|
||||||
|
## Use case
|
||||||
|
|
||||||
|
If you need to schedule an advanced query and use the results for follow up actions and processing, you can use [Microsoft Flow](https://flow.microsoft.com/) (or Logic Apps) for it!
|
||||||
|
|
||||||
|
## Define a flow to run query and parse results
|
||||||
|
|
||||||
|
You will find below a very basic flow example:
|
||||||
|
|
||||||
|
1. Define the trigger – Recurrence by time
|
||||||
|
|
||||||
|
2. Add an action – Select HTTP
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- Set method to be POST
|
||||||
|
- Uri is https://api.securitycenter.windows.com/advancedqueries/query or one of the region specific locations
|
||||||
|
- US: https://api-us.securitycenter.windows.com/advancedqueries/query
|
||||||
|
- Europe: https://api-eu.securitycenter.windows.com/advancedqueries/query
|
||||||
|
- United Kingdom: https://api-uk.securitycenter.windows.com/advancedqueries/query
|
||||||
|
- Add the Header: Content-Type application/json
|
||||||
|
- In the body write your query surrounded by single quotation mark (')
|
||||||
|
- In the Advanced options select Authentication to be Active Directory OAuth
|
||||||
|
- Set the Tenant with proper AAD Tenant Id
|
||||||
|
- Audience is https://securitycenter.onmicrosoft.com/windowsatpservice
|
||||||
|
- Client ID is your application ID
|
||||||
|
- Credential Type should be Secret
|
||||||
|
- Secret is the application secret generated in the Azure Active directory.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
3. You can use the "Parse JSON" action to get the schema of data – just "use sample payload to generate schema" and copy an output from of the expected result.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Expand the flow to use the query results
|
||||||
|
|
||||||
|
The below section shows how to use the parsed results to insert them in SQL database.
|
||||||
|
|
||||||
|
This is an example only, you could perform on your results any other action supported by Microsoft Flow.
|
||||||
|
|
||||||
|
- Add an 'Apply to each' action
|
||||||
|
- Select the Results json (which was an output of the last parse action)
|
||||||
|
- Add an 'Insert row' action – you will need to supply the connection details
|
||||||
|
- Select the table you want to update and define the mapping between the WD-ATP output to the SQL. Note it is possible to manipulate the data inside the flow. In the example I changed the type of the EventTime.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
The output in the SQL DB is getting updates and can be used for correlation with other data sources. You can now read from your table:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Full flow definition
|
||||||
|
|
||||||
|
You can find below the full definition
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 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)
|
||||||
@ -0,0 +1,134 @@
|
|||||||
|
---
|
||||||
|
title: Advanced Hunting API
|
||||||
|
description: Use this API to run advanced queries
|
||||||
|
keywords: apis, supported apis, advanced hunting, query
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 30/07/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create custom reports using Power BI (app authentication)
|
||||||
|
|
||||||
|
Run advanced queries and show results in Microsoft Power BI. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
|
||||||
|
|
||||||
|
In this section we share Power BI query sample to run a query using **application token**.
|
||||||
|
|
||||||
|
If you want to use **user token** instead please refer to [this](run-advanced-query-sample-power-bi-user-token.md) tutorial.
|
||||||
|
|
||||||
|
>**Prerequisite**: You first need to [create an app](exposed-apis-create-app-webapp.md).
|
||||||
|
|
||||||
|
## Run a query
|
||||||
|
|
||||||
|
- Open Microsoft Power BI
|
||||||
|
|
||||||
|
- Click **Get Data** > **Blank Query**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- 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://api.securitycenter.windows.com",
|
||||||
|
OAuthUrl = Text.Combine({"https://login.windows.net/", TenantId, "/oauth2/token"}, ""),
|
||||||
|
|
||||||
|
Resource = Text.Combine({"resource", Uri.EscapeDataString(ResourceAppIdUrl)}, "="),
|
||||||
|
ClientId = Text.Combine({"client_id", AppId}, "="),
|
||||||
|
ClientSecret = Text.Combine({"client_secret", Uri.EscapeDataString(AppSecret)}, "="),
|
||||||
|
GrantType = Text.Combine({"grant_type", "client_credentials"}, "="),
|
||||||
|
|
||||||
|
Body = Text.Combine({Resource, ClientId, ClientSecret, GrantType}, "&"),
|
||||||
|
|
||||||
|
AuthResponse= Json.Document(Web.Contents(OAuthUrl, [Content=Text.ToBinary(Body)])),
|
||||||
|
AccessToken= AuthResponse[access_token],
|
||||||
|
Bearer = Text.Combine({"Bearer", AccessToken}, " "),
|
||||||
|
|
||||||
|
AdvancedHuntingUrl = "https://api.securitycenter.windows.com/advancedqueries/query",
|
||||||
|
|
||||||
|
Response = Json.Document(Web.Contents(
|
||||||
|
AdvancedHuntingUrl,
|
||||||
|
[
|
||||||
|
Headers = [#"Content-Type"="application/json", #"Accept"="application/json", #"Authorization"=Bearer],
|
||||||
|
Content=Json.FromValue([#"Query"=Query])
|
||||||
|
]
|
||||||
|
)),
|
||||||
|
|
||||||
|
TypeMap = #table(
|
||||||
|
{ "Type", "PowerBiType" },
|
||||||
|
{
|
||||||
|
{ "Double", Double.Type },
|
||||||
|
{ "Int64", Int64.Type },
|
||||||
|
{ "Int32", Int32.Type },
|
||||||
|
{ "Int16", Int16.Type },
|
||||||
|
{ "UInt64", Number.Type },
|
||||||
|
{ "UInt32", Number.Type },
|
||||||
|
{ "UInt16", Number.Type },
|
||||||
|
{ "Byte", Byte.Type },
|
||||||
|
{ "Single", Single.Type },
|
||||||
|
{ "Decimal", Decimal.Type },
|
||||||
|
{ "TimeSpan", Duration.Type },
|
||||||
|
{ "DateTime", DateTimeZone.Type },
|
||||||
|
{ "String", Text.Type },
|
||||||
|
{ "Boolean", Logical.Type },
|
||||||
|
{ "SByte", Logical.Type },
|
||||||
|
{ "Guid", Text.Type }
|
||||||
|
}),
|
||||||
|
|
||||||
|
Schema = Table.FromRecords(Response[Schema]),
|
||||||
|
TypedSchema = Table.Join(Table.SelectColumns(Schema, {"Name", "Type"}), {"Type"}, TypeMap , {"Type"}),
|
||||||
|
Results = Response[Results],
|
||||||
|
Rows = Table.FromRecords(Results, Schema[Name]),
|
||||||
|
Table = Table.TransformColumnTypes(Rows, Table.ToList(TypedSchema, (c) => {c{0}, c{2}}))
|
||||||
|
|
||||||
|
in Table
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
- Click **Done**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- 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
|
||||||
|
- [Create custom Power BI reports with user authentication](run-advanced-query-sample-power-bi-user-token.md)
|
||||||
|
- [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)
|
||||||
@ -0,0 +1,112 @@
|
|||||||
|
---
|
||||||
|
title: Advanced Hunting API
|
||||||
|
description: Use this API to run advanced queries
|
||||||
|
keywords: apis, supported apis, advanced hunting, query
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 30/07/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create custom reports using Power BI (user authentication)
|
||||||
|
|
||||||
|
Run advanced queries and show results in Microsoft Power BI. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
|
||||||
|
|
||||||
|
In this section we share Power BI query sample to run a query using **user token**.
|
||||||
|
|
||||||
|
If you want to use **application token** instead please refer to [this](run-advanced-query-sample-power-bi-app-token.md) tutorial.
|
||||||
|
|
||||||
|
>**Prerequisite**: You first need to [create an app](exposed-apis-create-app-nativeapp.md).
|
||||||
|
|
||||||
|
## Run a query
|
||||||
|
|
||||||
|
- Open Microsoft Power BI
|
||||||
|
|
||||||
|
- Click **Get Data** > **Blank Query**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- Click **Advanced Editor**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- Copy the below and paste it in the editor, after you update the values of Query
|
||||||
|
|
||||||
|
```
|
||||||
|
let
|
||||||
|
|
||||||
|
Query = "MachineInfo | where EventTime > ago(7d) | summarize EventCount=count(), LastSeen=max(EventTime) by MachineId",
|
||||||
|
|
||||||
|
AdvancedHuntingUrl = "https://api.securitycenter.windows.com/advancedqueries/query",
|
||||||
|
|
||||||
|
Response = Json.Document(Web.Contents(
|
||||||
|
AdvancedHuntingUrl,
|
||||||
|
[
|
||||||
|
Query=[#"queryText"=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 **Organizational account** > **Sign in**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- Enter your credentials and wait to be signed in
|
||||||
|
|
||||||
|
- Click **Connect**
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- View the results of your query
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Related topic
|
||||||
|
- [Create custom Power BI reports with app authentication](run-advanced-query-sample-power-bi-app-token.md)
|
||||||
|
- [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)
|
||||||
@ -0,0 +1,113 @@
|
|||||||
|
---
|
||||||
|
title: Advanced Hunting API
|
||||||
|
description: Use this API to run advanced queries
|
||||||
|
keywords: apis, supported apis, advanced hunting, query
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 30/07/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Advanced Hunting using PowerShell
|
||||||
|
|
||||||
|
Run advanced queries using PowerShell. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
|
||||||
|
|
||||||
|
In this section we share PowerShell samples to retrieve a token and use it to run a query.
|
||||||
|
|
||||||
|
>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md).
|
||||||
|
|
||||||
|
## Preparation Instructions
|
||||||
|
|
||||||
|
- Open a PowerShell window.
|
||||||
|
- If your policy does not allow you to run the PowerShell commands, you can run the below command:
|
||||||
|
```
|
||||||
|
Set-ExecutionPolicy -ExecutionPolicy Bypass
|
||||||
|
```
|
||||||
|
|
||||||
|
>For more details, refer to [PowerShell documentation](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy)
|
||||||
|
|
||||||
|
## Get token
|
||||||
|
|
||||||
|
- Run the below
|
||||||
|
|
||||||
|
```
|
||||||
|
$tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here
|
||||||
|
$appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here
|
||||||
|
$appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here
|
||||||
|
|
||||||
|
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
|
||||||
|
$oAuthUri = "https://login.windows.net/$TenantId/oauth2/token"
|
||||||
|
$body = [Ordered] @{
|
||||||
|
resource = "$resourceAppIdUri"
|
||||||
|
client_id = "$appId"
|
||||||
|
client_secret = "$appSecret"
|
||||||
|
grant_type = 'client_credentials'
|
||||||
|
}
|
||||||
|
$response = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $body -ErrorAction Stop
|
||||||
|
$aadToken = $response.access_token
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
where
|
||||||
|
- $tenantId: ID of the tenant on behalf of which you want to run the query (i.e., the query will be run on the data of this tenant)
|
||||||
|
- $appId: ID of your AAD app (the app must have 'Run advanced queries' permission to WDATP)
|
||||||
|
- $appSecret: Secret of your AAD app
|
||||||
|
|
||||||
|
## Run query
|
||||||
|
|
||||||
|
Run the below
|
||||||
|
|
||||||
|
```
|
||||||
|
$query = 'RegistryEvents | limit 10' # Paste your own query here
|
||||||
|
|
||||||
|
$url = "https://api.securitycenter.windows.com/advancedqueries/query"
|
||||||
|
$headers = @{
|
||||||
|
'Content-Type' = 'application/json'
|
||||||
|
Accept = 'application/json'
|
||||||
|
Authorization = "Bearer $aadToken"
|
||||||
|
}
|
||||||
|
$body = ConvertTo-Json -InputObject @{ 'Query' = $query }
|
||||||
|
$webResponse = Invoke-WebRequest -Method Post -Uri $url -Headers $headers -Body $body -ErrorAction Stop
|
||||||
|
$response = $webResponse | ConvertFrom-Json
|
||||||
|
$results = $response.Results
|
||||||
|
$schema = $response.Schema
|
||||||
|
```
|
||||||
|
|
||||||
|
- $results contains the results of your query
|
||||||
|
- $schema contains the schema of the results of your query
|
||||||
|
|
||||||
|
### Complex queries
|
||||||
|
|
||||||
|
If you want to run complex queries (or multilines queries), save your query in a file and, instead of the first line in the above sample, run the below command:
|
||||||
|
|
||||||
|
```
|
||||||
|
$query = [IO.File]::ReadAllText("C:\myQuery.txt"); # Replace with the path to your file
|
||||||
|
```
|
||||||
|
|
||||||
|
## Work with query results
|
||||||
|
|
||||||
|
You can now use the query results.
|
||||||
|
|
||||||
|
To output the results of the query in CSV format in file file1.csv do the below:
|
||||||
|
|
||||||
|
```
|
||||||
|
$results | ConvertTo-Csv -NoTypeInformation | Set-Content file1.csv
|
||||||
|
```
|
||||||
|
|
||||||
|
To output the results of the query in JSON format in file file1.json do the below:
|
||||||
|
|
||||||
|
```
|
||||||
|
$results | ConvertTo-Json | Set-Content file1.json
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
## Related topic
|
||||||
|
- [Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
- [Advanced Hunting API](run-advanced-query-api.md)
|
||||||
|
- [Advanced Hunting using Python](run-advanced-query-sample-python.md)
|
||||||
|
- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)
|
||||||
@ -0,0 +1,142 @@
|
|||||||
|
---
|
||||||
|
title: Advanced Hunting API
|
||||||
|
description: Use this API to run advanced queries
|
||||||
|
keywords: apis, supported apis, advanced hunting, query
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 30/07/2018
|
||||||
|
---
|
||||||
|
|
||||||
|
# Advanced Hunting using Python
|
||||||
|
|
||||||
|
Run advanced queries using Python. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
|
||||||
|
|
||||||
|
In this section we share Python samples to retrieve a token and use it to run a query.
|
||||||
|
|
||||||
|
>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md).
|
||||||
|
|
||||||
|
## Get token
|
||||||
|
|
||||||
|
- Run the below
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
import json
|
||||||
|
import urllib.request
|
||||||
|
import urllib.parse
|
||||||
|
|
||||||
|
tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here
|
||||||
|
appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here
|
||||||
|
appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here
|
||||||
|
|
||||||
|
url = "https://login.windows.net/%s/oauth2/token" % (tenantId)
|
||||||
|
|
||||||
|
resourceAppIdUri = 'https://api.securitycenter.windows.com'
|
||||||
|
|
||||||
|
body = {
|
||||||
|
'resource' : resourceAppIdUri,
|
||||||
|
'client_id' : appId,
|
||||||
|
'client_secret' : appSecret,
|
||||||
|
'grant_type' : 'client_credentials'
|
||||||
|
}
|
||||||
|
|
||||||
|
data = urllib.parse.urlencode(body).encode("utf-8")
|
||||||
|
|
||||||
|
req = urllib.request.Request(url, data)
|
||||||
|
response = urllib.request.urlopen(req)
|
||||||
|
jsonResponse = json.loads(response.read())
|
||||||
|
aadToken = jsonResponse["access_token"]
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
where
|
||||||
|
- tenantId: ID of the tenant on behalf of which you want to run the query (i.e., the query will be run on the data of this tenant)
|
||||||
|
- appId: ID of your AAD app (the app must have 'Run advanced queries' permission to WDATP)
|
||||||
|
- appSecret: Secret of your AAD app
|
||||||
|
|
||||||
|
## Run query
|
||||||
|
|
||||||
|
Run the below
|
||||||
|
|
||||||
|
```
|
||||||
|
query = 'RegistryEvents | limit 10' # Paste your own query here
|
||||||
|
|
||||||
|
url = "https://api.securitycenter.windows.com/advancedqueries/query"
|
||||||
|
headers = {
|
||||||
|
'Content-Type' : 'application/json',
|
||||||
|
'Accept' : 'application/json',
|
||||||
|
'Authorization' : "Bearer " + aadToken
|
||||||
|
}
|
||||||
|
|
||||||
|
data = json.dumps({ 'Query' : query }).encode("utf-8")
|
||||||
|
|
||||||
|
req = urllib.request.Request(url, data, headers)
|
||||||
|
response = urllib.request.urlopen(req)
|
||||||
|
jsonResponse = json.loads(response.read())
|
||||||
|
schema = jsonResponse["Schema"]
|
||||||
|
results = jsonResponse["Results"]
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
- schema contains the schema of the results of your query
|
||||||
|
- results contains the results of your query
|
||||||
|
|
||||||
|
### Complex queries
|
||||||
|
|
||||||
|
If you want to run complex queries (or multilines queries), save your query in a file and, instead of the first line in the above sample, run the below command:
|
||||||
|
|
||||||
|
```
|
||||||
|
queryFile = open("D:\\Temp\\myQuery.txt", 'r') # Replace with the path to your file
|
||||||
|
query = queryFile.read()
|
||||||
|
queryFile.close()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Work with query results
|
||||||
|
|
||||||
|
You can now use the query results.
|
||||||
|
|
||||||
|
To iterate over the results do the below:
|
||||||
|
|
||||||
|
```
|
||||||
|
for result in results:
|
||||||
|
print(result) # Prints the whole result
|
||||||
|
print(result["EventTime"]) # Prints only the property 'EventTime' from the result
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
To output the results of the query in CSV format in file file1.csv do the below:
|
||||||
|
|
||||||
|
```
|
||||||
|
import csv
|
||||||
|
|
||||||
|
outputFile = open("D:\\Temp\\file1.csv", 'w')
|
||||||
|
output = csv.writer(outputFile)
|
||||||
|
output.writerow(results[0].keys())
|
||||||
|
for result in results:
|
||||||
|
output.writerow(result.values())
|
||||||
|
|
||||||
|
outputFile.close()
|
||||||
|
```
|
||||||
|
|
||||||
|
To output the results of the query in JSON format in file file1.json do the below:
|
||||||
|
|
||||||
|
```
|
||||||
|
outputFile = open("D:\\Temp\\file1.json", 'w')
|
||||||
|
json.dump(results, outputFile)
|
||||||
|
outputFile.close()
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
## Related topic
|
||||||
|
- [Windows Defender ATP APIs](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)
|
||||||
@ -0,0 +1,102 @@
|
|||||||
|
---
|
||||||
|
title: Run antivirus scan API
|
||||||
|
description: Use this API to create calls related to running an antivirus scan on a machine.
|
||||||
|
keywords: apis, graph api, supported apis, remove machine from isolation
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Run antivirus scan API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Initiate Windows Defender Antivirus scan on a machine.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Scan | 'Scan machine'
|
||||||
|
Delegated (work or school account) | Machine.Scan | 'Scan machine'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
POST /api/machines/{id}/runAntiVirusScan
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
Content-Type | string | application/json
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply a JSON object with the following parameters:
|
||||||
|
|
||||||
|
Parameter | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Comment | String | Comment to associate with the action. **Required**.
|
||||||
|
ScanType| String | Defines the type of the Scan. **Required**.
|
||||||
|
|
||||||
|
**ScanType** controls the type of scan to perform and can be one of the following:
|
||||||
|
|
||||||
|
- **Quick** – Perform quick scan on the machine
|
||||||
|
- **Full** – Perform full scan on the machine
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 201, Created response code and _MachineAction_ object in the response body.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runAntiVirusScan
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"Comment": "Check machine for viruses due to alert 3212",
|
||||||
|
“ScanType”: “Full”
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 201 Created
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
|
||||||
|
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
|
||||||
|
"type": "RunAntiVirusScan",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": "Check machine for viruses due to alert 3212",
|
||||||
|
"status": "InProgress",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:18:27.1293487Z"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
@ -0,0 +1,100 @@
|
|||||||
|
---
|
||||||
|
title: Release machine from isolation API
|
||||||
|
description: Use this API to create calls related to release a machine from isolation.
|
||||||
|
keywords: apis, graph api, supported apis, remove machine from isolation
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Release machine from isolation API
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Undo isolation of a machine.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.Isolate | 'Isolate machine'
|
||||||
|
Delegated (work or school account) | Machine.Isolate | 'Isolate machine'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
POST /api/machines/{id}/unisolate
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
Content-Type | string | application/json. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply a JSON object with the following parameters:
|
||||||
|
|
||||||
|
Parameter | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Comment | String | Comment to associate with the action. **Required**.
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/unisolate
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"Comment": "Unisolate machine since it was clean and validated"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
>[!NOTE]
|
||||||
|
>The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 201 Created
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
|
||||||
|
"id": "09a0f91e-a2eb-409d-af33-5577fe9bd558",
|
||||||
|
"type": "Unisolate",
|
||||||
|
"requestor": "Analyst@contoso.com ",
|
||||||
|
"requestorComment": "Unisolate machine since it was clean and validated ",
|
||||||
|
"status": "InProgress",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:13:15.0104931Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:13:15.0104931Z"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
To isolate a machine, see [Isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
|
||||||
@ -0,0 +1,95 @@
|
|||||||
|
---
|
||||||
|
title: Remove app restriction API
|
||||||
|
description: Use this API to create calls related to removing a restriction from applications from executing.
|
||||||
|
keywords: apis, graph api, supported apis, remove machine from isolation
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Remove app restriction API
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Enable execution of any application on the machine.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Machine.RestrictExecution | 'Restrict code execution'
|
||||||
|
Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code execution'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
POST /api/machines/{id}/unrestrictCodeExecution
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
Content-Type | string | application/json. **Required**.
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply a JSON object with the following parameters:
|
||||||
|
|
||||||
|
Parameter | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Comment | String | Comment to associate with the action. **Required**.
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 201 - Created response code and [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) in the response body.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/unrestrictCodeExecution
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"Comment": "Unrestrict code execution since machine was cleaned and validated"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 201 Created
|
||||||
|
Content-type: application/json
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
|
||||||
|
"id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e",
|
||||||
|
"type": "UnrestrictCodeExecution",
|
||||||
|
"requestor": "Analyst@contoso.com",
|
||||||
|
"requestorComment": "Unrestrict code execution since machine was cleaned and validated ",
|
||||||
|
"status": "InProgress",
|
||||||
|
"error": "None",
|
||||||
|
"machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
|
||||||
|
"creationDateTimeUtc": "2017-12-04T12:15:40.6052029Z",
|
||||||
|
"lastUpdateTimeUtc": "2017-12-04T12:15:40.6052029Z"
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
To restrict code execution on a machine, see [Restrict app execution](restrict-code-execution-windows-defender-advanced-threat-protection-new.md).
|
||||||
@ -0,0 +1,104 @@
|
|||||||
|
---
|
||||||
|
title: Get alert information by ID API
|
||||||
|
description: Retrieves an alert by its ID.
|
||||||
|
keywords: apis, graph api, supported apis, get, alert, information, id
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# Update alert
|
||||||
|
|
||||||
|
[!include[Prerelease information](prerelease.md)]
|
||||||
|
|
||||||
|
**Applies to:**
|
||||||
|
|
||||||
|
- Windows Defender Advanced Threat Protection (Windows Defender ATP)
|
||||||
|
|
||||||
|
Update the properties of an alert entity.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](exposed-apis-intro.md)
|
||||||
|
|
||||||
|
Permission type | Permission | Permission display name
|
||||||
|
:---|:---|:---
|
||||||
|
Application | Alerts.ReadWrite.All | 'Read and write all alerts'
|
||||||
|
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
|
||||||
|
|
||||||
|
## HTTP request
|
||||||
|
```
|
||||||
|
PATCH /api/alerts/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request headers
|
||||||
|
|
||||||
|
Name | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
Authorization | String | Bearer {token}. **Required**.
|
||||||
|
Content-Type | String | application/json. **Required**.
|
||||||
|
|
||||||
|
|
||||||
|
## Request body
|
||||||
|
In the request body, supply the values for the relevant fields that should be updated.Existing properties that are not included in the request body will maintain their previous values or be recalculated based on tchanges to other property values. For best performance you shouldn't include existing values that haven't change.
|
||||||
|
|
||||||
|
Property | Type | Description
|
||||||
|
:---|:---|:---
|
||||||
|
status | String | Specifies the current status of the alert. The property values are: 'New', 'InProgress' and 'Resolved'.
|
||||||
|
assignedTo | String | Owner of the alert
|
||||||
|
classification | String | Speficies the specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'.
|
||||||
|
determination | String | Specifies the determination of the alert. The property values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other'
|
||||||
|
|
||||||
|
|
||||||
|
## Response
|
||||||
|
If successful, this method returns 200 OK, and the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entity in the response body with the updated properties. If alert with the specified id was not found - 404 Not Found.
|
||||||
|
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
**Request**
|
||||||
|
|
||||||
|
Here is an example of the request.
|
||||||
|
|
||||||
|
[!include[Improve request performance](improverequestperformance-new.md)]
|
||||||
|
|
||||||
|
```
|
||||||
|
PATCH https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442
|
||||||
|
Content-Type: application/json
|
||||||
|
{
|
||||||
|
"assignedTo": "Our designated secop"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**
|
||||||
|
|
||||||
|
Here is an example of the response.
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts/$entity",
|
||||||
|
"id": "636688558380765161_2136280442",
|
||||||
|
"severity": "Medium",
|
||||||
|
"status": "InProgress",
|
||||||
|
"description": "An anomalous memory operation appears to be tampering with a process associated with the Windows Defender EDR sensor.",
|
||||||
|
"recommendedAction": "A. Validate the alert.\n1. Examine the process involved in the memory operation to determine whether the process and the observed activities are normal. \n2. Check for other suspicious activities in the machine timeline.\n3. Locate unfamiliar processes in the process tree. Check files for prevalence, their locations, and digital signatures.\n4. Submit relevant files for deep analysis and review file behaviors. \n5. Identify unusual system activity with system owners. \n\nB. Scope the incident. Find related machines, network addresses, and files in the incident graph. \n\nC. Contain and mitigate the breach. Stop suspicious processes, isolate affected machines, decommission compromised accounts or reset passwords, block IP addresses and URLs, and install security updates.\n\nD. Contact your incident response team, or contact Microsoft support for investigation and remediation services.",
|
||||||
|
"alertCreationTime": "2018-08-07T10:18:04.2665329Z",
|
||||||
|
"category": "Installation",
|
||||||
|
"title": "Possible sensor tampering in memory",
|
||||||
|
"threatFamilyName": null,
|
||||||
|
"detectionSource": "WindowsDefenderAtp",
|
||||||
|
"classification": null,
|
||||||
|
"determination": null,
|
||||||
|
"assignedTo": "Our designated secop",
|
||||||
|
"resolvedTime": null,
|
||||||
|
"lastEventTime": "2018-08-07T10:14:35.470671Z",
|
||||||
|
"firstEventTime": "2018-08-07T10:14:35.470671Z",
|
||||||
|
"actorName": null,
|
||||||
|
"machineId": "a2250e1cd215af1ea2818ef8d01a564f67542857"
|
||||||
|
}
|
||||||
|
```
|
||||||
@ -0,0 +1,23 @@
|
|||||||
|
---
|
||||||
|
title: File resource type
|
||||||
|
description: Retrieves top recent alerts.
|
||||||
|
keywords: apis, graph api, supported apis, get, alerts, recent
|
||||||
|
search.product: eADQiWindows 10XVcnh
|
||||||
|
ms.prod: w10
|
||||||
|
ms.mktglfcycl: deploy
|
||||||
|
ms.sitesec: library
|
||||||
|
ms.pagetype: security
|
||||||
|
ms.author: macapara
|
||||||
|
author: mjcaparas
|
||||||
|
ms.localizationpriority: medium
|
||||||
|
ms.date: 12/08/2017
|
||||||
|
---
|
||||||
|
|
||||||
|
# User resource type
|
||||||
|
|
||||||
|
Method|Return Type |Description
|
||||||
|
:---|:---|:---
|
||||||
|
[List User related alerts](get-user-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | List all the alerts that are associated with a [user](user-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
[List User related machines](get-user-related-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | List all the machines that were logged on by a [user](user-windows-defender-advanced-threat-protection-new.md).
|
||||||
|
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user