From 895143b9cc97bc9f6213c9c1860bed263d7da8b3 Mon Sep 17 00:00:00 2001 From: Ben Alfasi Date: Mon, 6 Jan 2020 15:44:52 +0200 Subject: [PATCH] files --- .../microsoft-defender-atp/files.md | 36 +++++++++-- .../get-file-information.md | 51 ++++++++------- .../get-file-related-alerts.md | 46 +++----------- .../get-file-related-machines.md | 62 +++---------------- .../get-file-statistics.md | 27 +++++--- 5 files changed, 98 insertions(+), 124 deletions(-) diff --git a/windows/security/threat-protection/microsoft-defender-atp/files.md b/windows/security/threat-protection/microsoft-defender-atp/files.md index d4cc5e85cb..5ef6fc7ec4 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/files.md +++ b/windows/security/threat-protection/microsoft-defender-atp/files.md @@ -17,9 +17,10 @@ ms.topic: article --- # File resource type -**Applies to:** -- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) +**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) + +- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) Represent a file entity in Microsoft Defender ATP. @@ -37,11 +38,10 @@ Property | Type | Description :---|:---|:--- sha1 | String | Sha1 hash of the file content sha256 | String | Sha256 hash of the file content -md5 | String | md5 hash of the file content -globalPrevalence | Integer | File prevalence across organization +globalPrevalence | Nullable long | File prevalence across organization globalFirstObserved | DateTimeOffset | First time the file was observed. globalLastObserved | DateTimeOffset | Last time the file was observed. -size | Integer | Size of the file. +size | Nullable long | Size of the file. fileType | String | Type of the file. isPeFile | Boolean | true if the file is portable executable (e.g. "DLL", "EXE", etc.) filePublisher | String | File publisher. @@ -50,3 +50,29 @@ signer | String | File signer. issuer | String | File issuer. signerHash | String | Hash of the signing certificate. isValidCertificate | Boolean | Was signing certificate successfully verified by Microsoft Defender ATP agent. +determinationType | String | The determination type of the file. +determinationValue | String | Determination value. + + +## Json representation + +```json +{ + "sha1": "4388963aaa83afe2042a46a3c017ad50bdcdafb3", + "sha256": "413c58c8267d2c8648d8f6384bacc2ae9c929b2b96578b6860b5087cd1bd6462", + "globalPrevalence": 180022, + "globalFirstObserved": "2017-09-19T03:51:27.6785431Z", + "globalLastObserved": "2020-01-06T03:59:21.3229314Z", + "size": 22139496, + "fileType": "APP", + "isPeFile": true, + "filePublisher": "CHENGDU YIWO Tech Development Co., Ltd.", + "fileProductName": "EaseUS MobiSaver for Android", + "signer": "CHENGDU YIWO Tech Development Co., Ltd.", + "issuer": "VeriSign Class 3 Code Signing 2010 CA", + "signerHash": "6c3245d4a9bc0244d99dff27af259cbbae2e2d16", + "isValidCertificate": false, + "determinationType": "Pua", + "determinationValue": "PUA:Win32/FusionCore" +} +``` \ No newline at end of file diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-file-information.md b/windows/security/threat-protection/microsoft-defender-atp/get-file-information.md index 0c499a7062..db2c9f018f 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/get-file-information.md +++ b/windows/security/threat-protection/microsoft-defender-atp/get-file-information.md @@ -17,10 +17,19 @@ ms.topic: article --- # Get file information API -**Applies to:** -- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) -Retrieves a file by identifier Sha1, Sha256, or MD5. +**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) + +- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + + +## API description +Retrieves a [File](files.md) by identifier Sha1, or Sha256 + + +## Limitations +1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour. + ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md) @@ -62,7 +71,7 @@ Here is an example of the request. [!include[Improve request performance](../../includes/improve-request-performance.md)] ``` -GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1 +GET https://api.securitycenter.windows.com/api/files/4388963aaa83afe2042a46a3c017ad50bdcdafb3 ``` **Response** @@ -74,22 +83,22 @@ Here is an example of the response. HTTP/1.1 200 OK Content-type: application/json { - "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files/$entity", - "sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1", - "sha256": "d4447dffdbb2889b4b4e746b0bc882df1b854101614b0aa83953ef3cb66904cf", - "md5": "7f05a371d2beffb3784fd2199f81d730", - "globalPrevalence": 7329, - "globalFirstObserved": "2018-04-08T05:50:29.4459725Z", - "globalLastObserved": "2018-08-07T23:35:11.1361328Z", - "windowsDefenderAVThreatName": null, - "size": 391680, - "fileType": "PortableExecutable", - "isPeFile": true, - "filePublisher": null, - "fileProductName": null, - "signer": null, - "issuer": null, - "signerHash": null, - "isValidCertificate": null + "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files/$entity", + "sha1": "4388963aaa83afe2042a46a3c017ad50bdcdafb3", + "sha256": "413c58c8267d2c8648d8f6384bacc2ae9c929b2b96578b6860b5087cd1bd6462", + "globalPrevalence": 180022, + "globalFirstObserved": "2017-09-19T03:51:27.6785431Z", + "globalLastObserved": "2020-01-06T03:59:21.3229314Z", + "size": 22139496, + "fileType": "APP", + "isPeFile": true, + "filePublisher": "CHENGDU YIWO Tech Development Co., Ltd.", + "fileProductName": "EaseUS MobiSaver for Android", + "signer": "CHENGDU YIWO Tech Development Co., Ltd.", + "issuer": "VeriSign Class 3 Code Signing 2010 CA", + "signerHash": "6c3245d4a9bc0244d99dff27af259cbbae2e2d16", + "isValidCertificate": false, + "determinationType": "Pua", + "determinationValue": "PUA:Win32/FusionCore" } ``` diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-file-related-alerts.md b/windows/security/threat-protection/microsoft-defender-atp/get-file-related-alerts.md index 3f6ac44dd3..146a80fcf6 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/get-file-related-alerts.md +++ b/windows/security/threat-protection/microsoft-defender-atp/get-file-related-alerts.md @@ -18,12 +18,19 @@ ms.topic: article # Get file related alerts API -**Applies to:** +**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) -- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) +- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + +## API description Retrieves a collection of alerts related to a given file hash. + +## Limitations +1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour. + + ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md) @@ -69,38 +76,3 @@ Here is an example of the request. ``` GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/alerts ``` - -**Response** - -Here is an example of the response. - - -``` -HTTP/1.1 200 OK -Content-type: application/json -{ - "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts", - "value": [ - { - "id": "121688558380765161_2136280442", - "incidentId": 7696, - "assignedTo": "secop@contoso.com", - "severity": "High", - "status": "New", - "classification": "TruePositive", - "determination": "Malware", - "investigationState": "Running", - "category": "MalwareDownload", - "detectionSource": "WindowsDefenderAv", - "threatFamilyName": "Mikatz", - "title": "Windows Defender AV detected 'Mikatz', high-severity malware", - "description": "Some description", - "alertCreationTime": "2018-11-26T16:19:21.8409809Z", - "firstEventTime": "2018-11-26T16:17:50.0948658Z", - "lastEventTime": "2018-11-26T16:18:01.809871Z", - "resolvedTime": null, - "machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337" - } - ] -} -``` diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-file-related-machines.md b/windows/security/threat-protection/microsoft-defender-atp/get-file-related-machines.md index de5d6837e9..a1e522151c 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/get-file-related-machines.md +++ b/windows/security/threat-protection/microsoft-defender-atp/get-file-related-machines.md @@ -18,11 +18,18 @@ ms.topic: article # Get file related machines API -**Applies to:** +**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) -- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) +- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + + +## API description +Retrieves a collection of [Machines](machine.md) related to a given file hash. + + +## Limitations +1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour. -- Retrieves a collection of machines related to a given file hash. ## Permissions One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md) @@ -69,52 +76,3 @@ Here is an example of the request. ``` GET https://api.securitycenter.windows.com/api/files/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/machines ``` - -**Response** - -Here is an example of the response. - - -``` -HTTP/1.1 200 OK -Content-type: application/json -{ - "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines", - "value": [ - { - "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07", - "computerDnsName": "mymachine1.contoso.com", - "firstSeen": "2018-08-02T14:55:03.7791856Z", - "lastSeen": "2018-08-02T14:55:03.7791856Z", - "osPlatform": "Windows10", - "osVersion": "10.0.0.0", - "lastIpAddress": "172.17.230.209", - "lastExternalIpAddress": "167.220.196.71", - "agentVersion": "10.5830.18209.1001", - "osBuild": 18209, - "healthStatus": "Active", - "rbacGroupId": 140, - "riskScore": "Low", - "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9", - "machineTags": [ "test tag 1", "test tag 2" ] - }, - { - "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7", - "computerDnsName": "mymachine2.contoso.com", - "firstSeen": "2018-07-09T13:22:45.1250071Z", - "lastSeen": "2018-07-09T13:22:45.1250071Z", - "osPlatform": "Windows10", - "osVersion": "10.0.0.0", - "lastIpAddress": "192.168.12.225", - "lastExternalIpAddress": "79.183.65.82", - "agentVersion": "10.5820.17724.1000", - "osBuild": 17724, - "healthStatus": "Inactive", - "rbacGroupId": 140, - "riskScore": "Low", - "aadDeviceId": null, - "machineTags": [ "test tag 1" ] - } - ] -} -``` diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-file-statistics.md b/windows/security/threat-protection/microsoft-defender-atp/get-file-statistics.md index 5f2cfec15b..df8bce6953 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/get-file-statistics.md +++ b/windows/security/threat-protection/microsoft-defender-atp/get-file-statistics.md @@ -18,12 +18,19 @@ ms.topic: article # Get file statistics API -**Applies to:** +**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) -- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) +- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + +## API description Retrieves the prevalence for the given file. + +## 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) @@ -64,7 +71,7 @@ Here is an example of the request. [!include[Improve request performance](../../includes/improve-request-performance.md)] ``` -GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/stats +GET https://api.securitycenter.windows.com/api/files/0991a395da64e1c5fbe8732ed11e6be064081d9f/stats ``` **Response** @@ -77,13 +84,15 @@ HTTP/1.1 200 OK Content-type: application/json { "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgFileStats", - "sha1": "6532ec91d513acc05f43ee0aa3002599729fd3e1", - "orgPrevalence": "3", - "orgFirstSeen": "2018-07-15T06:13:59Z", - "orgLastSeen": "2018-08-03T16:45:21Z", + "sha1": "0991a395da64e1c5fbe8732ed11e6be064081d9f", + "orgPrevalence": "14850", + "orgFirstSeen": "2019-12-07T13:44:16Z", + "orgLastSeen": "2020-01-06T13:39:36Z", + "globalPrevalence": "705012", + "globalFirstObserved": "2015-03-19T12:20:07.3432441Z", + "globalLastObserved": "2020-01-06T13:39:36Z", "topFileNames": [ - "chrome_1.exe", - "chrome_2.exe" + "MREC.exe" ] }