deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-05-12 13:27:23 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge pull request #1540 from MicrosoftDocs/master

Browse Source 
Publish 11/12/2019 3:31 PM PST
This commit is contained in:
Thomas Raya 2019-11-12 15:41:12 -08:00 committed by GitHub
commit 867ea30d03
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 143 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
windows/security/threat-protection/TOC.md
View File

@ -368,7 +368,7 @@
###### [Get access with user context](microsoft-defender-atp/exposed-apis-create-app-nativeapp.md)
##### [APIs]()
###### [Supported Microsoft Defender ATP query APIs](microsoft-defender-atp/exposed-apis-list.md)
###### [Supported Microsoft Defender ATP APIs](microsoft-defender-atp/exposed-apis-list.md)
###### [Advanced Hunting](microsoft-defender-atp/run-advanced-query-api.md)
###### [Alert]()

120
windows/security/threat-protection/microsoft-defender-atp/alerts.md
View File

@ -17,13 +17,13 @@ ms.topic: article
---
# Alert resource type
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
Represents an alert entity in Microsoft Defender ATP.
**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
# Methods
Method|Return Type |Description
- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
## Methods
Method |Return Type |Description
:---|:---|:---
[Get alert](get-alert-info-by-id.md) | [Alert](alerts.md) | Get a single [alert](alerts.md) object.
[List alerts](get-alerts.md) | [Alert](alerts.md) collection | List [alert](alerts.md) collection.
@ -35,49 +35,95 @@ Method|Return Type |Description
[Get related users](get-alert-related-user-info.md) | [User](user.md) | The [user](user.md) that is associated with the [alert](alerts.md).
# Properties
## Properties
Property | Type | Description
:---|:---|:---
id | String | Alert ID.
incidentId | String | The [Incident](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/view-incidents-queue) ID of the Alert.
title | String | Alert title.
description | String | Alert description.
alertCreationTime | Nullable DateTimeOffset | The date and time (in UTC) the alert was created.
lastEventTime | Nullable DateTimeOffset | The last occurrence of the event that triggered the alert on the same machine.
firstEventTime | Nullable DateTimeOffset | The first occurrence of the event that triggered the alert on that machine.
lastUpdateTime | Nullable DateTimeOffset | The first occurrence of the event that triggered the alert on that machine.
resolvedTime | Nullable DateTimeOffset | The date and time in which the status of the alert was changed to 'Resolved'.
incidentId | Nullable Long | The [Incident](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/view-incidents-queue) ID of the Alert.
investigationId | Nullable Long | The [Investigation](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/automated-investigations) ID related to the Alert.
investigationState | Nullable Enum | The current state of the [Investigation](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/automated-investigations). Possible values are: 'Unknown', 'Terminated', 'SuccessfullyRemediated', 'Benign', 'Failed', 'PartiallyRemediated', 'Running', 'PendingApproval', 'PendingResource', 'PartiallyInvestigated', 'TerminatedByUser', 'TerminatedBySystem', 'Queued', 'InnerFailure', 'PreexistingAlert', 'UnsupportedOs', 'UnsupportedAlertType', 'SuppressedAlert'.
assignedTo | String | Owner of the alert.
severity | Enum | Severity of the alert. Possible values are: 'UnSpecified', 'Informational', 'Low', 'Medium' and 'High'.
status | Enum | Specifies the current status of the alert. Possible values are: 'Unknown', 'New', 'InProgress' and 'Resolved'.
investigationState | Nullable Enum | The current state of the investigation. Possible values are: 'Unknown', 'Terminated', 'SuccessfullyRemediated', 'Benign Failed PartiallyRemediated', 'Running', 'PendingApproval', 'PendingResource', 'PartiallyInvestigated', 'TerminatedByUser', 'TerminatedBySystem', 'Queued', 'InnerFailure', 'PreexistingAlert', 'UnsupportedOs', 'UnsupportedAlertType', 'SuppressedAlert' .
classification | Nullable Enum | Specification of the alert. Possible values are: 'Unknown', 'FalsePositive', 'TruePositive'.
determination | Nullable Enum | Specifies the determination of the alert. Possible values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other'.
category| String | Category of the alert. Possible values are: 'Collection', 'Command and control', 'Credential access', 'Defense evasion', 'Discovery', 'Execution', 'Exfiltration', 'Exploit', 'Initial access', 'Lateral movement', 'Malware', 'Persistence', 'Privilege escalation', 'Ransomware', 'Suspicious activity', 'Unwanted software'.
detectionSource | string | Detection source.
threatFamilyName | string | Threat family.
title | string | Alert title.
description | String | Description of the threat, identified by the alert.
alertCreationTime | DateTimeOffset | The date and time (in UTC) the alert was created.
lastEventTime | DateTimeOffset | The last occurrence of the event that triggered the alert on the same machine.
firstEventTime | DateTimeOffset | The first occurrence of the event that triggered the alert on that machine.
resolvedTime | DateTimeOffset | The date and time in which the status of the alert was changed to 'Resolved'.
category| String | Category of the alert.
detectionSource | String | Detection source.
threatFamilyName | String | Threat family.
machineId | String | ID of a [machine](machine.md) entity that is associated with the alert.
comments | List of Alert comments | Alert Comment is an object that contains: comment string, createdBy string and createTime date time.
alertFiles | List of Alert Files | **This list will be populated on $expand option, see example below** Alert File is an object that contains: sha1, sha256, filePath and fileName.
alertIPs | List of Alert IPs | **This list will be populated on $expand option, see example below** Alert IP is an object that contains: ipAddress string field.
alertDomains | List of Alert Domains | **This list will be populated on $expand option, see example below** Alert Domain is an object that contains: host string field.
## JSON representation:
- When querying for alert list the regular way (without expand option, e.g. /api/alerts) the expandable properties will not get populated (empty lists)
- To expand expandable properties use $expand option (e.g. to expand all send /api/alerts?$expand=files,ips,domains).
- When querying single alert all expandable properties will be expanded.
- Check out [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md) for more OData examples.
### Response example for getting single alert:
# JSON representation
```
GET https://api.securitycenter.windows.com/api/alerts/da637084217856368682_-292920499
```
```json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"id": "121688558380765161_2136280442",
"incidentId": 7696,
"assignedTo": "secop@contoso.com",
"severity": "High",
"status": "New",
"classification": "TruePositive",
"determination": "Malware",
"investigationState": "Running",
"category": "MalwareDownload",
"detectionSource": "WindowsDefenderAv",
"threatFamilyName": "Mikatz",
"title": "Windows Defender AV detected 'Mikatz', high-severity malware",
"description": "Some description"
"alertCreationTime": "2018-11-26T16:19:21.8409809Z",
"firstEventTime": "2018-11-26T16:17:50.0948658Z",
"lastEventTime": "2018-11-26T16:18:01.809871Z",
"resolvedTime": null,
"machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
"id": "da637084217856368682_-292920499",
"incidentId": 66860,
"investigationId": 4416234,
"assignedTo": "secop@contoso.com",
"severity": "Low",
"status": "New",
"classification": "TruePositive",
"determination": null,
"investigationState": "Running",
"detectionSource": "WindowsDefenderAtp",
"category": "CommandAndControl",
"threatFamilyName": null,
"title": "Network connection to a risky host",
"description": "A network connection was made to a risky host which has exhibited malicious activity.",
"alertCreationTime": "2019-11-03T23:49:45.3823185Z",
"firstEventTime": "2019-11-03T23:47:16.2288822Z",
"lastEventTime": "2019-11-03T23:47:51.2966758Z",
"lastUpdateTime": "2019-11-03T23:55:52.6Z",
"resolvedTime": null,
"machineId": "986e5df8b73dacd43c8917d17e523e76b13c75cd",
"comments": [
{
"comment": "test comment for docs",
"createdBy": "secop@contoso.com",
"createdTime": "2019-11-05T14:08:37.8404534Z"
}
],
"alertFiles": [
{
"sha1": "77e862797dd525fd3e9c3058153247945d0d4cfd",
"sha256": "c05823562aee5e6d000b0e041197d5b8303f5aa4eecb49820879b705c926e16e",
"filePath": "C:\\Users\\test1212\\AppData\\Local\\Temp\\nsf61D3.tmp.exe",
"fileName": "nsf61D3.tmp.exe"
}
],
"alertDomains": [
{
"host": "login.bullguard.com"
}
],
"alertIps": [
{
"ipAddress": "91.231.212.53"
}
]
}
```

8
windows/security/threat-protection/microsoft-defender-atp/create-alert-by-reference.md
View File

@ -18,11 +18,11 @@ ms.topic: article
# Create alert from event API
**Applies to:**
**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
Enables using event data, as obtained from the [Advanced Hunting](run-advanced-query-api.md) for creating a new alert entity.
Create alert using event data, as obtained from [Advanced Hunting](run-advanced-query-api.md) for creating a new alert.
## Permissions
@ -64,7 +64,7 @@ description | String | Description of the alert. **Required**.
recommendedAction| String | Action that is recommended to be taken by security officer when analyzing the alert. **Required**.
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'.
category| String | Category of the alert. The property values are: "General", "CommandAndControl", "Collection", "CredentialAccess", "DefenseEvasion", "Discovery", "Exfiltration", "Exploit", "Execution", "InitialAccess", "LateralMovement", "Malware", "Persistence", "PrivilegeEscalation", "Ransomware", "SuspiciousActivity" **Required**.
## Response

27
windows/security/threat-protection/microsoft-defender-atp/exposed-apis-list.md
View File

@ -1,5 +1,5 @@
---
title: Supported Microsoft Defender Advanced Threat Protection query APIs
title: Supported Microsoft Defender Advanced Threat Protection APIs
ms.reviewer:
description: Learn about the specific supported Microsoft 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
@ -17,14 +17,11 @@ ms.collection: M365-security-compliance
ms.topic: article
---
# Supported Microsoft Defender ATP query APIs
# Supported Microsoft Defender ATP APIs
**Applies to:**
- Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)
**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
>Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-supportedapis-abovefoldlink)
- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
## End Point URI and Versioning
@ -42,7 +39,7 @@ ms.topic: article
>
> To use a specific version, use this format: https://api.securitycenter.windows.com/api/{Version}. For example: https://api.securitycenter.windows.com/api/v1.0/alerts
>
> If you don't specify any version (e.g., https://api.securitycenter.windows.com/api/alerts ) you will get to the latest version.
> If you don't specify any version (e.g. https://api.securitycenter.windows.com/api/alerts ) you will get to the latest version.
Learn more about the individual supported entities where you can run API calls to and details such as HTTP request values, request headers and expected responses.
@ -52,12 +49,14 @@ Learn more about the individual supported entities where you can run API calls t
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.
Alerts | Run API calls such as get alerts, create alert, update alert and more.
Domains | Run API calls such as get domain related machines, domain statistics and more.
Files | Run API calls such as get file information, file related alerts, file related machines, and file statistics.
IPs | Run API calls such as get IP related alerts and get IP statistics.
Machines | Run API calls such as get machines, get machines by ID, information about logged on users, edit tags and more.
Machine Actions | Run API call such as Isolation, Run anti-virus scan and more.
Indicators | Run API call such as create Indicator, get Indicators and delete Indicators.
Users | Run API calls such as get user related alerts and user related machines.
## Related topic
- [Microsoft Defender ATP APIs](apis-intro.md)

77
windows/security/threat-protection/microsoft-defender-atp/get-alerts.md
View File

@ -18,16 +18,15 @@ ms.topic: article
# List alerts API
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
Retrieves a collection of Alerts.
Supports [OData V4 queries](https://www.odata.org/documentation/).
The OData's Filter query is supported on: "Id", "IncidentId", "AlertCreationTime", "Status", "Severity" and "Category".
The OData's Filter query is supported on: "alertCreationTime", "incidentId", "InvestigationId", "status", "severity" and "category".
See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
@ -52,7 +51,8 @@ GET /api/alerts
```
## Optional query parameters
Method supports $skip and $top query parameters.
Method supports $top, $select, $filter, $expand and $skip query parameters.
<br>$expand is available on Files, IPs and Domains. e.g. $expand=files,domains
## Request headers
@ -74,18 +74,19 @@ If successful, this method returns 200 OK, and a list of [alert](alerts.md) obje
Here is an example of the request.
[!include[Improve request performance](improve-request-performance.md)]
```
GET https://api.securitycenter.windows.com/api/alerts
```
[!include[Improve request performance](improve-request-performance.md)]
**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.
>The response list shown here may be truncated for brevity. All alerts will be returned from an actual call.
```json
@ -93,45 +94,37 @@ Here is an example of the response.
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"value": [
{
"id": "121688558380765161_2136280442",
"incidentId": 7696,
"assignedTo": "secop@contoso.com",
"severity": "High",
"status": "New",
"classification": "TruePositive",
"determination": "Malware",
"investigationState": "Running",
"category": "MalwareDownload",
"detectionSource": "WindowsDefenderAv",
"threatFamilyName": "Mikatz",
"title": "Windows Defender AV detected 'Mikatz', high-severity malware",
"description": "Some description",
"alertCreationTime": "2018-11-26T16:19:21.8409809Z",
"firstEventTime": "2018-11-26T16:17:50.0948658Z",
"lastEventTime": "2018-11-26T16:18:01.809871Z",
"resolvedTime": null,
"machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
},
{
"id": "441688558380765161_2136280442",
"incidentId": 8633,
"id": "da637084217856368682_-292920499",
"incidentId": 66860,
"investigationId": 4416234,
"assignedTo": "secop@contoso.com",
"severity": "Low",
"status": "InProgress",
"status": "New",
"classification": "TruePositive",
"determination": "Malware",
"determination": null,
"investigationState": "Running",
"category": "MalwareDownload",
"detectionSource": "WindowsDefenderAv",
"threatFamilyName": "Mikatz",
"title": "Windows Defender AV detected 'Mikatz', high-severity malware",
"description": "Some description",
"alertCreationTime": "2018-11-25T16:19:21.8409809Z",
"firstEventTime": "2018-11-25T16:17:50.0948658Z",
"lastEventTime": "2018-11-25T16:18:01.809871Z",
"detectionSource": "WindowsDefenderAtp",
"category": "CommandAndControl",
"threatFamilyName": null,
"title": "Network connection to a risky host",
"description": "A network connection was made to a risky host which has exhibited malicious activity.",
"alertCreationTime": "2019-11-03T23:49:45.3823185Z",
"firstEventTime": "2019-11-03T23:47:16.2288822Z",
"lastEventTime": "2019-11-03T23:47:51.2966758Z",
"lastUpdateTime": "2019-11-03T23:55:52.6Z",
"resolvedTime": null,
"machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
}
"machineId": "986e5df8b73dacd43c8917d17e523e76b13c75cd",
"comments": [
{
"comment": "test comment for docs",
"createdBy": "secop@contoso.com",
"createdTime": "2019-11-05T14:08:37.8404534Z"
}
],
"alertFiles": [],
"alertDomains": [],
"alertIps": []
}
]
}
```

2
windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt
View File

@ -343,7 +343,7 @@
###### [Get access with user context](exposed-apis-create-app-nativeapp.md)
##### [APIs]()
###### [Supported Microsoft Defender ATP query APIs](exposed-apis-list.md)
###### [Supported Microsoft Defender ATP APIs](exposed-apis-list.md)
###### [Advanced Hunting](run-advanced-query-api.md)
###### [Alert]()

30
windows/security/threat-protection/microsoft-defender-atp/run-advanced-query-api.md
View File

@ -19,15 +19,14 @@ ms.topic: article
# Advanced hunting API
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
This API allows you to run programmatic queries that you are used to running from [Microsoft Defender ATP Portal](https://securitycenter.windows.com/hunting).
- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink)
## Limitations
1. You can only run a query on data from the last 30 days
2. The results will include a maximum of 10,000 rows
3. The number of executions is limited (up to 15 calls per minute, 15 minutes of running time every hour and 4 hours of running time a day)
1. You can only run a query on data from the last 30 days.
2. The results will include a maximum of 100,000 rows.
3. The number of executions is limited per tenant: up to 15 calls per minute, 15 minutes of running time every hour and 4 hours of running time a day.
4. The maximal execution time of a single request is 10 minutes.
## Permissions
@ -126,24 +125,7 @@ Content-Type: application/json​
}
```
## Troubleshoot issues
- Error: (403) Forbidden / (401) Unauthorized
~~~
If you get this error when calling Microsoft Defender ATP API, your token might not include the necessary permission.
Check [app permissions](exposed-apis-create-app-webapp.md#validate-the-token) or [delegated permissions](exposed-apis-create-app-nativeapp.md#validate-the-token) included in your token.
If the 'roles' section in the token does not include the necessary permission:
- The necessary permission to your app might not have been granted. For more information, see [Access Microsoft Defender ATP without a user](exposed-apis-create-app-webapp.md#create-an-app) or [Access Microsoft 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
- [Microsoft Defender ATP APIs](apis-intro.md)
- [Microsoft Defender ATP APIs introduction](apis-intro.md)
- [Advanced Hunting from Portal](advanced-hunting-query-language.md)
- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)