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

Merging changes synced from https://github.com/MicrosoftDocs/windows-docs-pr (branch live)

Browse Source
This commit is contained in:
officedocspr 2020-01-13 23:50:02 +00:00
commit 199cee3e1d
55 changed files with 1118 additions and 1213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -406,7 +406,12 @@
####### [Run antivirus scan](microsoft-defender-atp/run-av-scan.md) ####### [Run antivirus scan](microsoft-defender-atp/run-av-scan.md)
####### [Offboard machine](microsoft-defender-atp/offboard-machine-api.md) ####### [Offboard machine](microsoft-defender-atp/offboard-machine-api.md)
####### [Stop and quarantine file](microsoft-defender-atp/stop-and-quarantine-file.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]()
####### [Indicators methods and properties](microsoft-defender-atp/ti-indicator.md) ####### [Indicators methods and properties](microsoft-defender-atp/ti-indicator.md)

45
windows/security/threat-protection/microsoft-defender-atp/add-or-remove-machine-tags.md
View File

@ -18,10 +18,19 @@ ms.topic: article
# Add or Remove Machine Tags API # Add or Remove Machine Tags 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
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 ## 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) 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" "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. - To remove machine tag, set the Action to 'Remove' instead of 'Add' in the request body.

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

@ -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. [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. [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). [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 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). [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. threatFamilyName | String | Threat family.
machineId | String | ID of a [machine](machine.md) entity that is associated with the alert. 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. 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: ### Response example for getting single alert:
``` ```
@ -83,12 +73,12 @@ GET https://api.securitycenter.windows.com/api/alerts/da637084217856368682_-2929
"id": "da637084217856368682_-292920499", "id": "da637084217856368682_-292920499",
"incidentId": 66860, "incidentId": 66860,
"investigationId": 4416234, "investigationId": 4416234,
"investigationState": "Running",
"assignedTo": "secop@contoso.com", "assignedTo": "secop@contoso.com",
"severity": "Low", "severity": "Low",
"status": "New", "status": "New",
"classification": "TruePositive", "classification": "TruePositive",
"determination": null, "determination": null,
"investigationState": "Running",
"detectionSource": "WindowsDefenderAtp", "detectionSource": "WindowsDefenderAtp",
"category": "CommandAndControl", "category": "CommandAndControl",
"threatFamilyName": null, "threatFamilyName": null,
@ -106,24 +96,6 @@ GET https://api.securitycenter.windows.com/api/alerts/da637084217856368682_-2929
"createdBy": "secop@contoso.com", "createdBy": "secop@contoso.com",
"createdTime": "2019-11-05T14:08:37.8404534Z" "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"
}
] ]
} }
``` ```

34
windows/security/threat-protection/microsoft-defender-atp/collect-investigation-package.md
View File

@ -18,11 +18,19 @@ ms.topic: article
--- ---
# Collect investigation package API # 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. Collect investigation package from a machine.
## Limitations
1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
## Permissions ## 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) 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" "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
}
```

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

@ -16,13 +16,24 @@ ms.collection: M365-security-compliance
ms.topic: article 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) **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) - 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).
<br>Microsoft Defender ATP Event is a required parameter for the alert creation.
<br>You can use an event found in Advanced Hunting API or Portal.
<br>If there existing an open alert on the same Machine with the same Title, the new created alert will be merged with it.
<br>An automatic investigation starts automatically on alerts created via the API.
## Limitations
1. Rate limitations for this API are 15 calls per minute.
## Permissions ## Permissions

25
windows/security/threat-protection/microsoft-defender-atp/delete-ti-indicator-by-id.md
View File

@ -18,15 +18,18 @@ ms.topic: article
# Delete Indicator API # Delete Indicator 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)
>[!Note] ## API description
> 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) 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 ## 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) 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. Here is an example of the request.
``` ```
DELETE https://api.securitycenter.windows.com/api/indicators/220e7d15b0b3d7fac48f2bd61114db1022197f7f DELETE https://api.securitycenter.windows.com/api/indicators/995
```
**Response**
Here is an example of the response.
```
HTTP/1.1 204 NO CONTENT
``` ```

221
windows/security/threat-protection/microsoft-defender-atp/exposed-apis-odata-samples.md
View File

@ -51,25 +51,25 @@ Content-type: application/json
"value": [ "value": [
{ {
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com", "computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z", "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z", "lastSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10", "osPlatform": "Windows10",
"osVersion": "10.0.0.0", "version": "1709",
"lastIpAddress": "172.17.230.209", "osProcessor": "x64",
"lastExternalIpAddress": "167.220.196.71", "lastIpAddress": "172.17.230.209",
"agentVersion": "10.5830.18209.1001", "lastExternalIpAddress": "167.220.196.71",
"osBuild": 18209, "osBuild": 18209,
"healthStatus": "Active", "healthStatus": "Active",
"rbacGroupId": 140, "rbacGroupId": 140,
"rbacGroupName": "The-A-Team", "rbacGroupName": "The-A-Team",
"riskScore": "High", "riskScore": "Low",
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9", "exposureLevel": "Medium",
"machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ] "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 - 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:** **Response:**
@ -91,28 +91,35 @@ Content-type: application/json
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
"value": [ "value": [
{ {
"id": "121688558380765161_2136280442", "id": "da637084217856368682_-292920499",
"incidentId": 7696, "incidentId": 66860,
"assignedTo": "secop@contoso.com", "investigationId": 4416234,
"severity": "High", "investigationState": "Running",
"status": "New", "assignedTo": "secop@contoso.com",
"classification": "TruePositive", "severity": "Low",
"determination": "Malware", "status": "New",
"investigationState": "Running", "classification": "TruePositive",
"category": "MalwareDownload", "determination": null,
"detectionSource": "WindowsDefenderAv", "detectionSource": "WindowsDefenderAtp",
"threatFamilyName": "Mikatz", "category": "CommandAndControl",
"title": "Windows Defender AV detected 'Mikatz', high-severity malware", "threatFamilyName": null,
"description": "Some description", "title": "Network connection to a risky host",
"alertCreationTime": "2018-11-26T16:19:21.8409809Z", "description": "A network connection was made to a risky host which has exhibited malicious activity.",
"firstEventTime": "2018-11-26T16:17:50.0948658Z", "alertCreationTime": "2019-11-03T23:49:45.3823185Z",
"lastEventTime": "2018-11-26T16:18:01.809871Z", "firstEventTime": "2019-11-03T23:47:16.2288822Z",
"resolvedTime": null, "lastEventTime": "2019-11-03T23:47:51.2966758Z",
"machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337" "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' - 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:** **Response:**
@ -135,25 +142,25 @@ Content-type: application/json
"value": [ "value": [
{ {
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com", "computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z", "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z", "lastSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10", "osPlatform": "Windows10",
"osVersion": "10.0.0.0", "version": "1709",
"lastIpAddress": "172.17.230.209", "osProcessor": "x64",
"lastExternalIpAddress": "167.220.196.71", "lastIpAddress": "172.17.230.209",
"agentVersion": "10.5830.18209.1001", "lastExternalIpAddress": "167.220.196.71",
"osBuild": 18209, "osBuild": 18209,
"healthStatus": "Active", "healthStatus": "Active",
"rbacGroupId": 140, "rbacGroupId": 140,
"rbacGroupName": "The-A-Team", "rbacGroupName": "The-A-Team",
"riskScore": "High", "riskScore": "High",
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9", "exposureLevel": "Medium",
"machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ] "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' - 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:** **Response:**
@ -176,25 +183,25 @@ Content-type: application/json
"value": [ "value": [
{ {
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com", "computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z", "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z", "lastSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10", "osPlatform": "Windows10",
"osVersion": "10.0.0.0", "version": "1709",
"lastIpAddress": "172.17.230.209", "osProcessor": "x64",
"lastExternalIpAddress": "167.220.196.71", "lastIpAddress": "172.17.230.209",
"agentVersion": "10.5830.18209.1001", "lastExternalIpAddress": "167.220.196.71",
"osBuild": 18209, "osBuild": 18209,
"healthStatus": "Active", "healthStatus": "ImpairedCommunication",
"rbacGroupId": 140, "rbacGroupId": 140,
"rbacGroupName": "The-A-Team", "rbacGroupName": "The-A-Team",
"riskScore": "High", "riskScore": "Low",
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9", "exposureLevel": "Medium",
"machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ] "isAadJoined": true,
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
"machineTags": [ "test tag 1", "ExampleTag" ]
}, },
. ...
.
.
] ]
} }
``` ```
@ -217,25 +224,25 @@ Content-type: application/json
"value": [ "value": [
{ {
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com", "computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z", "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z", "lastSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10", "osPlatform": "Windows10",
"osVersion": "10.0.0.0", "version": "1709",
"lastIpAddress": "172.17.230.209", "osProcessor": "x64",
"lastExternalIpAddress": "167.220.196.71", "lastIpAddress": "172.17.230.209",
"agentVersion": "10.5830.18209.1001", "lastExternalIpAddress": "167.220.196.71",
"osBuild": 18209, "osBuild": 18209,
"healthStatus": "Active", "healthStatus": "ImpairedCommunication",
"rbacGroupId": 140, "rbacGroupId": 140,
"rbacGroupName": "The-A-Team", "rbacGroupName": "The-A-Team",
"riskScore": "High", "riskScore": "Low",
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9", "exposureLevel": "Medium",
"machineTags": [ "test tag 1", "test tag 2", "ExampleTag" ] "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 - 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:** **Response:**
@ -257,19 +264,19 @@ Content-type: application/json
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions",
"value": [ "value": [
{ {
"id": "5c3e3322-d993-1234-1111-dfb136ebc8c5", "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan", "type": "RunAntiVirusScan",
"requestor": "Analyst@examples.onmicrosoft.com", "scope": "Full",
"requestorComment": "1533", "requestor": "Analyst@contoso.com",
"requestorComment": "Check machine for viruses due to alert 3212",
"status": "Succeeded", "status": "Succeeded",
"machineId": "123321c10e44a82877af76b1d0161a17843f688a", "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"creationDateTimeUtc": "2018-11-12T13:33:24.5755657Z", "computerDnsName": "desktop-39g9tgl",
"lastUpdateDateTimeUtc": "2018-11-12T13:34:32.0319826Z", "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"relatedFileInfo": null "lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
"relatedFileInfo": null
}, },
. ...
.
.
] ]
} }
``` ```

36
windows/security/threat-protection/microsoft-defender-atp/files.md
View File

@ -17,9 +17,10 @@ ms.topic: article
--- ---
# File resource type # 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. Represent a file entity in Microsoft Defender ATP.
@ -37,11 +38,10 @@ Property | Type | Description
:---|:---|:--- :---|:---|:---
sha1 | String | Sha1 hash of the file content sha1 | String | Sha1 hash of the file content
sha256 | String | Sha256 hash of the file content sha256 | String | Sha256 hash of the file content
md5 | String | md5 hash of the file content globalPrevalence | Nullable long | File prevalence across organization
globalPrevalence | Integer | File prevalence across organization
globalFirstObserved | DateTimeOffset | First time the file was observed. globalFirstObserved | DateTimeOffset | First time the file was observed.
globalLastObserved | DateTimeOffset | Last 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. fileType | String | Type of the file.
isPeFile | Boolean | true if the file is portable executable (e.g. "DLL", "EXE", etc.) isPeFile | Boolean | true if the file is portable executable (e.g. "DLL", "EXE", etc.)
filePublisher | String | File publisher. filePublisher | String | File publisher.
@ -50,3 +50,29 @@ signer | String | File signer.
issuer | String | File issuer. issuer | String | File issuer.
signerHash | String | Hash of the signing certificate. signerHash | String | Hash of the signing certificate.
isValidCertificate | Boolean | Was signing certificate successfully verified by Microsoft Defender ATP agent. 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"
}
```

48
windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip.md
View File

@ -18,13 +18,19 @@ ms.topic: article
# Find machines by internal IP API # 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 ## 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) 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)] [!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) GET https://api.securitycenter.windows.com/api/machines/findbyip(ip='10.248.240.38',timestamp=2019-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" ]
}
]
}
``` ```

57
windows/security/threat-protection/microsoft-defender-atp/get-alert-info-by-id.md
View File

@ -18,11 +18,19 @@ ms.topic: article
# Get alert information by ID API # 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 ## 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) 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 ## 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. 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"
}
```

16
windows/security/threat-protection/microsoft-defender-atp/get-alert-related-domain-info.md
View File

@ -18,12 +18,20 @@ ms.topic: article
# Get alert related domain information API # 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. 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 ## 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) 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": [ "value": [
{ {
"host": "www.example.com" "host": "www.example.com"
},
{
"host": "www.example2.com"
} }
...
] ]
} }

44
windows/security/threat-protection/microsoft-defender-atp/get-alert-related-files-info.md
View File

@ -18,12 +18,20 @@ ms.topic: article
# Get alert related files information API # 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. 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 ## 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) 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", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files",
"value": [ "value": [
{ {
"sha1": "654f19c41d9662cf86be21bf0af5a88c38c56a9d", "sha1": "f2a00fd2f2de1be0214b8529f1e9f67096c1aa70",
"sha256": "2f905feec2798cee6f63da2c26758d86bfeaab954c01e20ac7085bf55fedde87", "sha256": "dcd71ef5fff4362a9f64cf3f96f14f2b11d6f428f3badbedcb9ff3361e7079aa",
"md5": "82849dc81d94056224445ea73dc6153a", "md5": "8d5b7cc9a832e21d22503057e1fec8e9",
"globalPrevalence": 33, "globalPrevalence": 29,
"globalFirstObserved": "2018-07-17T18:17:27.5909748Z", "globalFirstObserved": "2019-03-23T23:54:06.0135204Z",
"globalLastObserved": "2018-08-06T16:07:12.9414137Z", "globalLastObserved": "2019-04-23T00:43:20.0489831Z",
"windowsDefenderAVThreatName": null, "size": 113984,
"size": 801112, "fileType": null,
"fileType": "PortableExecutable",
"isPeFile": true, "isPeFile": true,
"filePublisher": null, "filePublisher": "Microsoft Corporation",
"fileProductName": null, "fileProductName": "Microsoft® Windows® Operating System",
"signer": "Microsoft Windows", "signer": "Microsoft Corporation",
"issuer": "Microsoft Development PCA 2014", "issuer": "Microsoft Code Signing PCA",
"signerHash": "9e284231a4d1c53fc8d4492b09f65116bf97447f", "signerHash": "9dc17888b5cfad98b3cb35c1994e96227f061675",
"isValidCertificate": true "isValidCertificate": true,
"determinationType": "Unknown",
"determinationValue": null
} }
...
] ]
} }
``` ```

15
windows/security/threat-protection/microsoft-defender-atp/get-alert-related-ip-info.md
View File

@ -16,14 +16,22 @@ ms.collection: M365-security-compliance
ms.topic: article 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. 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 ## 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) 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 "id": "23.203.232.228
} }
...
] ]
} }

19
windows/security/threat-protection/microsoft-defender-atp/get-alert-related-machine-info.md
View File

@ -18,11 +18,19 @@ ms.topic: article
# Get alert related machine information API # 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 ## 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) 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", "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z", "lastSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10", "osPlatform": "Windows10",
"osVersion": "10.0.0.0", "version": "1709",
"osProcessor": "x64",
"lastIpAddress": "172.17.230.209", "lastIpAddress": "172.17.230.209",
"lastExternalIpAddress": "167.220.196.71", "lastExternalIpAddress": "167.220.196.71",
"agentVersion": "10.5830.18209.1001",
"osBuild": 18209, "osBuild": 18209,
"healthStatus": "Active", "healthStatus": "Active",
"rbacGroupId": 140, "rbacGroupId": 140,
"rbacGroupName": "The-A-Team", "rbacGroupName": "The-A-Team",
"riskScore": "Low", "riskScore": "Low",
"exposureLevel": "Medium",
"isAadJoined": true, "isAadJoined": true,
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9", "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
"machineTags": [ "test tag 1", "test tag 2" ] "machineTags": [ "test tag 1", "test tag 2" ]

29
windows/security/threat-protection/microsoft-defender-atp/get-alert-related-user-info.md
View File

@ -18,11 +18,19 @@ ms.topic: article
# Get alert related user information API # 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 ## 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) 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", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users/$entity",
"id": "contoso\\user1", "id": "contoso\\user1",
"firstSeen": "2018-08-02T00:00:00Z", "accountName": "user1",
"lastSeen": "2018-08-04T00:00:00Z", "accountDomain": "contoso",
"mostPrevalentMachineId": null, "accountSid": "S-1-5-21-72051607-1745760036-109187956-93922",
"leastPrevalentMachineId": null, "firstSeen": "2019-12-08T06:33:39Z",
"lastSeen": "2020-01-05T06:58:34Z",
"mostPrevalentMachineId": "0111b647235c26159bec3e5eb6c8c3a0cc3ab766",
"leastPrevalentMachineId": "0111b647235c26159bec3e5eb6c8c3a0cc3ab766",
"logonTypes": "Network", "logonTypes": "Network",
"logOnMachinesCount": 3, "logOnMachinesCount": 1,
"isDomainAdmin": false, "isDomainAdmin": false,
"isOnlyNetworkUser": null "isOnlyNetworkUser": false
} }
``` ```

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

@ -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) - 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. Retrieves a collection of Alerts.
<br>Supports [OData V4 queries](https://www.odata.org/documentation/).
<br>The OData's ```$filter``` query is supported on: ```alertCreationTime```, ```incidentId```, ```InvestigationId```, ```status```, ```severity``` and ```category``` properties.
<br>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 ## 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) 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 GET /api/alerts
``` ```
## Optional query parameters
Method supports $top, $select, $filter, $expand and $skip query parameters.
<br>$expand is available on Files, IPs and Domains. e.g. $expand=files,domains
## Request headers ## Request headers
Name | Type | Description Name | Type | Description
@ -120,11 +122,9 @@ Here is an example of the response.
"createdBy": "secop@contoso.com", "createdBy": "secop@contoso.com",
"createdTime": "2019-11-05T14:08:37.8404534Z" "createdTime": "2019-11-05T14:08:37.8404534Z"
} }
], ]
"alertFiles": [],
"alertDomains": [],
"alertIps": []
} }
...
] ]
} }
``` ```

1
windows/security/threat-protection/microsoft-defender-atp/get-cvekbmap-collection.md
View File

@ -15,6 +15,7 @@ manager: dansimp
audience: ITPro audience: ITPro
ms.collection: M365-security-compliance ms.collection: M365-security-compliance
ms.topic: article ms.topic: article
ROBOTS: NOINDEX
--- ---
# Get CVE-KB map API # Get CVE-KB map API

69
windows/security/threat-protection/microsoft-defender-atp/get-domain-related-alerts.md
View File

@ -18,11 +18,19 @@ ms.topic: article
# Get domain related alerts API # 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 ## 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) 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 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"
}
]
}
```

67
windows/security/threat-protection/microsoft-defender-atp/get-domain-related-machines.md
View File

@ -17,10 +17,20 @@ ms.topic: article
--- ---
# Get domain related machines API # 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 ## 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) 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 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" ]
}
]
}
```

14
windows/security/threat-protection/microsoft-defender-atp/get-domain-statistics.md
View File

@ -18,10 +18,18 @@ ms.topic: article
# Get domain statistics API # Get domain 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 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 ## 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) 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
windows/security/threat-protection/microsoft-defender-atp/get-file-information.md
View File

@ -17,10 +17,19 @@ ms.topic: article
--- ---
# Get file information API # 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 ## 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) 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)] [!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** **Response**
@ -74,22 +83,22 @@ Here is an example of the response.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-type: application/json Content-type: application/json
{ {
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files/$entity", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files/$entity",
"sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1", "sha1": "4388963aaa83afe2042a46a3c017ad50bdcdafb3",
"sha256": "d4447dffdbb2889b4b4e746b0bc882df1b854101614b0aa83953ef3cb66904cf", "sha256": "413c58c8267d2c8648d8f6384bacc2ae9c929b2b96578b6860b5087cd1bd6462",
"md5": "7f05a371d2beffb3784fd2199f81d730", "globalPrevalence": 180022,
"globalPrevalence": 7329, "globalFirstObserved": "2017-09-19T03:51:27.6785431Z",
"globalFirstObserved": "2018-04-08T05:50:29.4459725Z", "globalLastObserved": "2020-01-06T03:59:21.3229314Z",
"globalLastObserved": "2018-08-07T23:35:11.1361328Z", "size": 22139496,
"windowsDefenderAVThreatName": null, "fileType": "APP",
"size": 391680, "isPeFile": true,
"fileType": "PortableExecutable", "filePublisher": "CHENGDU YIWO Tech Development Co., Ltd.",
"isPeFile": true, "fileProductName": "EaseUS MobiSaver for Android",
"filePublisher": null, "signer": "CHENGDU YIWO Tech Development Co., Ltd.",
"fileProductName": null, "issuer": "VeriSign Class 3 Code Signing 2010 CA",
"signer": null, "signerHash": "6c3245d4a9bc0244d99dff27af259cbbae2e2d16",
"issuer": null, "isValidCertificate": false,
"signerHash": null, "determinationType": "Pua",
"isValidCertificate": null "determinationValue": "PUA:Win32/FusionCore"
} }
``` ```

46
windows/security/threat-protection/microsoft-defender-atp/get-file-related-alerts.md
View File

@ -18,12 +18,19 @@ ms.topic: article
# Get file related alerts API # 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. 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 ## 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) 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 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"
}
]
}
```

62
windows/security/threat-protection/microsoft-defender-atp/get-file-related-machines.md
View File

@ -18,11 +18,18 @@ ms.topic: article
# Get file related machines API # 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 ## 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) 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 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" ]
}
]
}
```

29
windows/security/threat-protection/microsoft-defender-atp/get-file-statistics.md
View File

@ -18,11 +18,18 @@ ms.topic: article
# Get file statistics API # 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 ## 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) 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)] [!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** **Response**
@ -77,13 +84,15 @@ HTTP/1.1 200 OK
Content-type: application/json Content-type: application/json
{ {
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgFileStats", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgFileStats",
"sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1", "sha1": "0991a395da64e1c5fbe8732ed11e6be064081d9f",
"orgPrevalence": "3", "orgPrevalence": "14850",
"orgFirstSeen": "2018-07-15T06:13:59Z", "orgFirstSeen": "2019-12-07T13:44:16Z",
"orgLastSeen": "2018-08-03T16:45:21Z", "orgLastSeen": "2020-01-06T13:39:36Z",
"globalPrevalence": "705012",
"globalFirstObserved": "2015-03-19T12:20:07.3432441Z",
"globalLastObserved": "2020-01-06T13:39:36Z",
"topFileNames": [ "topFileNames": [
"chrome_1.exe", "MREC.exe"
"chrome_2.exe"
] ]
} }

110
windows/security/threat-protection/microsoft-defender-atp/get-investigation-collection.md Normal file
View File

@ -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).
<br>Supports [OData V4 queries](https://www.odata.org/documentation/).
<br>The OData's ```$filter``` query is supported on: ```startTime```, ```state```, ```machineId``` and ```triggeringAlertId``` properties.
<br>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"
}
...
]
}
```

66
windows/security/threat-protection/microsoft-defender-atp/get-investigation-object.md Normal file
View File

@ -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.
<br> 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.

48
windows/security/threat-protection/microsoft-defender-atp/get-ip-related-alerts.md
View File

@ -18,12 +18,19 @@ ms.topic: article
# Get IP related alerts API # 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. 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 ## 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) 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 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"
}
]
}
```

13
windows/security/threat-protection/microsoft-defender-atp/get-ip-statistics.md
View File

@ -18,11 +18,18 @@ ms.topic: article
# Get IP statistics API # 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 ## 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) 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)

2
windows/security/threat-protection/microsoft-defender-atp/get-kbinfo-collection.md
View File

@ -15,7 +15,7 @@ manager: dansimp
audience: ITPro audience: ITPro
ms.collection: M365-security-compliance ms.collection: M365-security-compliance
ms.topic: article ms.topic: article
ms.date: 10/07/2018 ROBOTS: NOINDEX
--- ---
# Get KB collection API # Get KB collection API

40
windows/security/threat-protection/microsoft-defender-atp/get-machine-by-id.md
View File

@ -18,11 +18,19 @@ ms.topic: article
# Get machine by ID API # 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 ## 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) 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", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machine",
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com", "computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z", "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z", "lastSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10", "osPlatform": "Windows10",
"osVersion": "10.0.0.0", "version": "1709",
"lastIpAddress": "172.17.230.209", "osProcessor": "x64",
"lastExternalIpAddress": "167.220.196.71", "lastIpAddress": "172.17.230.209",
"agentVersion": "10.5830.18209.1001", "lastExternalIpAddress": "167.220.196.71",
"osBuild": 18209, "osBuild": 18209,
"healthStatus": "Active", "healthStatus": "Active",
"rbacGroupId": 140, "rbacGroupId": 140,
"rbacGroupName": "The-A-Team", "rbacGroupName": "The-A-Team",
"riskScore": "Low", "riskScore": "Low",
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9", "exposureLevel": "Medium",
"isAadJoined": true,
"aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
"machineTags": [ "test tag 1", "test tag 2" ] "machineTags": [ "test tag 1", "test tag 2" ]
} }

45
windows/security/threat-protection/microsoft-defender-atp/get-machine-log-on-users.md
View File

@ -18,11 +18,19 @@ ms.topic: article
# Get machine log on users API # 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 ## 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) 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": [ "value": [
{ {
"id": "contoso\\user1", "id": "contoso\\user1",
"firstSeen": "2018-08-02T00:00:00Z", "accountName": "user1",
"lastSeen": "2018-08-04T00:00:00Z", "accountDomain": "contoso",
"mostPrevalentMachineId": null, "accountSid": "S-1-5-21-72051607-1745760036-109187956-93922",
"leastPrevalentMachineId": null, "firstSeen": "2019-12-18T08:02:54Z",
"logonTypes": "Network", "lastSeen": "2020-01-06T08:01:48Z",
"logOnMachinesCount": 3, "mostPrevalentMachineId": "111153d0c675eaa415b8e5f383c6388bff446c62",
"isDomainAdmin": false, "leastPrevalentMachineId": "111153d0c675eaa415b8e5f383c6388bff446c62",
"isOnlyNetworkUser": null "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
}
] ]
} }
``` ```

66
windows/security/threat-protection/microsoft-defender-atp/get-machine-related-alerts.md
View File

@ -17,13 +17,20 @@ ms.topic: article
--- ---
# Get machine related alerts API # 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 Permission type | Permission | Permission display name
:---|:---|:--- :---|:---|:---
@ -54,52 +61,3 @@ Empty
## Response ## 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. 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"
}
]
}
```

32
windows/security/threat-protection/microsoft-defender-atp/get-machineaction-object.md
View File

@ -18,10 +18,18 @@ ms.topic: article
# Get machineAction API # Get machineAction 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 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 ## 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) 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 Content-type: application/json
{ {
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba", "id": "5382f7ea-7557-4ab7-9782-d50480024a4e",
"type": "RunAntiVirusScan", "type": "Isolate",
"requestor": "Analyst@contoso.com", "scope": "Selective",
"requestorComment": "Check machine for viruses due to alert 3212", "requestor": "Analyst@TestPrd.onmicrosoft.com",
"requestorComment": "test for docs",
"status": "Succeeded", "status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", "machineId": "7b1f4967d9728e5aa3c06a9e617a22a4a5a17378",
"creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z", "computerDnsName": "desktop-test",
"lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z", "creationDateTimeUtc": "2019-01-02T14:39:38.2262283Z",
"relatedFileInfo": null "lastUpdateDateTimeUtc": "2019-01-02T14:40:44.6596267Z",
"relatedFileInfo": null
} }

27
windows/security/threat-protection/microsoft-defender-atp/get-machineactions-collection.md
View File

@ -18,17 +18,22 @@ ms.topic: article
# List MachineActions API # 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).
<br>Supports [OData V4 queries](https://www.odata.org/documentation/).
<br>The OData's ```$filter``` query is supported on: ```status```, ```machineId```, ```type```, ```requestor``` and ```creationDateTimeUtc``` properties.
<br>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 ## 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) 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", "id": "69dc3630-1ccc-4342-acf3-35286eec741d",
"type": "CollectInvestigationPackage", "type": "CollectInvestigationPackage",
"scope": null,
"requestor": "Analyst@contoso.com", "requestor": "Analyst@contoso.com",
"requestorComment": "test", "requestorComment": "test",
"status": "Succeeded", "status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z", "creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z",
"lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z", "lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z",
"relatedFileInfo": null "relatedFileInfo": null
@ -100,10 +107,12 @@ Content-type: application/json
{ {
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba", "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan", "type": "RunAntiVirusScan",
"scope": "Full",
"requestor": "Analyst@contoso.com", "requestor": "Analyst@contoso.com",
"requestorComment": "Check machine for viruses due to alert 3212", "requestorComment": "Check machine for viruses due to alert 3212",
"status": "Succeeded", "status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z", "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z", "lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
"relatedFileInfo": null "relatedFileInfo": null
@ -111,10 +120,12 @@ Content-type: application/json
{ {
"id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e", "id": "44cffc15-0e3d-4cbf-96aa-bf76f9b27f5e",
"type": "StopAndQuarantineFile", "type": "StopAndQuarantineFile",
"scope": null,
"requestor": "Analyst@contoso.com", "requestor": "Analyst@contoso.com",
"requestorComment": "test", "requestorComment": "test",
"status": "Succeeded", "status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:15:40.6052029Z", "creationDateTimeUtc": "2018-12-04T12:15:40.6052029Z",
"lastUpdateTimeUtc": "2018-12-04T12:16:14.2899973Z", "lastUpdateTimeUtc": "2018-12-04T12:16:14.2899973Z",
"relatedFileInfo": { "relatedFileInfo": {
@ -151,10 +162,12 @@ Content-type: application/json
{ {
"id": "69dc3630-1ccc-4342-acf3-35286eec741d", "id": "69dc3630-1ccc-4342-acf3-35286eec741d",
"type": "CollectInvestigationPackage", "type": "CollectInvestigationPackage",
"scope": null,
"requestor": "Analyst@contoso.com", "requestor": "Analyst@contoso.com",
"requestorComment": "test", "requestorComment": "test",
"status": "Succeeded", "status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z", "creationDateTimeUtc": "2018-12-04T12:43:57.2011911Z",
"lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z", "lastUpdateTimeUtc": "2018-12-04T12:45:25.4049122Z",
"relatedFileInfo": null "relatedFileInfo": null
@ -162,10 +175,12 @@ Content-type: application/json
{ {
"id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba", "id": "2e9da30d-27f6-4208-81f2-9cd3d67893ba",
"type": "RunAntiVirusScan", "type": "RunAntiVirusScan",
"scope": "Full",
"requestor": "Analyst@contoso.com", "requestor": "Analyst@contoso.com",
"requestorComment": "Check machine for viruses due to alert 3212", "requestorComment": "Check machine for viruses due to alert 3212",
"status": "Succeeded", "status": "Succeeded",
"machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f", "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
"computerDnsName": "desktop-39g9tgl",
"creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z", "creationDateTimeUtc": "2018-12-04T12:18:27.1293487Z",
"lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z", "lastUpdateTimeUtc": "2018-12-04T12:18:57.5511934Z",
"relatedFileInfo": null "relatedFileInfo": null

67
windows/security/threat-protection/microsoft-defender-atp/get-machines.md
View File

@ -18,17 +18,23 @@ ms.topic: article
# List machines API # 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. ## API description
- Get Machines collection API supports [OData V4 queries](https://www.odata.org/documentation/). Retrieves a collection of [Machines](machine.md) that have communicated with Microsoft Defender ATP cloud on the last 30 days.
- The OData's Filter query is supported on: "Id", "ComputerDnsName", "LastSeen", "LastIpAddress", "HealthStatus", "OsPlatform", "RiskScore", "MachineTags" and "RbacGroupId". <br>Supports [OData V4 queries](https://www.odata.org/documentation/).
<br>The OData's ```$filter``` query is supported on: ```computerDnsName```, ```lastSeen```, ```lastIpAddress```, ```healthStatus```, ```osPlatform```, ```riskScore```, ```rbacGroupId``` and ```machineTags``` properties.
<br>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 ## Permissions
@ -88,42 +94,25 @@ Content-type: application/json
"value": [ "value": [
{ {
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
"computerDnsName": "mymachine1.contoso.com", "computerDnsName": "mymachine1.contoso.com",
"firstSeen": "2018-08-02T14:55:03.7791856Z", "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z", "lastSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10", "osPlatform": "Windows10",
"osVersion": "10.0.0.0", "version": "1709",
"lastIpAddress": "172.17.230.209", "osProcessor": "x64",
"lastExternalIpAddress": "167.220.196.71", "lastIpAddress": "172.17.230.209",
"agentVersion": "10.5830.18209.1001", "lastExternalIpAddress": "167.220.196.71",
"osBuild": 18209, "osBuild": 18209,
"healthStatus": "Active", "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",
"rbacGroupId": 140, "rbacGroupId": 140,
"rbacGroupName": "The-A-Team", "rbacGroupName": "The-A-Team",
"riskScore": "Low", "riskScore": "Low",
"isAadJoined": false, "exposureLevel": "Medium",
"aadDeviceId": null, "isAadJoined": true,
"machineTags": [ "test tag 1" ] "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
"machineTags": [ "test tag 1", "test tag 2" ]
} }
...
] ]
} }
``` ```

9
windows/security/threat-protection/microsoft-defender-atp/get-package-sas-uri.md
View File

@ -18,11 +18,14 @@ ms.topic: article
# Get package SAS URI API # 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 ## 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) 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)

47
windows/security/threat-protection/microsoft-defender-atp/get-ti-indicators-collection.md
View File

@ -18,16 +18,21 @@ ms.topic: article
# List Indicators API # List Indicators 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)
>[!NOTE] ## API description
> 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) Retrieves a collection of all active [Indicators](ti-indicator.md).
<br>Supports [OData V4 queries](https://www.odata.org/documentation/).
<br>The OData's ```$filter``` query is supported on: ```indicatorValue```, ```indicatorType```, ```creationTimeDateTimeUtc```, ```createdBy```, ```action``` and ```severity``` properties.
<br>See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
- Gets collection of TI Indicators. ## Limitations
- Get TI Indicators collection API supports [OData V4 queries](https://www.odata.org/documentation/). 1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
## Permissions ## 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) 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 | 'Read and write Indicators'
Application | Ti.ReadWrite.All | 'Read and write All Indicators' Application | Ti.ReadWrite.All | 'Read and write All Indicators'
Delegated (work or school account) | Ti.ReadWrite | 'Read and write Indicators'
## HTTP request ## HTTP request
``` ```
@ -82,26 +87,38 @@ Content-type: application/json
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators",
"value": [ "value": [
{ {
"id": "995",
"indicatorValue": "12.13.14.15", "indicatorValue": "12.13.14.15",
"indicatorType": "IpAddress", "indicatorType": "IpAddress",
"action": "Alert",
"application": "demo-test",
"source": "TestPrdApp",
"sourceType": "AadApp",
"title": "test", "title": "test",
"creationTimeDateTimeUtc": "2018-10-24T11:15:35.3688259Z", "creationTimeDateTimeUtc": "2018-10-24T11:15:35.3688259Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c", "createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z", "expirationTime": "2020-12-12T00:00:00Z",
"action": "Alert", "lastUpdateTime": "2019-10-24T10:54:23.2009016Z",
"lastUpdatedBy": TestPrdApp,
"severity": "Informational", "severity": "Informational",
"description": "test", "description": "test",
"recommendedActions": "test", "recommendedActions": "test",
"rbacGroupNames": [] "rbacGroupNames": []
}, },
{ {
"id": "996",
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", "indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1", "indicatorType": "FileSha1",
"action": "AlertAndBlock",
"application": null,
"source": "TestPrdApp",
"sourceType": "AadApp",
"title": "test", "title": "test",
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z", "creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c", "createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z", "expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock", "lastUpdateTime": "2019-10-24T10:54:23.2009016Z",
"lastUpdatedBy": TestPrdApp,
"severity": "Informational", "severity": "Informational",
"description": "test", "description": "test",
"recommendedActions": "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 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** **Response**
@ -133,13 +150,19 @@ Content-type: application/json
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators", "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Indicators",
"value": [ "value": [
{ {
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", "id": "997",
"indicatorValue": "111e7d15b0b3d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1", "indicatorType": "FileSha1",
"action": "AlertAndBlock",
"application": null,
"source": "TestPrdApp",
"sourceType": "AadApp",
"title": "test", "title": "test",
"creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z", "creationTimeDateTimeUtc": "2018-10-24T10:54:23.2009016Z",
"createdBy": "45097602-1234-5678-1234-9f453233e62c", "createdBy": "45097602-1234-5678-1234-9f453233e62c",
"expirationTime": "2020-12-12T00:00:00Z", "expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock", "lastUpdateTime": "2019-10-24T10:54:23.2009016Z",
"lastUpdatedBy": TestPrdApp,
"severity": "Informational", "severity": "Informational",
"description": "test", "description": "test",
"recommendedActions": "TEST", "recommendedActions": "TEST",

68
windows/security/threat-protection/microsoft-defender-atp/get-user-related-alerts.md
View File

@ -18,12 +18,19 @@ ms.topic: article
# Get user related alerts API # 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. 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 ## 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) 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 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"
}
]
}
```

62
windows/security/threat-protection/microsoft-defender-atp/get-user-related-machines.md
View File

@ -18,12 +18,19 @@ ms.topic: article
# Get user related machines API # 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. 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 ## 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) 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 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" ]
}
]
}
```

58
windows/security/threat-protection/microsoft-defender-atp/initiate-autoir-investigation.md
View File

@ -1,7 +1,7 @@
--- ---
title: Initiate machine investigation API title: Start Investigation API
description: Use this API to create calls related to initiating an investigation on a machine. description: Use this API to start investigation on a machine.
keywords: apis, graph api, supported apis, initiate AutoIR investigation keywords: apis, graph api, supported apis, investigation
search.product: eADQiWindows 10XVcnh search.product: eADQiWindows 10XVcnh
ms.prod: w10 ms.prod: w10
ms.mktglfcycl: deploy ms.mktglfcycl: deploy
@ -16,38 +16,39 @@ ms.collection: M365-security-compliance
ms.topic: article ms.topic: article
--- ---
# Initiate machine investigation API (Preview) # Start Investigation API
**Applies to:**
- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
> [!IMPORTANT] **Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
> Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Initiate AutoIR investigation on a machine. - 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.
<br>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 ## Limitations
1. The number of executions is limited (up to 5 calls per hour). 1. Rate limitations for this API are 50 calls per hour.
2. For Automated Investigation limitations, see [Automated Investigation](automated-investigations.md).
## Permissions ## 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) 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 Permission type | Permission | Permission display name
:---|:---|:--- :---|:---|:---
Application | Alert.ReadWrite.All | 'Read and write all alerts' Application | Alert.ReadWrite.All | 'Read and write all alerts'
Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
>[!Note] >[!Note]
> When obtaining a token using user credentials: > 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) >- 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 ## HTTP request
``` ```
POST https://api.securitycenter.windows.com/api/machines/{id}/InitiateInvestigation POST https://api.securitycenter.microsoft.com/api/machines/{id}/startInvestigation
``` ```
## Request headers ## Request headers
@ -64,8 +65,10 @@ Parameter | Type | Description
:---|:---|:--- :---|:---|:---
Comment | String | Comment to associate with the action. **Required**. Comment | String | Comment to associate with the action. **Required**.
## Response ## 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 ## Example
@ -76,23 +79,8 @@ Here is an example of the request.
[!include[Improve request performance](../../includes/improve-request-performance.md)] [!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 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
}
```

64
windows/security/threat-protection/microsoft-defender-atp/investigation.md Normal file
View File

@ -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.
<br> 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"
}
```

35
windows/security/threat-protection/microsoft-defender-atp/isolate-machine.md
View File

@ -18,12 +18,19 @@ ms.topic: article
# Isolate machine API # 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. 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)] [!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions ## Permissions
@ -85,27 +92,5 @@ Content-type: application/json
“IsolationType”: “Full” “IsolationType”: “Full”
} }
```
**Response**
Here is an example of the response. - To unisolate a machine, see [Release machine from isolation](unisolate-machine.md).
```
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).

46
windows/security/threat-protection/microsoft-defender-atp/machine.md
View File

@ -17,8 +17,10 @@ ms.topic: article
--- ---
# Machine resource type # 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 ## Methods
@ -38,15 +40,41 @@ id | String | [machine](machine.md) identity.
computerDnsName | String | [machine](machine.md) fully qualified name. 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. 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. lastSeen | DateTimeOffset | Last date and time where the [machine](machine.md) was observed by Microsoft Defender ATP.
osPlatform | String | OS platform. osPlatform | String | Operating system platform.
osVersion | String | OS Version. version | String | Operating system Version.
osBuild | Nullable long | Operating system build number.
lastIpAddress | String | Last IP on local NIC on the [machine](machine.md). 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. 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" healthStatus | Enum | [machine](machine.md) health status. Possible values are: "Active", "Inactive", "ImpairedCommunication", "NoSensorData" and "NoSensorDataImpairedCommunication"
rbacGroupId | Int | RBAC Group ID. rbacGroupName | String | Machine group Name.
rbacGroupName | String | RBAC 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'. 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. 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" ]
}
```

32
windows/security/threat-protection/microsoft-defender-atp/machineaction.md
View File

@ -18,8 +18,11 @@ ms.topic: article
# MachineAction resource type # MachineAction 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 [Response Actions](respond-machine-alerts.md) for more information
| Method | Return Type | Description | | 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. | | [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). | | [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. | | [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. |
<br> <br>
@ -42,11 +46,31 @@ ms.topic: article
|:--------------------|:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:--------------------|:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id | Guid | Identity of the [Machine Action](machineaction.md) entity. | | 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" | | 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. | | requestor | String | Identity of the person that executed the action. |
| requestorComment | String | Comment that was written when issuing 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". | | 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. | | creationDateTimeUtc | DateTimeOffset | The date and time when the action was created. |
| lastUpdateTimeUtc | DateTimeOffset | The last date and time when the action status was updated. | | 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
}
```

35
windows/security/threat-protection/microsoft-defender-atp/offboard-machine-api.md
View File

@ -18,12 +18,19 @@ ms.topic: article
# Offboard machine API # 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. 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)] [!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions ## Permissions
@ -76,26 +83,4 @@ Content-type: application/json
{ {
"Comment": "Offboard machine by automation" "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
}
```

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

@ -381,7 +381,12 @@
####### [Run antivirus scan](run-av-scan.md) ####### [Run antivirus scan](run-av-scan.md)
####### [Offboard machine](offboard-machine-api.md) ####### [Offboard machine](offboard-machine-api.md)
####### [Stop and quarantine file](stop-and-quarantine-file.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]() ###### [Indicators]()
####### [Methods and properties](ti-indicator.md) ####### [Methods and properties](ti-indicator.md)

55
windows/security/threat-protection/microsoft-defender-atp/post-ti-indicator.md
View File

@ -18,18 +18,19 @@ ms.topic: article
# Submit or Update Indicator API # Submit or Update Indicator 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)
>[!NOTE] ## API description
> 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) Submits or Updates new [Indicator](ti-indicator.md) entity.
<br>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 ## 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) 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 | 'Read and write Indicators'
Application | Ti.ReadWrite.All | 'Read and write All Indicators' Application | Ti.ReadWrite.All | 'Read and write All Indicators'
Delegated (work or school account) | Ti.ReadWrite | 'Read and write Indicators'
## HTTP request ## HTTP request
@ -63,16 +65,17 @@ Parameter | Type | Description
indicatorValue | String | Identity of the [Indicator](ti-indicator.md) entity. **Required** 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** 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** 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** 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** 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** recommendedActions | String | TI indicator alert recommended actions. **Optional**
## Response ## Response
- If successful, this method returns 200 - OK response code and the created / updated [Indicator](ti-indicator.md) entity in the response body. - 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 ## Example
@ -84,40 +87,16 @@ Here is an example of the request.
POST https://api.securitycenter.windows.com/api/indicators POST https://api.securitycenter.windows.com/api/indicators
Content-type: application/json Content-type: application/json
{ {
"indicatorValue": "220e7d15b0b3d7fac48f2bd61114db1022197f7f", "indicatorValue": "220e7d15b011d7fac48f2bd61114db1022197f7f",
"indicatorType": "FileSha1", "indicatorType": "FileSha1",
"title": "test", "title": "test",
"application": "demo-test",
"expirationTime": "2020-12-12T00:00:00Z", "expirationTime": "2020-12-12T00:00:00Z",
"action": "AlertAndBlock", "action": "AlertAndBlock",
"severity": "Informational", "severity": "Informational",
"description": "test", "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 ## Related topic
- [Manage indicators](manage-indicators.md) - [Manage indicators](manage-indicators.md)

38
windows/security/threat-protection/microsoft-defender-atp/restrict-code-execution.md
View File

@ -18,11 +18,18 @@ ms.topic: article
# Restrict app execution API # 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)] [!include[Machine actions note](../../includes/machineactionsnote.md)]
@ -76,29 +83,6 @@ Content-type: application/json
} }
``` ```
**Response**
Here is an example of the response. - To remove code execution restriction from a machine, see [Remove app restriction](unrestrict-code-execution.md).
[!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).

34
windows/security/threat-protection/microsoft-defender-atp/run-av-scan.md
View File

@ -18,12 +18,19 @@ ms.topic: article
# Run antivirus scan API # 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. 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)] [!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions ## 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
}
```

38
windows/security/threat-protection/microsoft-defender-atp/stop-and-quarantine-file.md
View File

@ -18,12 +18,19 @@ ms.topic: article
# Stop and quarantine file API # 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. 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)] [!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions ## 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"
}
}
```

56
windows/security/threat-protection/microsoft-defender-atp/ti-indicator.md
View File

@ -18,9 +18,11 @@ ms.topic: article
# Indicator resource type # 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 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. [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. [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 ## Properties
Property | Type | Description Property | Type | Description
:---|:---|:--- :---|:---|:---
indicatorValue | String | Identity of the [Indicator](ti-indicator.md) entity. id | String | Identity of the [Indicator](ti-indicator.md) entity.
indicatorType | Enum | Type of the indicator. Possible values are: "FileSha1", "FileSha256", "IpAddress", "DomainName" and "Url" indicatorValue | String | The value of the [Indicator](ti-indicator.md).
title | String | Indicator alert title. 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. 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.
expirationTime | DateTimeOffset | The expiration time of the indicator lastUpdateTime | DateTimeOffset | The last time the indicator was updated.
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".
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. description | String | Description of the indicator.
recommendedActions | String | Indicator alert recommended actions. recommendedActions | String | Recommended actions for the indicator.
rbacGroupNames | List of strings | RBAC group names where the indicator is exposed. Empty list in case it exposed to all groups. 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"]
}
```

36
windows/security/threat-protection/microsoft-defender-atp/unisolate-machine.md
View File

@ -19,12 +19,19 @@ ms.topic: article
# Release machine from isolation API # 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. 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)] [!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions ## Permissions
@ -80,30 +87,7 @@ Content-type: application/json
} }
``` ```
**Response**
Here is an example of the response.
>[!NOTE] - To isolate a machine, see [Isolate machine](isolate-machine.md).
>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).

32
windows/security/threat-protection/microsoft-defender-atp/unrestrict-code-execution.md
View File

@ -18,12 +18,19 @@ ms.topic: article
# Remove app restriction API # 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. 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)] [!include[Machine actions note](../../includes/machineactionsnote.md)]
## Permissions ## 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). To restrict code execution on a machine, see [Restrict app execution](restrict-code-execution.md).

54
windows/security/threat-protection/microsoft-defender-atp/update-alert.md
View File

@ -18,11 +18,21 @@ ms.topic: article
# Update alert # 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).
<br>Submission of **comment** is available with or without updating properties.
<br>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 ## 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) 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 ## 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.
<br>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.
<br>For best performance you shouldn't include existing values that haven't change.
Property | Type | Description 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 assignedTo | String | Owner of the alert
classification | String | Specifies the specification of the alert. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'. 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' 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)] [!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 PATCH https://api.securitycenter.windows.com/api/alerts/121688558380765161_2136280442
Content-Type: application/json Content-Type: application/json
{ {
"assignedTo": "secop2@contoso.com" "status": "Resolved",
}
```
**Response**
Here is an example of the response.
```
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts/$entity",
"id": "121688558380765161_2136280442",
"incidentId": 7696,
"assignedTo": "secop2@contoso.com", "assignedTo": "secop2@contoso.com",
"severity": "High", "classification": "FalsePositive",
"status": "New", "determination": "Malware",
"classification": "TruePositive", "comment": "Resolve my alert and assign to secop2"
"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"
} }
``` ```

5
windows/security/threat-protection/microsoft-defender-atp/user.md
View File

@ -18,8 +18,9 @@ ms.topic: article
# User resource type # User 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)
Method|Return Type |Description Method|Return Type |Description
:---|:---|:--- :---|:---|:---