From 4555f820e4f70b9ee3b4449e5f0f8be938582f09 Mon Sep 17 00:00:00 2001 From: Dulce Montemayor Date: Tue, 7 Jan 2020 15:30:35 -0800 Subject: [PATCH] Added new topics for TVM API --- .../get-device-secure-score.md | 85 +++++++++++++++++ .../get-exposure-score.md | 91 ++++++++++++++++++ .../get-machine-group-exposure-score.md | 94 +++++++++++++++++++ .../microsoft-defender-atp/recommendation.md | 57 +++++++++++ .../microsoft-defender-atp/score.md | 75 +++++++++++++++ .../microsoft-defender-atp/software.md | 45 +++++++++ .../microsoft-defender-atp/vulnerability.md | 48 ++++++++++ 7 files changed, 495 insertions(+) create mode 100644 windows/security/threat-protection/microsoft-defender-atp/get-device-secure-score.md create mode 100644 windows/security/threat-protection/microsoft-defender-atp/get-exposure-score.md create mode 100644 windows/security/threat-protection/microsoft-defender-atp/get-machine-group-exposure-score.md create mode 100644 windows/security/threat-protection/microsoft-defender-atp/recommendation.md create mode 100644 windows/security/threat-protection/microsoft-defender-atp/score.md create mode 100644 windows/security/threat-protection/microsoft-defender-atp/software.md create mode 100644 windows/security/threat-protection/microsoft-defender-atp/vulnerability.md diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-device-secure-score.md b/windows/security/threat-protection/microsoft-defender-atp/get-device-secure-score.md new file mode 100644 index 0000000000..7a81fe0182 --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/get-device-secure-score.md @@ -0,0 +1,85 @@ +--- +title: Get Device Secure score +description: Retrieves the organizational device secure score. +keywords: apis, graph api, supported apis, get, alerts, recent +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: dolmont +author: DulceMontemayor +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Get Device Secure score + +**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) + +- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + +Retrieves the organizational device secure score. + +## 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 | Score.Read.Alll | 'Read Threat and Vulnerability Management score' +Delegated (work or school account) | Score.Read | 'Read Threat and Vulnerability Management score' + +## HTTP request +``` +GET /api/configurationScore +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200 OK, with the with device secure score data in the response body. + + +## Example + +**Request** + +Here is an example of the request. + +``` +GET https://api.securitycenter.windows.com/api/configurationScore +``` + +[!include[Improve request performance](improve-request-performance.md)] + + +**Response** + +Here is an example of the response. + +>[!NOTE] +>The response list shown here may be truncated for brevity. + + +```json +{ + "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#ConfigurationScore/$entity", + "time": "2019-12-03T09:15:58.1665846Z", + "score": 340, + "rbacGroupId": null +} +``` + +## Related topics +- [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md) \ No newline at end of file diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-exposure-score.md b/windows/security/threat-protection/microsoft-defender-atp/get-exposure-score.md new file mode 100644 index 0000000000..2ce5adf1e0 --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/get-exposure-score.md @@ -0,0 +1,91 @@ +--- +title: Get exposure score +description: Retrieves the organizational exposure score. +keywords: apis, graph api, supported apis, get, exposure score, organizational exposure score +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: dolmont +author: DulceMontemayor +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Get exposure score + +**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559) + +- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + +Retrieves the organizational exposure score. + +## 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 | Score.Read.All | 'Read Threat and Vulnerability Management score' +Delegated (work or school account) | Score.Read | 'Read Threat and Vulnerability Management score' + + +## HTTP request +``` +GET /api/exposureScore +``` + +## Optional query parameters +Method supports $top, $select, $filter, $expand and $skip query parameters. +
$expand is available on Files, IPs and Domains. e.g. $expand=files,domains + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + + +## Request body +Empty + +## Response +If successful, this method returns 200 OK, with the exposure data in the response body. + + +## Example + +**Request** + +Here is an example of the request. + +``` +GET https://api.securitycenter.windows.com/api/exposureScore +``` + +[!include[Improve request performance](improve-request-performance.md)] + + +**Response** + +Here is an example of the response. + +>[!NOTE] +>The response list shown here may be truncated for brevity. + + +```json +{ + "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#ExposureScore/$entity", + "time": "2019-12-03T07:23:53.280499Z", + "score": 33.491554051195706, + "rbacGroupId": null +} + +``` + +## Related topics +- [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md) diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machine-group-exposure-score.md b/windows/security/threat-protection/microsoft-defender-atp/get-machine-group-exposure-score.md new file mode 100644 index 0000000000..42995a2265 --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/get-machine-group-exposure-score.md @@ -0,0 +1,94 @@ +--- +title: List exposure score by machine group +description: Retrieves a list of exposure scores by machine group. +keywords: apis, graph api, supported apis, get, exposure score, machine group, machine group exposure score +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: dolmont +author: DulceMontemayor +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# List exposure score by machine group + +**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 domain address. + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Score.Read.All | 'Read Threat and Vulnerability Management score' +Delegated (work or school account) | Score.Read | 'Read Threat and Vulnerability Management score' + +## HTTP request +``` +GET /api/exposureScore/ByMachineGroups +``` + +## Request headers + +| Name | Type | Description +|:--------------|:-------|:--------------| +| Authorization | String | Bearer {token}.**Required**. + +## Request body +Empty + +## Response +If successful, this method returns 200 OK, with a list of exposure score per machine group data in the response body. + + +## Example + +**Request** + +Here is an example of the request. + +``` +GET https://api.securitycenter.windows.com/api/exposureScore/ByMachineGroups +``` + +**Response** + +Here is an example of the response. + +```json + +{ + "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#ExposureScore", + "value": [ + { + "time": "2019-12-03T09:51:28.214338Z", + "score": 41.38041766305988, + "rbacGroupId": 10 + }, + { + "time": "2019-12-03T09:51:28.2143399Z", + "score": 37.403726933165366, + "rbacGroupId": 11 + }, + { + "time": "2019-12-03T09:51:28.2143407Z", + "score": 26.390921344426033, + "rbacGroupId": 9 + }, + { + "time": "2019-12-03T09:51:28.2143414Z", + "score": 23.58823563070858, + "rbacGroupId": 5 + } + ] +} +``` \ No newline at end of file diff --git a/windows/security/threat-protection/microsoft-defender-atp/recommendation.md b/windows/security/threat-protection/microsoft-defender-atp/recommendation.md new file mode 100644 index 0000000000..c9dfd44b5f --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/recommendation.md @@ -0,0 +1,57 @@ +--- +title: Recommendation methods and properties +description: Retrieves top recent alerts. +keywords: apis, graph api, supported apis, get, alerts, recent +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: dolmont +author: DulceMontemayor +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Recommendation 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) + +## Methods +Method |Return Type |Description +:---|:---|:--- +[List all recommendations](get-all-recommendations.md) | Recommendation collection | +[Get recommendation by Id](get-recommendation-by-id.md) | Recommendation | +[Get recommendation software](get-recommendation-software.md)| [Software](software.md) | +[Get recommendation machines](get-recommendation-machines.md)|MachineRef collection | +[Get recommendation vulnerabilities](get-recommendation-vulnerabilities.md) | [Vulnerability](vulnerability.md) collection | + + +## Properties +Property | Type | Description +:---|:---|:--- +id | String | +productName | String | +recommendationName | String | +Weaknesses | Long | +Vendor | String | +recommendedVersion | String | +recommendationCategory | String | +subCategory | String | +severityScore | Double | +publicExploit | Boolean | +activeAlert | Boolean | +associatedThreats | String collection | +remediationType | String | +Status | String | Enum +configScoreImpact | Double | +exposureImpacte | Double| +totalMachineCount | Long | +exposedMachinesCount | Long | +nonProductivityImpactedAssets | Long | +relatedComponent | String | diff --git a/windows/security/threat-protection/microsoft-defender-atp/score.md b/windows/security/threat-protection/microsoft-defender-atp/score.md new file mode 100644 index 0000000000..06f002a203 --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/score.md @@ -0,0 +1,75 @@ +--- +title: Score methods and properties +description: Retrieves your organization's exposure score, device secure score, and exposure score by machine group +keywords: apis, graph api, supported apis, score, exposure score, device secure score, exposure score by machine group +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: dolmont +author: DulceMontemayor +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Score 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) + +## Methods +Method |Return Type |Description +:---|:---|:--- +[Get exposure score](get-exposure-score.md) | [Score](score.md) | Get the organizational exposure score. +[Get device secure score](get-device-secure-score.md) | [Score](score.md) | Get the organizational device secure score. +[List exposure score by machine group](get-machine-group-exposure-score.md)| [Score](score.md) | List scores by machine group. + + +## Properties +Property | Type | Description +:---|:---|:--- +Score | Double | The current score. +Time | DateTime | The date and time in which the call for this API was made. +RbacGroupId | Nullable Int | RBAC Group ID. + + +### Response example for getting machine groups score: + +``` +GET https://api.securitycenter.windows.com/api/exposureScore/byMachineGroups +``` + +```json +{ + "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#ExposureScore", + "value": [ + { + "time": "2019-12-03T07:26:49.9376328Z", + "score": 41.38041766305988, + "rbacGroupId": 10 + }, + { + "time": "2019-12-03T07:26:49.9376375Z", + "score": 23.58823563070858, + "rbacGroupId": 5 + }, + { + "time": "2019-12-03T07:26:49.9376382Z", + "score": 37.403726933165366, + "rbacGroupId": 11 + }, + { + "time": "2019-12-03T07:26:49.9376388Z", + "score": 26.323200116475423, + "rbacGroupId": 9 + } + ] +} + + +``` diff --git a/windows/security/threat-protection/microsoft-defender-atp/software.md b/windows/security/threat-protection/microsoft-defender-atp/software.md new file mode 100644 index 0000000000..36aba64d20 --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/software.md @@ -0,0 +1,45 @@ +--- +title: Software methods and properties +description: Retrieves top recent alerts. +keywords: apis, graph api, supported apis, get, alerts, recent +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: dolmont +author: DulceMontemayor +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Software 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) + +## Methods +Method |Return Type |Description +:---|:---|:--- +[List software](get-software.md) | Software collection | List the organizational software inventory. +[Get software by Id](get-software-by-id.md) | Software | Get a specific software by its software ID. +[List software version distribution](get-software-ver-distribution.md)| Distribution collection | List software version distribution by software ID. +[List machines by software](get-machines-by-software.md)| MachineRef collection | Retrieve a list of machines that are associated with the software ID. +[List vulnerabilities by software](get-vuln-by-software.md) | [Vulnerability](vulnerability.md) collection | Retrieve a list of vulnerabilities associated with the software ID. + +## Properties +Property | Type | Description +:---|:---|:--- +id | String | +Name | String | +Vendor | String | +Weaknesses | Long | +publicExploit | Boolean | +activeAlert | Boolean | +exposedMachines | Long | +impactScore | Double | + diff --git a/windows/security/threat-protection/microsoft-defender-atp/vulnerability.md b/windows/security/threat-protection/microsoft-defender-atp/vulnerability.md new file mode 100644 index 0000000000..3be61d9006 --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/vulnerability.md @@ -0,0 +1,48 @@ +--- +title: Vulnerability methods and properties +description: Retrieves vulnerability information +keywords: apis, graph api, supported apis, get, vulnerability +search.product: eADQiWindows 10XVcnh +ms.prod: w10 +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: dolmont +author: DulceMontemayor +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +--- + +# Vulnerability 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) + +## Methods +Method |Return Type |Description +:---|:---|:--- +[Get all vulnerabilities](get-all-vulnerabilities.md) | Vulnerability collection | +[Get vulnerability by Id](get-vulnerability-by-id.md) | Vulnerability | +[List machines by vulnerability](get-machines-by-vulnerability.md)| MachineRef collection | Retrieve a list of machines that are associated with the vulnerability ID + + +## Properties +Property | Type | Description +:---|:---|:--- +id | String | +Name | String | +Description | String | +Severity | String | +cvssV3 | Double | +exposedMachines | Long | +publishedOn | DateTime | +updatedOn | DateTime | +publicExploit | Boolean | +exploitVerified | Boolean | +exploitInKit | Boolean | +exploitTypes | String collection | +exploitUris | String collection |