diff --git a/windows/security/threat-protection/TOC.md b/windows/security/threat-protection/TOC.md
index 7e2204a44a..1762f3ee06 100644
--- a/windows/security/threat-protection/TOC.md
+++ b/windows/security/threat-protection/TOC.md
@@ -406,7 +406,12 @@
####### [Run antivirus scan](microsoft-defender-atp/run-av-scan.md)
####### [Offboard machine](microsoft-defender-atp/offboard-machine-api.md)
####### [Stop and quarantine file](microsoft-defender-atp/stop-and-quarantine-file.md)
-####### [Initiate investigation (preview)](microsoft-defender-atp/initiate-autoir-investigation.md)
+
+###### [Automated Investigation]()
+####### [Investigation methods and properties](microsoft-defender-atp/investigation.md)
+####### [List Investigation](microsoft-defender-atp/get-investigation-collection.md)
+####### [Get Investigation](microsoft-defender-atp/get-investigation-object.md)
+####### [Start Investigation](microsoft-defender-atp/initiate-autoir-investigation.md)
###### [Indicators]()
####### [Indicators methods and properties](microsoft-defender-atp/ti-indicator.md)
diff --git a/windows/security/threat-protection/microsoft-defender-atp/add-or-remove-machine-tags.md b/windows/security/threat-protection/microsoft-defender-atp/add-or-remove-machine-tags.md
index d619963f4f..0e8ba41a5c 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/add-or-remove-machine-tags.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/add-or-remove-machine-tags.md
@@ -18,10 +18,19 @@ ms.topic: article
# Add or Remove Machine Tags 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)
+
+
+## API description
+Adds or remove tag to a specific [Machine](machine.md).
+
+
+## Limitations
+1. You can post on machines last seen in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-This API adds or remove tag to a specific machine.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -77,34 +86,4 @@ Content-type: application/json
"Action": "Add"
}
-```
-**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/$entity",
- "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
- "lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2" ]
-}
-
-```
-
- To remove machine tag, set the Action to 'Remove' instead of 'Add' in the request body.
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/alerts.md b/windows/security/threat-protection/microsoft-defender-atp/alerts.md
index 3bf7ffba39..62a32da91b 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/alerts.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/alerts.md
@@ -27,6 +27,7 @@ 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.
+[Update alert](get-alerts.md) | [Alert](update-alert.md) | Update specific [alert](alerts.md).
[Create alert](create-alert-by-reference.md)|[Alert](alerts.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.md)|Domain collection| List URLs associated with the alert.
[List related files](get-alert-related-files-info.md) | [File](files.md) collection | List the [file](files.md) entities that are associated with the [alert](alerts.md).
@@ -59,19 +60,8 @@ 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:
```
@@ -83,12 +73,12 @@ GET https://api.securitycenter.windows.com/api/alerts/da637084217856368682_-2929
"id": "da637084217856368682_-292920499",
"incidentId": 66860,
"investigationId": 4416234,
+ "investigationState": "Running",
"assignedTo": "secop@contoso.com",
"severity": "Low",
"status": "New",
"classification": "TruePositive",
"determination": null,
- "investigationState": "Running",
"detectionSource": "WindowsDefenderAtp",
"category": "CommandAndControl",
"threatFamilyName": null,
@@ -106,24 +96,6 @@ GET https://api.securitycenter.windows.com/api/alerts/da637084217856368682_-2929
"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"
- }
]
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/collect-investigation-package.md b/windows/security/threat-protection/microsoft-defender-atp/collect-investigation-package.md
index fbfaeaf1bc..1596496d14 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/collect-investigation-package.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/collect-investigation-package.md
@@ -18,11 +18,19 @@ ms.topic: article
---
# Collect investigation package 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)
+
+## API description
Collect investigation package from a machine.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -74,25 +82,3 @@ 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",
- "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
- "creationDateTimeUtc": "2018-12-04T12:09:24.1785079Z",
- "lastUpdateTimeUtc": "2018-12-04T12:09:24.1785079Z",
- "relatedFileInfo": null
-}
-
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/create-alert-by-reference.md b/windows/security/threat-protection/microsoft-defender-atp/create-alert-by-reference.md
index 077445f7c7..2e5c7cec45 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/create-alert-by-reference.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/create-alert-by-reference.md
@@ -16,13 +16,24 @@ ms.collection: M365-security-compliance
ms.topic: article
---
-# Create alert from event API
+# Create alert API
**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)
-Create alert using event data, as obtained from [Advanced Hunting](run-advanced-query-api.md) for creating a new alert.
+
+## API description
+Creates new [Alert](alerts.md).
+
Microsoft Defender ATP Event is a required parameter for the alert creation.
+
You can use an event found in Advanced Hunting API or Portal.
+
If there existing an open alert on the same Machine with the same Title, the new created alert will be merged with it.
+
An automatic investigation starts automatically on alerts created via the API.
+
+
+## Limitations
+1. Rate limitations for this API are 15 calls per minute.
+
## Permissions
diff --git a/windows/security/threat-protection/microsoft-defender-atp/delete-ti-indicator-by-id.md b/windows/security/threat-protection/microsoft-defender-atp/delete-ti-indicator-by-id.md
index 27ffb12de8..1c03a39e93 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/delete-ti-indicator-by-id.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/delete-ti-indicator-by-id.md
@@ -18,15 +18,18 @@ ms.topic: article
# Delete Indicator 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)
->[!Note]
-> Currently this API is only supported for AppOnly context requests. (See [Get access with application context](exposed-apis-create-app-webapp.md) for more information)
+## API description
+Deletes an [Indicator](ti-indicator.md) entity by ID.
-- Deletes an Indicator entity by ID.
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Get started](apis-intro.md)
@@ -66,15 +69,5 @@ If Indicator with the specified id was not found - 404 Not Found.
Here is an example of the request.
```
-DELETE https://api.securitycenter.windows.com/api/indicators/220e7d15b0b3d7fac48f2bd61114db1022197f7f
-```
-
-**Response**
-
-Here is an example of the response.
-
-
-```
-HTTP/1.1 204 NO CONTENT
-
+DELETE https://api.securitycenter.windows.com/api/indicators/995
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-odata-samples.md b/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-odata-samples.md
index fbcee47cf2..cb90cee7fe 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-odata-samples.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-odata-samples.md
@@ -51,25 +51,25 @@ Content-type: application/json
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
- "lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "High",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ]
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
+ "lastSeen": "2018-08-02T14:55:03.7791856Z",
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "Active",
+ "rbacGroupId": 140,
+ "rbacGroupName": "The-A-Team",
+ "riskScore": "Low",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "machineTags": [ "test tag 1", "ExampleTag" ]
},
- .
- .
- .
+ ...
]
}
```
@@ -79,7 +79,7 @@ Content-type: application/json
- Get all the alerts that created after 2018-10-20 00:00:00
```
-HTTP GET https://api.securitycenter.windows.com/api/alerts?$filter=alertCreationTime gt 2018-11-22T00:00:00Z
+HTTP GET https://api.securitycenter.windows.com/api/alerts?$filter=alertCreationTime+gt+2018-11-22T00:00:00Z
```
**Response:**
@@ -91,28 +91,35 @@ Content-type: application/json
"@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": "da637084217856368682_-292920499",
+ "incidentId": 66860,
+ "investigationId": 4416234,
+ "investigationState": "Running",
+ "assignedTo": "secop@contoso.com",
+ "severity": "Low",
+ "status": "New",
+ "classification": "TruePositive",
+ "determination": null,
+ "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"
+ }
+ ]
},
- .
- .
- .
+ ...
]
}
```
@@ -122,7 +129,7 @@ Content-type: application/json
- Get all the machines with 'High' 'RiskScore'
```
-HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=riskScore eq 'High'
+HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=riskScore+eq+'High'
```
**Response:**
@@ -135,25 +142,25 @@ Content-type: application/json
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
- "lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "High",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ]
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
+ "lastSeen": "2018-08-02T14:55:03.7791856Z",
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "Active",
+ "rbacGroupId": 140,
+ "rbacGroupName": "The-A-Team",
+ "riskScore": "High",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "machineTags": [ "test tag 1", "ExampleTag" ]
},
- .
- .
- .
+ ...
]
}
```
@@ -163,7 +170,7 @@ Content-type: application/json
- Get top 100 machines with 'HealthStatus' not equals to 'Active'
```
-HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=healthStatus ne 'Active'&$top=100
+HTTP GET https://api.securitycenter.windows.com/api/machines?$filter=healthStatus+ne+'Active'&$top=100
```
**Response:**
@@ -176,25 +183,25 @@ Content-type: application/json
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
- "lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "High",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ]
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
+ "lastSeen": "2018-08-02T14:55:03.7791856Z",
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "ImpairedCommunication",
+ "rbacGroupId": 140,
+ "rbacGroupName": "The-A-Team",
+ "riskScore": "Low",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "machineTags": [ "test tag 1", "ExampleTag" ]
},
- .
- .
- .
+ ...
]
}
```
@@ -217,25 +224,25 @@ Content-type: application/json
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
- "lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "High",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ]
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
+ "lastSeen": "2018-08-02T14:55:03.7791856Z",
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "ImpairedCommunication",
+ "rbacGroupId": 140,
+ "rbacGroupName": "The-A-Team",
+ "riskScore": "Low",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "machineTags": [ "test tag 1", "ExampleTag" ]
},
- .
- .
- .
+ ...
]
}
```
@@ -245,7 +252,7 @@ Content-type: application/json
- Get all the Anti-Virus scans that the user Analyst@examples.onmicrosoft.com created using Microsoft Defender ATP
```
-HTTP GET https://api.securitycenter.windows.com/api/machineactions?$filter=requestor eq 'Analyst@WcdTestPrd.onmicrosoft.com' and type eq 'RunAntiVirusScan'
+HTTP GET https://api.securitycenter.windows.com/api/machineactions?$filter=requestor eq 'Analyst@contoso.com' and type eq 'RunAntiVirusScan'
```
**Response:**
@@ -257,19 +264,19 @@ Content-type: application/json
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions",
"value": [
{
- "id": "5c3e3322-d993-1234-1111-dfb136ebc8c5",
+ "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan",
- "requestor": "Analyst@examples.onmicrosoft.com",
- "requestorComment": "1533",
+ "scope": "Full",
+ "requestor": "Analyst@contoso.com",
+ "requestorComment": "Check machine for viruses due to alert 3212",
"status": "Succeeded",
- "machineId": "123321c10e44a82877af76b1d0161a17843f688a",
- "creationDateTimeUtc": "2018-11-12T13:33:24.5755657Z",
- "lastUpdateDateTimeUtc": "2018-11-12T13:34:32.0319826Z",
- "relatedFileInfo": null
+ "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+ "computerDnsName": "desktop-39g9tgl",
+ "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
+ "lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
+ "relatedFileInfo": null
},
- .
- .
- .
+ ...
]
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/files.md b/windows/security/threat-protection/microsoft-defender-atp/files.md
index d4cc5e85cb..5ef6fc7ec4 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/files.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/files.md
@@ -17,9 +17,10 @@ ms.topic: article
---
# File resource type
-**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)
Represent a file entity in Microsoft Defender ATP.
@@ -37,11 +38,10 @@ 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 across organization
+globalPrevalence | Nullable long | File prevalence across organization
globalFirstObserved | DateTimeOffset | First time the file was observed.
globalLastObserved | DateTimeOffset | Last time the file was observed.
-size | Integer | Size of the file.
+size | Nullable long | 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.
@@ -50,3 +50,29 @@ signer | String | File signer.
issuer | String | File issuer.
signerHash | String | Hash of the signing certificate.
isValidCertificate | Boolean | Was signing certificate successfully verified by Microsoft Defender ATP agent.
+determinationType | String | The determination type of the file.
+determinationValue | String | Determination value.
+
+
+## Json representation
+
+```json
+{
+ "sha1": "4388963aaa83afe2042a46a3c017ad50bdcdafb3",
+ "sha256": "413c58c8267d2c8648d8f6384bacc2ae9c929b2b96578b6860b5087cd1bd6462",
+ "globalPrevalence": 180022,
+ "globalFirstObserved": "2017-09-19T03:51:27.6785431Z",
+ "globalLastObserved": "2020-01-06T03:59:21.3229314Z",
+ "size": 22139496,
+ "fileType": "APP",
+ "isPeFile": true,
+ "filePublisher": "CHENGDU YIWO Tech Development Co., Ltd.",
+ "fileProductName": "EaseUS MobiSaver for Android",
+ "signer": "CHENGDU YIWO Tech Development Co., Ltd.",
+ "issuer": "VeriSign Class 3 Code Signing 2010 CA",
+ "signerHash": "6c3245d4a9bc0244d99dff27af259cbbae2e2d16",
+ "isValidCertificate": false,
+ "determinationType": "Pua",
+ "determinationValue": "PUA:Win32/FusionCore"
+}
+```
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip.md b/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip.md
index c803a1d4de..5976574977 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip.md
@@ -18,13 +18,19 @@ ms.topic: article
# Find machines by internal IP 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)
-Find machines seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp.
-The given timestamp must be in the past 30 days.
+## API description
+Find [Machines](machine.md) seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp.
+
+
+## Limitations
+1. The given timestamp must be in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -70,37 +76,5 @@ Here is an example of the request.
[!include[Improve request performance](../../includes/improve-request-performance.md)]
```
-GET https://api.securitycenter.windows.com/api/machines/findbyip(ip='10.248.240.38',timestamp=2018-09-22T08:44:05Z)
-```
-
-**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",
- "lastSeen": "2018-09-22T08:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "10.248.240.38",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2" ]
- }
- ]
-}
+GET https://api.securitycenter.windows.com/api/machines/findbyip(ip='10.248.240.38',timestamp=2019-09-22T08:44:05Z)
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-alert-info-by-id.md b/windows/security/threat-protection/microsoft-defender-atp/get-alert-info-by-id.md
index d410e5fdb4..f065b2faab 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-alert-info-by-id.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-alert-info-by-id.md
@@ -18,11 +18,19 @@ ms.topic: article
# Get alert information by ID 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)
+
+
+## API description
+Retrieves specific [Alert](alerts.md) by its ID.
+
+
+## Limitations
+1. You can get alerts last updated in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -56,46 +64,3 @@ Empty
## Response
If successful, this method returns 200 OK, and the [alert](alerts.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](../../includes/improve-request-performance.md)]
-
-```
-GET https://api.securitycenter.windows.com/api/alerts/441688558380765161_2136280442
-```
-
-**Response**
-
-Here is an example of the response.
-
-
-```
-{
- "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
- "id": "441688558380765161_2136280442",
- "incidentId": 8633,
- "assignedTo": "secop@contoso.com",
- "severity": "Low",
- "status": "InProgress",
- "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-25T16:19:21.8409809Z",
- "firstEventTime": "2018-11-25T16:17:50.0948658Z",
- "lastEventTime": "2018-11-25T16:18:01.809871Z",
- "resolvedTime": null,
- "machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
-}
-
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-domain-info.md b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-domain-info.md
index 001e90c95f..bfafa218ea 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-domain-info.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-domain-info.md
@@ -18,12 +18,20 @@ ms.topic: article
# Get alert related domain information 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)
+
+## API description
Retrieves all domains related to a specific alert.
+
+## Limitations
+1. You can query on alerts last updated in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -79,7 +87,11 @@ Content-type: application/json
"value": [
{
"host": "www.example.com"
+ },
+ {
+ "host": "www.example2.com"
}
+ ...
]
}
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-files-info.md b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-files-info.md
index c8605dc7cd..89838eb90d 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-files-info.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-files-info.md
@@ -18,12 +18,20 @@ ms.topic: article
# Get alert related files information 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)
+
+## API description
Retrieves all files related to a specific alert.
+
+## Limitations
+1. You can query on alerts last updated in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -79,23 +87,25 @@ 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",
+ "sha1": "f2a00fd2f2de1be0214b8529f1e9f67096c1aa70",
+ "sha256": "dcd71ef5fff4362a9f64cf3f96f14f2b11d6f428f3badbedcb9ff3361e7079aa",
+ "md5": "8d5b7cc9a832e21d22503057e1fec8e9",
+ "globalPrevalence": 29,
+ "globalFirstObserved": "2019-03-23T23:54:06.0135204Z",
+ "globalLastObserved": "2019-04-23T00:43:20.0489831Z",
+ "size": 113984,
+ "fileType": null,
"isPeFile": true,
- "filePublisher": null,
- "fileProductName": null,
- "signer": "Microsoft Windows",
- "issuer": "Microsoft Development PCA 2014",
- "signerHash": "9e284231a4d1c53fc8d4492b09f65116bf97447f",
- "isValidCertificate": true
+ "filePublisher": "Microsoft Corporation",
+ "fileProductName": "Microsoft® Windows® Operating System",
+ "signer": "Microsoft Corporation",
+ "issuer": "Microsoft Code Signing PCA",
+ "signerHash": "9dc17888b5cfad98b3cb35c1994e96227f061675",
+ "isValidCertificate": true,
+ "determinationType": "Unknown",
+ "determinationValue": null
}
+ ...
]
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-ip-info.md b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-ip-info.md
index 69d6da0bf6..f012975e19 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-ip-info.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-ip-info.md
@@ -16,14 +16,22 @@ ms.collection: M365-security-compliance
ms.topic: article
---
-# Get alert related IP information API
+# Get alert related IPs information 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)
+
+## API description
Retrieves all IPs related to a specific alert.
+
+## Limitations
+1. You can query on alerts last updated in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -85,6 +93,7 @@ Content-type: application/json
{
"id": "23.203.232.228
}
+ ...
]
}
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-machine-info.md b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-machine-info.md
index bd98f47f1b..be84e2c9ca 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-machine-info.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-machine-info.md
@@ -18,11 +18,19 @@ ms.topic: article
# Get alert related machine information 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)
+
+
+## API description
+Retrieves [Machine](machine.md) related to a specific alert.
+
+
+## Limitations
+1. You can query on alerts last updated in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -85,15 +93,16 @@ Content-type: application/json
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
+ "version": "1709",
+ "osProcessor": "x64",
"lastIpAddress": "172.17.230.209",
"lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
"osBuild": 18209,
"healthStatus": "Active",
"rbacGroupId": 140,
"rbacGroupName": "The-A-Team",
"riskScore": "Low",
+ "exposureLevel": "Medium",
"isAadJoined": true,
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
"machineTags": [ "test tag 1", "test tag 2" ]
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-user-info.md b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-user-info.md
index ac8b284b43..d0e078abac 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-user-info.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-user-info.md
@@ -18,11 +18,19 @@ ms.topic: article
# Get alert related user information 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)
+
+
+## API description
+Retrieves the User related to a specific alert.
+
+
+## Limitations
+1. You can query on alerts last updated in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -80,13 +88,16 @@ 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,
+ "accountName": "user1",
+ "accountDomain": "contoso",
+ "accountSid": "S-1-5-21-72051607-1745760036-109187956-93922",
+ "firstSeen": "2019-12-08T06:33:39Z",
+ "lastSeen": "2020-01-05T06:58:34Z",
+ "mostPrevalentMachineId": "0111b647235c26159bec3e5eb6c8c3a0cc3ab766",
+ "leastPrevalentMachineId": "0111b647235c26159bec3e5eb6c8c3a0cc3ab766",
"logonTypes": "Network",
- "logOnMachinesCount": 3,
+ "logOnMachinesCount": 1,
"isDomainAdmin": false,
- "isOnlyNetworkUser": null
+ "isOnlyNetworkUser": false
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-alerts.md b/windows/security/threat-protection/microsoft-defender-atp/get-alerts.md
index b6056a66b3..33337c0f38 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-alerts.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-alerts.md
@@ -22,13 +22,19 @@ ms.topic: article
- 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)
+
+## API description
Retrieves a collection of Alerts.
+
Supports [OData V4 queries](https://www.odata.org/documentation/).
+
The OData's ```$filter``` query is supported on: ```alertCreationTime```, ```incidentId```, ```InvestigationId```, ```status```, ```severity``` and ```category``` properties.
+
See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
-Supports [OData V4 queries](https://www.odata.org/documentation/).
-The OData's Filter query is supported on: "alertCreationTime", "incidentId", "InvestigationId", "status", "severity" and "category".
+## Limitations
+1. You can get alerts last updated in the past 30 days.
+2. Maximum page size is 10,000.
+3. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -50,10 +56,6 @@ Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
GET /api/alerts
```
-## Optional query parameters
-Method supports $top, $select, $filter, $expand and $skip query parameters.
-
$expand is available on Files, IPs and Domains. e.g. $expand=files,domains
-
## Request headers
Name | Type | Description
@@ -120,11 +122,9 @@ Here is an example of the response.
"createdBy": "secop@contoso.com",
"createdTime": "2019-11-05T14:08:37.8404534Z"
}
- ],
- "alertFiles": [],
- "alertDomains": [],
- "alertIps": []
+ ]
}
+ ...
]
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-cvekbmap-collection.md b/windows/security/threat-protection/microsoft-defender-atp/get-cvekbmap-collection.md
index 07b687504d..4207a4cc3b 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-cvekbmap-collection.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-cvekbmap-collection.md
@@ -15,6 +15,7 @@ manager: dansimp
audience: ITPro
ms.collection: M365-security-compliance
ms.topic: article
+ROBOTS: NOINDEX
---
# Get CVE-KB map API
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-domain-related-alerts.md b/windows/security/threat-protection/microsoft-defender-atp/get-domain-related-alerts.md
index f835f9bc06..73b5a29c5d 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-domain-related-alerts.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-domain-related-alerts.md
@@ -18,11 +18,19 @@ ms.topic: article
# Get domain related alerts 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)
+
+
+## API description
+Retrieves a collection of [Alerts](alerts.md) related to a given domain address.
+
+
+## Limitations
+1. You can query on alerts last updated in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -68,58 +76,3 @@ Here is an example of the request.
```
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": "441688558380765161_2136280442",
- "incidentId": 8633,
- "assignedTo": "secop@contoso.com",
- "severity": "Low",
- "status": "InProgress",
- "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-25T16:19:21.8409809Z",
- "firstEventTime": "2018-11-25T16:17:50.0948658Z",
- "lastEventTime": "2018-11-25T16:18:01.809871Z",
- "resolvedTime": null,
- "machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
- },
- {
- "id": "121688558380765161_2136280442",
- "incidentId": 4123,
- "assignedTo": "secop@contoso.com",
- "severity": "Low",
- "status": "InProgress",
- "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-24T16:19:21.8409809Z",
- "firstEventTime": "2018-11-24T16:17:50.0948658Z",
- "lastEventTime": "2018-11-24T16:18:01.809871Z",
- "resolvedTime": null,
- "machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
- }
- ]
-}
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-domain-related-machines.md b/windows/security/threat-protection/microsoft-defender-atp/get-domain-related-machines.md
index 3d5d3cd534..b8b6be1268 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-domain-related-machines.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-domain-related-machines.md
@@ -17,10 +17,20 @@ ms.topic: article
---
# Get domain related machines API
-**Applies to:**
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-Retrieves a collection of machines that have communicated to or from a given domain address.
+**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)
+
+
+## API description
+Retrieves a collection of [Machines](machine.md) that have communicated to or from a given domain address.
+
+
+## Limitations
+1. You can query on machines last seen in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -68,54 +78,3 @@ Here is an example of the request.
```
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": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
- "lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2" ]
- },
- {
- "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
- "computerDnsName": "mymachine2.contoso.com",
- "firstSeen": "2018-07-09T13:22:45.1250071Z",
- "lastSeen": "2018-07-09T13:22:45.1250071Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "192.168.12.225",
- "lastExternalIpAddress": "79.183.65.82",
- "agentVersion": "10.5820.17724.1000",
- "osBuild": 17724,
- "healthStatus": "Inactive",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": null,
- "machineTags": [ "test tag 1" ]
- }
- ]
-}
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-domain-statistics.md b/windows/security/threat-protection/microsoft-defender-atp/get-domain-statistics.md
index a74fa5c9ca..77725715cd 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-domain-statistics.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-domain-statistics.md
@@ -18,10 +18,18 @@ ms.topic: article
# Get domain statistics 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)
+
+
+## API description
+Retrieves the statistics on the given domain.
+
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-file-information.md b/windows/security/threat-protection/microsoft-defender-atp/get-file-information.md
index 0c499a7062..db2c9f018f 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-file-information.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-file-information.md
@@ -17,10 +17,19 @@ ms.topic: article
---
# Get file information API
-**Applies to:**
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-Retrieves a file by identifier Sha1, Sha256, or MD5.
+**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)
+
+
+## API description
+Retrieves a [File](files.md) by identifier Sha1, or Sha256
+
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -62,7 +71,7 @@ Here is an example of the request.
[!include[Improve request performance](../../includes/improve-request-performance.md)]
```
-GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1
+GET https://api.securitycenter.windows.com/api/files/4388963aaa83afe2042a46a3c017ad50bdcdafb3
```
**Response**
@@ -74,22 +83,22 @@ 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
+ "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files/$entity",
+ "sha1": "4388963aaa83afe2042a46a3c017ad50bdcdafb3",
+ "sha256": "413c58c8267d2c8648d8f6384bacc2ae9c929b2b96578b6860b5087cd1bd6462",
+ "globalPrevalence": 180022,
+ "globalFirstObserved": "2017-09-19T03:51:27.6785431Z",
+ "globalLastObserved": "2020-01-06T03:59:21.3229314Z",
+ "size": 22139496,
+ "fileType": "APP",
+ "isPeFile": true,
+ "filePublisher": "CHENGDU YIWO Tech Development Co., Ltd.",
+ "fileProductName": "EaseUS MobiSaver for Android",
+ "signer": "CHENGDU YIWO Tech Development Co., Ltd.",
+ "issuer": "VeriSign Class 3 Code Signing 2010 CA",
+ "signerHash": "6c3245d4a9bc0244d99dff27af259cbbae2e2d16",
+ "isValidCertificate": false,
+ "determinationType": "Pua",
+ "determinationValue": "PUA:Win32/FusionCore"
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-file-related-alerts.md b/windows/security/threat-protection/microsoft-defender-atp/get-file-related-alerts.md
index 3f6ac44dd3..146a80fcf6 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-file-related-alerts.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-file-related-alerts.md
@@ -18,12 +18,19 @@ ms.topic: article
# Get file related alerts 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)
+
+## API description
Retrieves a collection of alerts related to a given file hash.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -69,38 +76,3 @@ Here is an example of the request.
```
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": "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"
- }
- ]
-}
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-file-related-machines.md b/windows/security/threat-protection/microsoft-defender-atp/get-file-related-machines.md
index de5d6837e9..a1e522151c 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-file-related-machines.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-file-related-machines.md
@@ -18,11 +18,18 @@ ms.topic: article
# Get file related machines 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)
+
+
+## API description
+Retrieves a collection of [Machines](machine.md) related to a given file hash.
+
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-- 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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -69,52 +76,3 @@ Here is an example of the request.
```
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",
- "lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "riskScore": "Low",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2" ]
- },
- {
- "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
- "computerDnsName": "mymachine2.contoso.com",
- "firstSeen": "2018-07-09T13:22:45.1250071Z",
- "lastSeen": "2018-07-09T13:22:45.1250071Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "192.168.12.225",
- "lastExternalIpAddress": "79.183.65.82",
- "agentVersion": "10.5820.17724.1000",
- "osBuild": 17724,
- "healthStatus": "Inactive",
- "rbacGroupId": 140,
- "riskScore": "Low",
- "aadDeviceId": null,
- "machineTags": [ "test tag 1" ]
- }
- ]
-}
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-file-statistics.md b/windows/security/threat-protection/microsoft-defender-atp/get-file-statistics.md
index 5f2cfec15b..b6abc23c5f 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-file-statistics.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-file-statistics.md
@@ -18,11 +18,18 @@ ms.topic: article
# Get file statistics 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)
+
+
+## API description
+Retrieves the statistics for the given file.
+
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -64,7 +71,7 @@ Here is an example of the request.
[!include[Improve request performance](../../includes/improve-request-performance.md)]
```
-GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/stats
+GET https://api.securitycenter.windows.com/api/files/0991a395da64e1c5fbe8732ed11e6be064081d9f/stats
```
**Response**
@@ -77,13 +84,15 @@ 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",
+ "sha1": "0991a395da64e1c5fbe8732ed11e6be064081d9f",
+ "orgPrevalence": "14850",
+ "orgFirstSeen": "2019-12-07T13:44:16Z",
+ "orgLastSeen": "2020-01-06T13:39:36Z",
+ "globalPrevalence": "705012",
+ "globalFirstObserved": "2015-03-19T12:20:07.3432441Z",
+ "globalLastObserved": "2020-01-06T13:39:36Z",
"topFileNames": [
- "chrome_1.exe",
- "chrome_2.exe"
+ "MREC.exe"
]
}
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-investigation-collection.md b/windows/security/threat-protection/microsoft-defender-atp/get-investigation-collection.md
new file mode 100644
index 0000000000..03fc53560f
--- /dev/null
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-investigation-collection.md
@@ -0,0 +1,110 @@
+---
+title: List Investigations API
+description: Use this API to create calls related to get Investigations collection
+keywords: apis, graph api, supported apis, Investigations 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
+manager: dansimp
+audience: ITPro
+ms.collection: M365-security-compliance
+ms.topic: article
+---
+
+# List Investigations API
+
+**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)
+
+
+## API description
+Retrieves a collection of [Investigations](investigation.md).
+
Supports [OData V4 queries](https://www.odata.org/documentation/).
+
The OData's ```$filter``` query is supported on: ```startTime```, ```state```, ```machineId``` and ```triggeringAlertId``` properties.
+
See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
+
+
+## Limitations
+1. Maximum page size is 10,000.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
+## Permissions
+One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](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'
+
+>[!Note]
+> When obtaining a token using user credentials:
+>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles.md) for more information)
+
+## HTTP request
+```
+GET https://api.securitycenter.windows.com/api/investigations
+```
+
+## 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 [Investigations](investigation.md) entities.
+
+
+[!include[Improve request performance](../../includes/improve-request-performance.md)]
+
+
+## Example
+
+**Request**
+
+Here is an example of a request to get all investigations:
+
+
+```
+GET https://api.securitycenter.windows.com/api/investigations
+```
+
+**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#Investigations",
+ "value": [
+ {
+ "id": "63017",
+ "startTime": "2020-01-06T14:11:34Z",
+ "endTime": null,
+ "state": "Running",
+ "cancelledBy": null,
+ "statusDetails": null,
+ "machineId": "a69a22debe5f274d8765ea3c368d00762e057b30",
+ "computerDnsName": "desktop-gtrcon0",
+ "triggeringAlertId": "da637139166940871892_-598649278"
+ }
+ ...
+ ]
+}
+```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-investigation-object.md b/windows/security/threat-protection/microsoft-defender-atp/get-investigation-object.md
new file mode 100644
index 0000000000..933c2cde60
--- /dev/null
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-investigation-object.md
@@ -0,0 +1,66 @@
+---
+title: Get Investigation object API
+description: Use this API to create calls related to get Investigation object
+keywords: apis, graph api, supported apis, Investigation 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
+manager: dansimp
+audience: ITPro
+ms.collection: M365-security-compliance
+ms.topic: article
+---
+
+# Get Investigation API
+
+**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)
+
+
+## API description
+Retrieves specific [Investigation](investigation.md) by its ID.
+
ID can be the investigation ID or the investigation triggering alert ID.
+
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
+## Permissions
+One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](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'
+
+>[!Note]
+> When obtaining a token using user credentials:
+>- The user needs to have at least the following role permission: 'View Data' (See [Create and manage roles](user-roles.md) for more information)
+
+## HTTP request
+```
+GET https://api.securitycenter.windows.com/api/investigations/{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 [Investigations](investigation.md) entity.
+
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-ip-related-alerts.md b/windows/security/threat-protection/microsoft-defender-atp/get-ip-related-alerts.md
index e7bf04d3e1..c0088b91f6 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-ip-related-alerts.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-ip-related-alerts.md
@@ -18,12 +18,19 @@ ms.topic: article
# Get IP related alerts 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)
+
+## API description
Retrieves a collection of alerts related to a given IP address.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -69,39 +76,4 @@ Here is an example of the request.
```
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": "441688558380765161_2136280442",
- "incidentId": 8633,
- "assignedTo": "secop@contoso.com",
- "severity": "Low",
- "status": "InProgress",
- "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-25T16:19:21.8409809Z",
- "firstEventTime": "2018-11-25T16:17:50.0948658Z",
- "lastEventTime": "2018-11-25T16:18:01.809871Z",
- "resolvedTime": null,
- "machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
- }
- ]
-}
-```
+```
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-ip-statistics.md b/windows/security/threat-protection/microsoft-defender-atp/get-ip-statistics.md
index 6f8fe6c478..9bc08c2680 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-ip-statistics.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-ip-statistics.md
@@ -18,11 +18,18 @@ ms.topic: article
# Get IP statistics 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)
+
+
+## API description
+Retrieves the statistics for the given IP.
+
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-kbinfo-collection.md b/windows/security/threat-protection/microsoft-defender-atp/get-kbinfo-collection.md
index 7617020547..55e74662e6 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-kbinfo-collection.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-kbinfo-collection.md
@@ -15,7 +15,7 @@ manager: dansimp
audience: ITPro
ms.collection: M365-security-compliance
ms.topic: article
-ms.date: 10/07/2018
+ROBOTS: NOINDEX
---
# Get KB collection API
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machine-by-id.md b/windows/security/threat-protection/microsoft-defender-atp/get-machine-by-id.md
index 2f8eda6c03..aaaa6abf4d 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machine-by-id.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machine-by-id.md
@@ -18,11 +18,19 @@ ms.topic: article
# Get machine by ID 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)
+
+
+## API description
+Retrieves specific [Machine](machine.md) by its machine ID or computer name.
+
+
+## Limitations
+1. You can get machines last seen in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -83,20 +91,22 @@ 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",
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "Active",
+ "rbacGroupId": 140,
"rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "riskScore": "Low",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
"machineTags": [ "test tag 1", "test tag 2" ]
}
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machine-log-on-users.md b/windows/security/threat-protection/microsoft-defender-atp/get-machine-log-on-users.md
index 9d364b0815..59e1357d2e 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machine-log-on-users.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machine-log-on-users.md
@@ -18,11 +18,19 @@ ms.topic: article
# Get machine log on users 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)
+
+
+## API description
+Retrieves a collection of logged on users on a specific machine.
+
+
+## Limitations
+1. You can query on machines last seen in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -81,26 +89,19 @@ Content-type: application/json
"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
+ "accountName": "user1",
+ "accountDomain": "contoso",
+ "accountSid": "S-1-5-21-72051607-1745760036-109187956-93922",
+ "firstSeen": "2019-12-18T08:02:54Z",
+ "lastSeen": "2020-01-06T08:01:48Z",
+ "mostPrevalentMachineId": "111153d0c675eaa415b8e5f383c6388bff446c62",
+ "leastPrevalentMachineId": "111153d0c675eaa415b8e5f383c6388bff446c62",
+ "logonTypes": "Interactive",
+ "logOnMachinesCount": 8,
+ "isDomainAdmin": true,
+ "isOnlyNetworkUser": false
},
- {
- "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
- }
+ ...
]
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machine-related-alerts.md b/windows/security/threat-protection/microsoft-defender-atp/get-machine-related-alerts.md
index f6499ab7bb..dd13f88123 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machine-related-alerts.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machine-related-alerts.md
@@ -17,13 +17,20 @@ ms.topic: article
---
# Get machine related alerts API
-**Applies to:**
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-Retrieves a collection of alerts related to a given machine ID.
+**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)
+
+
+## API description
+Retrieves all [Alerts](alerts.md) related to a specific machine.
+
+
+## Limitations
+1. You can query on machines last seen in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-## Permissions
-One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
@@ -54,52 +61,3 @@ Empty
## Response
If successful and machine exists - 200 OK with list of [alert](alerts.md) entities in the body. If machine was not found - 404 Not Found.
-
-
-## Example
-
-**Request**
-
-Here is an example of the request.
-
-[!include[Improve request performance](../../includes/improve-request-performance.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": "441688558380765161_2136280442",
- "incidentId": 8633,
- "assignedTo": "secop@contoso.com",
- "severity": "Low",
- "status": "InProgress",
- "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-25T16:19:21.8409809Z",
- "firstEventTime": "2018-11-25T16:17:50.0948658Z",
- "lastEventTime": "2018-11-25T16:18:01.809871Z",
- "resolvedTime": null,
- "machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
- }
- ]
-}
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machineaction-object.md b/windows/security/threat-protection/microsoft-defender-atp/get-machineaction-object.md
index 0b122f4eb6..dbcaf5b6fb 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machineaction-object.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machineaction-object.md
@@ -18,10 +18,18 @@ ms.topic: article
# Get machineAction 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)
+
+
+## API description
+Retrieves specific [Machine Action](machineaction.md) by its ID.
+
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -77,15 +85,17 @@ 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",
+ "id": "5382f7ea-7557-4ab7-9782-d50480024a4e",
+ "type": "Isolate",
+ "scope": "Selective",
+ "requestor": "Analyst@TestPrd.onmicrosoft.com",
+ "requestorComment": "test for docs",
"status": "Succeeded",
- "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
- "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
- "lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
- "relatedFileInfo": null
+ "machineId": "7b1f4967d9728e5aa3c06a9e617a22a4a5a17378",
+ "computerDnsName": "desktop-test",
+ "creationDateTimeUtc": "2019-01-02T14:39:38.2262283Z",
+ "lastUpdateDateTimeUtc": "2019-01-02T14:40:44.6596267Z",
+ "relatedFileInfo": null
}
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machineactions-collection.md b/windows/security/threat-protection/microsoft-defender-atp/get-machineactions-collection.md
index 6389f8c1f4..c9883c2e4a 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machineactions-collection.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machineactions-collection.md
@@ -18,17 +18,22 @@ ms.topic: article
# List MachineActions 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)
-Gets collection of actions done on machines.
-Get MachineAction collection API supports [OData V4 queries](https://www.odata.org/documentation/).
+## API description
+Retrieves a collection of [Machine Actions](machineaction.md).
+
Supports [OData V4 queries](https://www.odata.org/documentation/).
+
The OData's ```$filter``` query is supported on: ```status```, ```machineId```, ```type```, ```requestor``` and ```creationDateTimeUtc``` properties.
+
See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
-The OData's Filter query is supported on: "Id", "Status", "MachineId", "Type", "Requestor" and "CreationDateTimeUtc".
-See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
+## Limitations
+1. Maximum page size is 10,000.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -89,10 +94,12 @@ Content-type: application/json
{
"id": "69dc3630-1ccc-4342-acf3-35286eec741d",
"type": "CollectInvestigationPackage",
+ "scope": null,
"requestor": "Analyst@contoso.com",
"requestorComment": "test",
"status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+ "computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z",
"lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z",
"relatedFileInfo": null
@@ -100,10 +107,12 @@ Content-type: application/json
{
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan",
+ "scope": "Full",
"requestor": "Analyst@contoso.com",
"requestorComment": "Check machine for viruses due to alert 3212",
"status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+ "computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
"relatedFileInfo": null
@@ -111,10 +120,12 @@ Content-type: application/json
{
"id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e",
"type": "StopAndQuarantineFile",
+ "scope": null,
"requestor": "Analyst@contoso.com",
"requestorComment": "test",
"status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+ "computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:15:40.6052029Z",
"lastUpdateTimeUtc": "2018-12-04T12:16:14.2899973Z",
"relatedFileInfo": {
@@ -151,10 +162,12 @@ Content-type: application/json
{
"id": "69dc3630-1ccc-4342-acf3-35286eec741d",
"type": "CollectInvestigationPackage",
+ "scope": null,
"requestor": "Analyst@contoso.com",
"requestorComment": "test",
"status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+ "computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z",
"lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z",
"relatedFileInfo": null
@@ -162,10 +175,12 @@ Content-type: application/json
{
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan",
+ "scope": "Full",
"requestor": "Analyst@contoso.com",
"requestorComment": "Check machine for viruses due to alert 3212",
"status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+ "computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
"relatedFileInfo": null
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machines.md b/windows/security/threat-protection/microsoft-defender-atp/get-machines.md
index 1434e0878e..31ef6bb72d 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machines.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machines.md
@@ -18,17 +18,23 @@ ms.topic: article
# List machines 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)
-This API can do the following actions:
-- Retrieves a collection of machines that have communicated with Microsoft Defender ATP cloud on the last 30 days.
-- Get Machines collection API supports [OData V4 queries](https://www.odata.org/documentation/).
-- The OData's Filter query is supported on: "Id", "ComputerDnsName", "LastSeen", "LastIpAddress", "HealthStatus", "OsPlatform", "RiskScore", "MachineTags" and "RbacGroupId".
+## API description
+Retrieves a collection of [Machines](machine.md) that have communicated with Microsoft Defender ATP cloud on the last 30 days.
+
Supports [OData V4 queries](https://www.odata.org/documentation/).
+
The OData's ```$filter``` query is supported on: ```computerDnsName```, ```lastSeen```, ```lastIpAddress```, ```healthStatus```, ```osPlatform```, ```riskScore```, ```rbacGroupId``` and ```machineTags``` properties.
+
See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
+
+
+## Limitations
+1. You can get machines last seen in the past 30 days.
+2. Maximum page size is 10,000.
+3. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
## Permissions
@@ -88,42 +94,25 @@ Content-type: application/json
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "isAadJoined": true,
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2" ]
- },
- {
- "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
- "computerDnsName": "mymachine2.contoso.com",
- "firstSeen": "2018-07-09T13:22:45.1250071Z",
- "lastSeen": "2018-07-09T13:22:45.1250071Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "192.168.12.225",
- "lastExternalIpAddress": "79.183.65.82",
- "agentVersion": "10.5820.17724.1000",
- "osBuild": 17724,
- "healthStatus": "Inactive",
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "Active",
"rbacGroupId": 140,
"rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "isAadJoined": false,
- "aadDeviceId": null,
- "machineTags": [ "test tag 1" ]
+ "riskScore": "Low",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "machineTags": [ "test tag 1", "test tag 2" ]
}
+ ...
]
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-package-sas-uri.md b/windows/security/threat-protection/microsoft-defender-atp/get-package-sas-uri.md
index d3b61ac453..986c832afc 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-package-sas-uri.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-package-sas-uri.md
@@ -18,11 +18,14 @@ ms.topic: article
# Get package SAS URI 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)
+
+
+## API description
+Get a URI that allows downloading of an [Investigation package](collect-investigation-package.md).
-Get a URI that allows downloading of an [investigation package](collect-investigation-package.md).
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-ti-indicators-collection.md b/windows/security/threat-protection/microsoft-defender-atp/get-ti-indicators-collection.md
index 84051f2159..7ac3ed480b 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-ti-indicators-collection.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-ti-indicators-collection.md
@@ -18,16 +18,21 @@ ms.topic: article
# List Indicators 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)
->[!NOTE]
-> Currently this API is supported only for AppOnly context requests. (See [Get access with application context](exposed-apis-create-app-webapp.md) for more information)
+## API description
+Retrieves a collection of all active [Indicators](ti-indicator.md).
+
Supports [OData V4 queries](https://www.odata.org/documentation/).
+
The OData's ```$filter``` query is supported on: ```indicatorValue```, ```indicatorType```, ```creationTimeDateTimeUtc```, ```createdBy```, ```action``` and ```severity``` properties.
+
See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
-- Gets collection of TI Indicators.
-- Get TI Indicators collection API supports [OData V4 queries](https://www.odata.org/documentation/).
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Get started](apis-intro.md)
@@ -36,7 +41,7 @@ Permission type | Permission | Permission display name
:---|:---|:---
Application | Ti.ReadWrite | 'Read and write Indicators'
Application | Ti.ReadWrite.All | 'Read and write All Indicators'
-
+Delegated (work or school account) | Ti.ReadWrite | 'Read and write Indicators'
## HTTP request
```
@@ -82,26 +87,38 @@ Content-type: application/json
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators",
"value": [
{
+ "id": "995",
"indicatorValue": "12.13.14.15",
"indicatorType": "IpAddress",
+ "action": "Alert",
+ "application": "demo-test",
+ "source": "TestPrdApp",
+ "sourceType": "AadApp",
"title": "test",
"creationTimeDateTimeUtc": "2018-10-24T11:15:35.3688259Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z",
- "action": "Alert",
+ "lastUpdateTime": "2019-10-24T10:54:23.2009016Z",
+ "lastUpdatedBy": TestPrdApp,
"severity": "Informational",
"description": "test",
"recommendedActions": "test",
"rbacGroupNames": []
},
{
+ "id": "996",
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1",
+ "action": "AlertAndBlock",
+ "application": null,
+ "source": "TestPrdApp",
+ "sourceType": "AadApp",
"title": "test",
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z",
- "action": "AlertAndBlock",
+ "lastUpdateTime": "2019-10-24T10:54:23.2009016Z",
+ "lastUpdatedBy": TestPrdApp,
"severity": "Informational",
"description": "test",
"recommendedActions": "TEST",
@@ -119,7 +136,7 @@ Content-type: application/json
Here is an example of a request that gets all Indicators with 'AlertAndBlock' action
```
-GET https://api.securitycenter.windows.com/api/indicators?$filter=action eq 'AlertAndBlock'
+GET https://api.securitycenter.windows.com/api/indicators?$filter=action+eq+'AlertAndBlock'
```
**Response**
@@ -133,13 +150,19 @@ Content-type: application/json
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators",
"value": [
{
- "indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
+ "id": "997",
+ "indicatorValue": "111e7d15b0b3d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1",
+ "action": "AlertAndBlock",
+ "application": null,
+ "source": "TestPrdApp",
+ "sourceType": "AadApp",
"title": "test",
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z",
- "action": "AlertAndBlock",
+ "lastUpdateTime": "2019-10-24T10:54:23.2009016Z",
+ "lastUpdatedBy": TestPrdApp,
"severity": "Informational",
"description": "test",
"recommendedActions": "TEST",
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-user-related-alerts.md b/windows/security/threat-protection/microsoft-defender-atp/get-user-related-alerts.md
index 724fb808b6..0eaec5311d 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-user-related-alerts.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-user-related-alerts.md
@@ -18,12 +18,19 @@ ms.topic: article
# Get user related alerts 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)
+
+## API description
Retrieves a collection of alerts related to a given user ID.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -70,59 +77,4 @@ Here is an example of the request.
```
GET https://api.securitycenter.windows.com/api/users/user1/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": "441688558380765161_2136280442",
- "incidentId": 8633,
- "assignedTo": "secop@contoso.com",
- "severity": "Low",
- "status": "InProgress",
- "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-25T16:19:21.8409809Z",
- "firstEventTime": "2018-11-25T16:17:50.0948658Z",
- "lastEventTime": "2018-11-25T16:18:01.809871Z",
- "resolvedTime": null,
- "machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
- },
- {
- "id": "121688558380765161_2136280442",
- "incidentId": 4123,
- "assignedTo": "secop@contoso.com",
- "severity": "Low",
- "status": "InProgress",
- "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-24T16:19:21.8409809Z",
- "firstEventTime": "2018-11-24T16:17:50.0948658Z",
- "lastEventTime": "2018-11-24T16:18:01.809871Z",
- "resolvedTime": null,
- "machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
- }
- ]
-}
-```
+```
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-user-related-machines.md b/windows/security/threat-protection/microsoft-defender-atp/get-user-related-machines.md
index f1ede24b29..ec84fa1f38 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-user-related-machines.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-user-related-machines.md
@@ -18,12 +18,19 @@ ms.topic: article
# Get user related machines 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)
+
+## API description
Retrieves a collection of machines related to a given user ID.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
@@ -72,54 +79,3 @@ Here is an example of the request.
```
GET https://api.securitycenter.windows.com/api/users/user1/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",
- "lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2" ]
- },
- {
- "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
- "computerDnsName": "mymachine2.contoso.com",
- "firstSeen": "2018-07-09T13:22:45.1250071Z",
- "lastSeen": "2018-07-09T13:22:45.1250071Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "192.168.12.225",
- "lastExternalIpAddress": "79.183.65.82",
- "agentVersion": "10.5820.17724.1000",
- "osBuild": 17724,
- "healthStatus": "Inactive",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": null,
- "machineTags": [ "test tag 1" ]
- }
- ]
-}
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/initiate-autoir-investigation.md b/windows/security/threat-protection/microsoft-defender-atp/initiate-autoir-investigation.md
index f875c8027f..3e95295b96 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/initiate-autoir-investigation.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/initiate-autoir-investigation.md
@@ -1,7 +1,7 @@
---
-title: Initiate machine investigation API
-description: Use this API to create calls related to initiating an investigation on a machine.
-keywords: apis, graph api, supported apis, initiate AutoIR investigation
+title: Start Investigation API
+description: Use this API to start investigation on a machine.
+keywords: apis, graph api, supported apis, investigation
search.product: eADQiWindows 10XVcnh
ms.prod: w10
ms.mktglfcycl: deploy
@@ -16,38 +16,39 @@ ms.collection: M365-security-compliance
ms.topic: article
---
-# Initiate machine investigation API (Preview)
-**Applies to:**
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+# Start Investigation API
-> [!IMPORTANT]
-> Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-Initiate AutoIR investigation on a machine.
+- 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)
+
+
+## API description
+Start automated investigation on a machine.
+
See [Overview of automated investigations](automated-investigations.md) for more information.
->[!Note]
-> This page focuses on performing an automated investigation on a machine. See [automated investigation](automated-investigations.md) for more information.
## Limitations
-1. The number of executions is limited (up to 5 calls per hour).
-2. For Automated Investigation limitations, see [Automated Investigation](automated-investigations.md).
+1. Rate limitations for this API are 50 calls per hour.
+
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
-Application | Alert.ReadWrite.All | 'Read and write all alerts'
-Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
+Application | Alert.ReadWrite.All | 'Read and write all alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
>[!Note]
> When obtaining a token using user credentials:
->- The user needs to have at least the following role permission: 'Alerts Investigation' (See [Create and manage roles](user-roles.md) for more information)
+>- The user needs to have at least the following role permission: 'Active remediation actions' (See [Create and manage roles](user-roles.md) for more information)
>- The user needs to have access to the machine, based on machine group settings (See [Create and manage machine groups](machine-groups.md) for more information)
+
## HTTP request
```
-POST https://api.securitycenter.windows.com/api/machines/{id}/InitiateInvestigation
+POST https://api.securitycenter.microsoft.com/api/machines/{id}/startInvestigation
```
## Request headers
@@ -64,8 +65,10 @@ Parameter | Type | Description
:---|:---|:---
Comment | String | Comment to associate with the action. **Required**.
+
## Response
-If successful, this method returns 200 OK response code with object that holds the investigation ID in the "value" parameter. If machine was not found - 404 Not Found.
+If successful, this method returns 201 - Created response code and [Investigation](investigation.md) in the response body.
+
## Example
@@ -76,23 +79,8 @@ Here is an example of the request.
[!include[Improve request performance](../../includes/improve-request-performance.md)]
```
-POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/InitiateInvestigation
+POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/startInvestigation
Content-type: application/json
{
- "Comment": "Initiate an investigation on machine fb9ab6be3965095a09c057be7c90f0a2"
+ "Comment": "Test investigation",
}
-```
-
-**Response**
-
-Here is an example of the response.
-
-```
-HTTP/1.1 200 Created
-Content-type: application/json
-{
- "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Edm.Int64",
- "value": 5146
-}
-
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/investigation.md b/windows/security/threat-protection/microsoft-defender-atp/investigation.md
new file mode 100644
index 0000000000..ec516a1afc
--- /dev/null
+++ b/windows/security/threat-protection/microsoft-defender-atp/investigation.md
@@ -0,0 +1,64 @@
+---
+title: Investigation resource type
+description: Microsoft Defender ATP Investigation entity.
+keywords: apis, graph api, supported apis, get, alerts, investigations
+search.product: eADQiWindows 10XVcnh
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+ms.author: macapara
+author: mjcaparas
+ms.localizationpriority: medium
+manager: dansimp
+audience: ITPro
+ms.collection: M365-security-compliance
+ms.topic: article
+---
+
+# Investigation resource type
+
+**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)
+
+Represent an Automated Investigation entity in Microsoft Defender ATP.
+
See [Overview of automated investigations](automated-investigations.md) for more information.
+
+## Methods
+Method|Return Type |Description
+:---|:---|:---
+[List Investigations](get-investigation-collection.md) | Investigation collection | Get collection of Investigation
+[Get single Investigation](get-investigation-collection.md) | Investigation entity | Gets single Investigation entity.
+[Start Investigation](initiate-autoir-investigation.md) | Investigation entity | Starts Investigation on a machine.
+
+
+## Properties
+Property | Type | Description
+:---|:---|:---
+id | String | Identity of the investigation entity.
+startTime | DateTime Nullable | The date and time when the investigation was created.
+endTime | DateTime Nullable | The date and time when the investigation was completed.
+cancelledBy | String | The ID of the user/application that cancelled that investigation.
+investigationState | 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'.
+statusDetails | String | Additional information about the state of the investigation.
+machineId | String | The ID of the machine on which the investigation is executed.
+computerDnsName | String | The name of the machine on which the investigation is executed.
+triggeringAlertId | String | The ID of the alert that triggered the investigation.
+
+
+## Json representation
+
+```json
+{
+ "id": "63004",
+ "startTime": "2020-01-06T13:05:15Z",
+ "endTime": null,
+ "state": "Running",
+ "cancelledBy": null,
+ "statusDetails": null,
+ "machineId": "e828a0624ed33f919db541065190d2f75e50a071",
+ "computerDnsName": "desktop-test123",
+ "triggeringAlertId": "da637139127150012465_1011995739"
+}
+```
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/isolate-machine.md b/windows/security/threat-protection/microsoft-defender-atp/isolate-machine.md
index 4a1fb9b49b..8b8c759287 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/isolate-machine.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/isolate-machine.md
@@ -18,12 +18,19 @@ ms.topic: article
# Isolate machine 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)
+
+## API description
Isolates a machine from accessing external network.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
[!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions
@@ -85,27 +92,5 @@ Content-type: application/json
“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",
- "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "creationDateTimeUtc": "2017-12-04T12:12:18.9725659Z",
- "lastUpdateTimeUtc": "2017-12-04T12:12:18.9725659Z",
- "relatedFileInfo": null
-}
-
-```
-
-To unisolate a machine, see [Release machine from isolation](unisolate-machine.md).
+- To unisolate a machine, see [Release machine from isolation](unisolate-machine.md).
diff --git a/windows/security/threat-protection/microsoft-defender-atp/machine.md b/windows/security/threat-protection/microsoft-defender-atp/machine.md
index a4227c1113..4edb6f1e70 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/machine.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/machine.md
@@ -17,8 +17,10 @@ ms.topic: article
---
# Machine resource type
-**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)
## Methods
@@ -38,15 +40,41 @@ id | String | [machine](machine.md) identity.
computerDnsName | String | [machine](machine.md) fully qualified name.
firstSeen | DateTimeOffset | First date and time where the [machine](machine.md) was observed by Microsoft Defender ATP.
lastSeen | DateTimeOffset | Last date and time where the [machine](machine.md) was observed by Microsoft Defender ATP.
-osPlatform | String | OS platform.
-osVersion | String | OS Version.
+osPlatform | String | Operating system platform.
+version | String | Operating system Version.
+osBuild | Nullable long | Operating system build number.
lastIpAddress | String | Last IP on local NIC on the [machine](machine.md).
lastExternalIpAddress | String | Last IP through which the [machine](machine.md) accessed the internet.
-agentVersion | String | Version of Microsoft Defender ATP agent.
-osBuild | Nullable long | OS build number.
healthStatus | Enum | [machine](machine.md) health status. Possible values are: "Active", "Inactive", "ImpairedCommunication", "NoSensorData" and "NoSensorDataImpairedCommunication"
-rbacGroupId | Int | RBAC Group ID.
-rbacGroupName | String | RBAC Group Name.
+rbacGroupName | String | Machine group Name.
+rbacGroupId | Int | Machine group unique ID.
riskScore | Nullable Enum | Risk score as evaluated by Microsoft Defender ATP. Possible values are: 'None', 'Low', 'Medium' and 'High'.
-aadDeviceId | Nullable Guid | AAD Device ID (when [machine](machine.md) is Aad Joined).
+exposureScore | Nullable Enum | [Exposure score](tvm-exposure-score.md) as evaluated by Microsoft Defender ATP. Possible values are: 'None', 'Low', 'Medium' and 'High'.
+aadDeviceId | Nullable representation Guid | AAD Device ID (when [machine](machine.md) is Aad Joined).
machineTags | String collection | Set of [machine](machine.md) tags.
+
+
+## Json representation
+
+```json
+{
+ "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
+ "lastSeen": "2018-08-02T14:55:03.7791856Z",
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "Active",
+ "rbacGroupId": 140,
+ "rbacGroupName": "The-A-Team",
+ "riskScore": "Low",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "machineTags": [ "test tag 1", "test tag 2" ]
+}
+```
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/machineaction.md b/windows/security/threat-protection/microsoft-defender-atp/machineaction.md
index 714a678227..fdd4146f99 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/machineaction.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/machineaction.md
@@ -18,8 +18,11 @@ ms.topic: article
# MachineAction resource type
-**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)
+
+- See [Response Actions](respond-machine-alerts.md) for more information
| Method | Return Type | Description |
|:------------------------------------------------------------------|:-----------------------------------|:------------------------------------------------------------|
@@ -33,6 +36,7 @@ ms.topic: article
| [Remove app restriction](unrestrict-code-execution.md) | [Machine Action](machineaction.md) | Remove application execution restriction. |
| [Run antivirus scan](run-av-scan.md) | [Machine Action](machineaction.md) | Run an AV scan using Windows Defender (when applicable). |
| [Offboard machine](offboard-machine-api.md) | [Machine Action](machineaction.md) | Offboard [machine](machine.md) from Microsoft Defender ATP. |
+| [Stop and quarantine file](stop-and-quarantine-file.md) | [Machine Action](machineaction.md) | Stop execution of a file on a machine and delete it. |
@@ -42,11 +46,31 @@ ms.topic: article
|:--------------------|:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id | Guid | Identity of the [Machine Action](machineaction.md) entity. |
| type | Enum | Type of the action. Possible values are: "RunAntiVirusScan", "Offboard", "CollectInvestigationPackage", "Isolate", "Unisolate", "StopAndQuarantineFile", "RestrictCodeExecution" and "UnrestrictCodeExecution" |
+| scope | string | Scope of the action. "Full" or "Selective" in case of Isolation, "Quick" or "Full" in case of Anti-Virus scan. |
| requestor | String | Identity of the person that executed the action. |
| requestorComment | String | Comment that was written when issuing the action. |
| status | Enum | Current status of the command. Possible values are: "Pending", "InProgress", "Succeeded", "Failed", "TimeOut" and "Cancelled". |
-| machineId | String | Id of the machine on which the action was executed. |
+| machineId | String | Id of the [machine](machine.md) on which the action was executed. |
+| machineId | String | Name of the [machine](machine.md) 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. |
-| relatedFileInfo | Class | Contains two Properties. 1) string 'fileIdentifier' 2) Enum 'fileIdentifierType' with the possible values: "Sha1" ,"Sha256" and "Md5". |
+| relatedFileInfo | Class | Contains two Properties. string ```fileIdentifier```, Enum ```fileIdentifierType``` with the possible values: "Sha1" ,"Sha256" and "Md5". |
+
+## Json representation
+
+```json
+{
+ "id": "5382f7ea-7557-4ab7-9782-d50480024a4e",
+ "type": "Isolate",
+ "scope": "Selective",
+ "requestor": "Analyst@TestPrd.onmicrosoft.com",
+ "requestorComment": "test for docs",
+ "status": "Succeeded",
+ "machineId": "7b1f4967d9728e5aa3c06a9e617a22a4a5a17378",
+ "computerDnsName": "desktop-test",
+ "creationDateTimeUtc": "2019-01-02T14:39:38.2262283Z",
+ "lastUpdateDateTimeUtc": "2019-01-02T14:40:44.6596267Z",
+ "relatedFileInfo": null
+}
+```
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/offboard-machine-api.md b/windows/security/threat-protection/microsoft-defender-atp/offboard-machine-api.md
index 314f1a67e6..ab3dd486d7 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/offboard-machine-api.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/offboard-machine-api.md
@@ -18,12 +18,19 @@ ms.topic: article
# Offboard machine 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)
+
+## API description
Offboard machine from Microsoft Defender ATP.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
[!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions
@@ -76,26 +83,4 @@ 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",
- "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "creationDateTimeUtc": "2018-12-04T12:09:24.1785079Z",
- "lastUpdateTimeUtc": "2018-12-04T12:09:24.1785079Z",
- "relatedFileInfo": null
-}
-
-```
+```
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt b/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt
index a603fac035..987d3c8ce0 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt
+++ b/windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt
@@ -381,7 +381,12 @@
####### [Run antivirus scan](run-av-scan.md)
####### [Offboard machine](offboard-machine-api.md)
####### [Stop and quarantine file](stop-and-quarantine-file.md)
-####### [Initiate investigation (preview)](initiate-autoir-investigation.md)
+
+###### [Automated Investigation]()
+####### [Investigation methods and properties](microsoft-defender-atp/investigation.md)
+####### [List Investigation](microsoft-defender-atp/get-investigation-collection.md)
+####### [Get Investigation](microsoft-defender-atp/get-investigation-object.md)
+####### [Start Investigation](microsoft-defender-atp/initiate-autoir-investigation.md)
###### [Indicators]()
####### [Methods and properties](ti-indicator.md)
diff --git a/windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md b/windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md
index 2165a3f073..b865033486 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md
@@ -18,18 +18,19 @@ ms.topic: article
# Submit or Update Indicator 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)
->[!NOTE]
-> Currently this API is supported only for AppOnly context requests. (See [Get access with application context](exposed-apis-create-app-webapp.md) for more information)
+## API description
+Submits or Updates new [Indicator](ti-indicator.md) entity.
+
CIDR notation for IPs is supported.
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+2. There is a limit of 5,000 active indicators per tenant.
-- Submits or Updates new [Indicator](ti-indicator.md) entity.
-
->[!NOTE]
->There is a limit of 5000 indicators per tenant.
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Get started](apis-intro.md)
@@ -38,6 +39,7 @@ Permission type | Permission | Permission display name
:---|:---|:---
Application | Ti.ReadWrite | 'Read and write Indicators'
Application | Ti.ReadWrite.All | 'Read and write All Indicators'
+Delegated (work or school account) | Ti.ReadWrite | 'Read and write Indicators'
## HTTP request
@@ -63,16 +65,17 @@ Parameter | Type | Description
indicatorValue | String | Identity of the [Indicator](ti-indicator.md) entity. **Required**
indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url". **Required**
action | Enum | The action that will be taken if the indicator will be discovered in the organization. Possible values are: "Alert", "AlertAndBlock", and "Allowed". **Required**
-title | String | Indicator alert title. **Optional**
+application | String | The application associated with the indicator. **Optional**
+title | String | Indicator alert title. **Required**
+description | String | Description of the indicator. **Required**
expirationTime | DateTimeOffset | The expiration time of the indicator. **Optional**
severity | Enum | The severity of the indicator. possible values are: "Informational", "Low", "Medium" and "High". **Optional**
-description | String | Description of the indicator. **Optional**
recommendedActions | String | TI indicator alert recommended actions. **Optional**
## Response
- If successful, this method returns 200 - OK response code and the created / updated [Indicator](ti-indicator.md) entity in the response body.
-- If not successful: this method return 400 - Bad Request / 409 - Conflict with the failure reason. Bad request usually indicates incorrect body and Conflict can happen if you try to submit an Indicator that conflicts with an existing Indicator type or Action.
+- If not successful: this method return 400 - Bad Request. Bad request usually indicates incorrect body.
## Example
@@ -84,40 +87,16 @@ Here is an example of the request.
POST https://api.securitycenter.windows.com/api/indicators
Content-type: application/json
{
- "indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
+ "indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1",
"title": "test",
+ "application": "demo-test",
"expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock",
"severity": "Informational",
"description": "test",
- "recommendedActions": "TEST"
+ "recommendedActions": "nothing"
}
-```
-**Response**
-
-Here is an example of the response.
-
-```
-HTTP/1.1 200 OK
-Content-type: application/json
-{
- "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators/$entity",
- "indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
- "indicatorType": "FileSha1",
- "title": "test",
- "creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
- "createdBy": "45097602-1234-5678-1234-9f453233e62c",
- "expirationTime": "2020-12-12T00:00:00Z",
- "action": "AlertAndBlock",
- "severity": "Informational",
- "description": "test",
- "recommendedActions": "TEST",
- "rbacGroupNames": []
-}
-
-```
-
## Related topic
- [Manage indicators](manage-indicators.md)
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/restrict-code-execution.md b/windows/security/threat-protection/microsoft-defender-atp/restrict-code-execution.md
index dd7b5aa37f..6addf06827 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/restrict-code-execution.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/restrict-code-execution.md
@@ -18,11 +18,18 @@ ms.topic: article
# Restrict app execution 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)
+
+
+## API description
+Restrict execution of all applications on the machine except a predefined set.
+
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-Restrict execution of all applications on the machine except a predefined set (see [Response machine alerts](respond-machine-alerts.md) for more information)
[!include[Machine actions note](../../includes/machineactionsnote.md)]
@@ -76,29 +83,6 @@ Content-type: application/json
}
```
-**Response**
-Here is an example of the response.
-
-[!include[Improve request performance](../../includes/improve-request-performance.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",
- "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "creationDateTimeUtc": "2018-12-04T12:15:04.3825985Z",
- "lastUpdateTimeUtc": "2018-12-04T12:15:04.3825985Z",
- "relatedFileInfo": null
-}
-
-```
-
-To remove code execution restriction from a machine, see [Remove app restriction](unrestrict-code-execution.md).
+- To remove code execution restriction from a machine, see [Remove app restriction](unrestrict-code-execution.md).
diff --git a/windows/security/threat-protection/microsoft-defender-atp/run-av-scan.md b/windows/security/threat-protection/microsoft-defender-atp/run-av-scan.md
index 648cd1a9ee..10a0f81607 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/run-av-scan.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/run-av-scan.md
@@ -18,12 +18,19 @@ ms.topic: article
# Run antivirus scan 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)
+
+## API description
Initiate Windows Defender Antivirus scan on a machine.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
[!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions
@@ -85,26 +92,3 @@ Content-type: application/json
}
```
-**Response**
-
-Here is an example of the response.
-
-[!include[Improve request performance](../../includes/improve-request-performance.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",
- "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
- "lastUpdateTimeUtc": "2018-12-04T12:18:27.1293487Z",
- "relatedFileInfo": null
-}
-
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/stop-and-quarantine-file.md b/windows/security/threat-protection/microsoft-defender-atp/stop-and-quarantine-file.md
index 90a5c9e590..edfd07e6a7 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/stop-and-quarantine-file.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/stop-and-quarantine-file.md
@@ -18,12 +18,19 @@ ms.topic: article
# Stop and quarantine file 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)
+
+## API description
Stop execution of a file on a machine and delete it.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
[!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions
@@ -78,30 +85,3 @@ Content-type: application/json
}
```
-**Response**
-
-Here is an example of the response.
-
-[!include[Improve request performance](../../includes/improve-request-performance.md)]
-
-```
-HTTP/1.1 201 Created
-Content-type: application/json
-{
- "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
- "id": "141408d1-384c-4c19-8b57-ba39e378011a",
- "type": "StopAndQuarantineFile",
- "requestor": "Analyst@contoso.com ",
- "requestorComment": "Stop and quarantine file on machine due to alert 441688558380765161_2136280442",
- "status": "InProgress",
- "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "creationDateTimeUtc": "2018-12-04T12:15:04.3825985Z",
- "lastUpdateTimeUtc": "2018-12-04T12:15:04.3825985Z",
- "relatedFileInfo": {
- "fileIdentifier": "87662bc3d60e4200ceaf7aae249d1c343f4b83c9",
- "fileIdentifierType": "Sha1"
- }
-}
-
-```
-
diff --git a/windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md b/windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md
index 28e3bd225c..8e4d732734 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md
@@ -18,9 +18,11 @@ ms.topic: article
# Indicator resource type
-**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)
+
+- See the corresponding [Indicators page](https://securitycenter.windows.com/preferences2/custom_ti_indicators/files) in the portal.
Method|Return Type |Description
:---|:---|:---
@@ -28,23 +30,49 @@ Method|Return Type |Description
[Submit Indicator](post-ti-indicator.md) | [Indicator](ti-indicator.md) | Submits [Indicator](ti-indicator.md) entity.
[Delete Indicator](delete-ti-indicator-by-id.md) | No Content | Deletes [Indicator](ti-indicator.md) entity.
-- See the corresponding [page](https://securitycenter.windows.com/preferences2/custom_ti_indicators/files) in the portal.
-
-For more information on creating indicators, see [Manage indicators](manage-indicators.md).
## Properties
Property | Type | Description
:---|:---|:---
-indicatorValue | String | Identity of the [Indicator](ti-indicator.md) entity.
-indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url"
-title | String | Indicator alert title.
+id | String | Identity of the [Indicator](ti-indicator.md) entity.
+indicatorValue | String | The value of the [Indicator](ti-indicator.md).
+indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url".
+application | String | The application associated with the indicator.
+action | Enum | The action that will be taken if the indicator will be discovered in the organization. Possible values are: "Alert", "AlertAndBlock", and "Allowed".
+sourceType | Enum | "User" in case the Indicator created by a user (e.g. from the portal), "AadApp" in case it submitted using automated application via the API.
+source | string | The name of the user/application that submitted the indicator.
+createdBy | String | Unique identity of the user/application that submitted the indicator.
+lastUpdatedBy | String | Identity of the user/application that last updated the indicator.
creationTimeDateTimeUtc | DateTimeOffset | The date and time when the indicator was created.
-createdBy | String | Identity of the user/application that submitted the indicator.
-expirationTime | DateTimeOffset | The expiration time of the indicator
-action | Enum | The action that will be taken if the indicator will be discovered in the organization. Possible values are: "Alert", "AlertAndBlock", and "Allowed"
-severity | Enum | The severity of the indicator. possible values are: "Informational", "Low", "Medium" and "High"
+expirationTime | DateTimeOffset | The expiration time of the indicator.
+lastUpdateTime | DateTimeOffset | The last time the indicator was updated.
+severity | Enum | The severity of the indicator. possible values are: "Informational", "Low", "Medium" and "High".
+title | String | Indicator title.
description | String | Description of the indicator.
-recommendedActions | String | Indicator alert recommended actions.
-rbacGroupNames | List of strings | RBAC group names where the indicator is exposed. Empty list in case it exposed to all groups.
+recommendedActions | String | Recommended actions for the indicator.
+rbacGroupNames | List of strings | RBAC machine group names where the indicator is exposed and active. Empty list in case it exposed to all machines.
+## Json representation
+
+```json
+{
+ "id": "994",
+ "indicatorValue": "881c0f10c75e64ec39d257a131fcd531f47dd2cff2070ae94baa347d375126fd",
+ "indicatorType": "FileSha256",
+ "action": "AlertAndBlock",
+ "application": null,
+ "source": "user@contoso.onmicrosoft.com",
+ "sourceType": "User",
+ "createdBy": "user@contoso.onmicrosoft.com",
+ "severity": "Informational",
+ "title": "Michael test",
+ "description": "test",
+ "recommendedActions": "nothing",
+ "creationTimeDateTimeUtc": "2019-12-19T09:09:46.9139216Z",
+ "expirationTime": null,
+ "lastUpdateTime": "2019-12-19T09:09:47.3358111Z",
+ "lastUpdatedBy": null,
+ "rbacGroupNames": ["team1"]
+}
+```
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/unisolate-machine.md b/windows/security/threat-protection/microsoft-defender-atp/unisolate-machine.md
index 9c17d1b578..40c5117a86 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/unisolate-machine.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/unisolate-machine.md
@@ -19,12 +19,19 @@ ms.topic: article
# Release machine from isolation 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)
+
+## API description
Undo isolation of a machine.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
[!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions
@@ -80,30 +87,7 @@ Content-type: application/json
}
```
-**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",
- "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "creationDateTimeUtc": "2018-12-04T12:13:15.0104931Z",
- "lastUpdateTimeUtc": "2018-12-04T12:13:15.0104931Z",
- "relatedFileInfo": null
-}
-
-```
-
-To isolate a machine, see [Isolate machine](isolate-machine.md).
+- To isolate a machine, see [Isolate machine](isolate-machine.md).
diff --git a/windows/security/threat-protection/microsoft-defender-atp/unrestrict-code-execution.md b/windows/security/threat-protection/microsoft-defender-atp/unrestrict-code-execution.md
index fdb3691cc4..9687b34e41 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/unrestrict-code-execution.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/unrestrict-code-execution.md
@@ -18,12 +18,19 @@ ms.topic: article
# Remove app restriction 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)
+
+## API description
Enable execution of any application on the machine.
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
[!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions
@@ -78,26 +85,5 @@ Content-type: application/json
```
-**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",
- "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "creationDateTimeUtc": "2018-12-04T12:15:40.6052029Z",
- "lastUpdateTimeUtc": "2018-12-04T12:15:40.6052029Z",
- "relatedFileInfo": null
-}
-
-```
To restrict code execution on a machine, see [Restrict app execution](restrict-code-execution.md).
diff --git a/windows/security/threat-protection/microsoft-defender-atp/update-alert.md b/windows/security/threat-protection/microsoft-defender-atp/update-alert.md
index 1f6195d622..d51346f8f2 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/update-alert.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/update-alert.md
@@ -18,11 +18,21 @@ ms.topic: article
# Update alert
-**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)
+
+
+## API description
+Updates properties of existing [Alert](alerts.md).
+
Submission of **comment** is available with or without updating properties.
+
Updatable properties are: ```status```, ```determination```, ```classification``` and ```assignedTo```.
+
+
+## Limitations
+1. You can update alerts that available in the API. See [List Alerts](get-alerts.md) for more information.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-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 Microsoft Defender ATP APIs](apis-intro.md)
@@ -51,7 +61,9 @@ 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 changes to other property values. For best performance you shouldn't include existing values that haven't change.
+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 changes to other property values.
+
For best performance you shouldn't include existing values that haven't change.
Property | Type | Description
:---|:---|:---
@@ -59,6 +71,7 @@ status | String | Specifies the current status of the alert. The property values
assignedTo | String | Owner of the alert
classification | String | Specifies 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'
+comment | String | Comment to be added to the alert.
[!include[Improve request performance](../../includes/improve-request-performance.md)]
@@ -75,35 +88,12 @@ Here is an example of the request.
```
PATCH https://api.securitycenter.windows.com/api/alerts/121688558380765161_2136280442
Content-Type: application/json
+
{
- "assignedTo": "secop2@contoso.com"
-}
-```
-
-**Response**
-
-Here is an example of the response.
-
-```
-{
- "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts/$entity",
- "id": "121688558380765161_2136280442",
- "incidentId": 7696,
+ "status": "Resolved",
"assignedTo": "secop2@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"
+ "classification": "FalsePositive",
+ "determination": "Malware",
+ "comment": "Resolve my alert and assign to secop2"
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/user.md b/windows/security/threat-protection/microsoft-defender-atp/user.md
index 9700fea0cb..bd76e783d9 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/user.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/user.md
@@ -18,8 +18,9 @@ ms.topic: article
# User resource type
-**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)
Method|Return Type |Description
:---|:---|:---