deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-23 14:23:38 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

machine finish

Browse Source
This commit is contained in:
Ben Alfasi
2020-01-06 11:39:49 +02:00
parent 72ac42fd62
commit cdddcf81c8
8 changed files with 139 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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.

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" ]
}
]
}
``` ```

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

@ -93,7 +93,7 @@ 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",
"version": null, "version": "1709",
"osProcessor": "x64", "osProcessor": "x64",
"lastIpAddress": "172.17.230.209", "lastIpAddress": "172.17.230.209",
"lastExternalIpAddress": "167.220.196.71", "lastExternalIpAddress": "167.220.196.71",

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"
}
]
}
```

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

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

@ -50,5 +50,31 @@ rbacGroupName | String | Machine group Name.
rbacGroupId | Int | Machine group unique ID. 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'.
exposureScore | Nullable Enum | [Exposure score](tvm-exposure-score.md) as evaluated by Microsoft Defender ATP. Possible values are: 'None', 'Low', 'Medium' and 'High'. 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 Guid | AAD Device ID (when [machine](machine.md) is Aad Joined). 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" ]
}
```