From 76857325a2dfec49bd71d1d6fe1510ed2c8a927f Mon Sep 17 00:00:00 2001 From: Beth Levin Date: Tue, 24 Mar 2020 12:01:03 -0700 Subject: [PATCH] apis --- .../get-missing-kbs-machine.md | 86 +++++++++++++++++ .../get-missing-kbs-software.md | 93 +++++++++++++++++++ .../microsoft-defender-atp/machine.md | 5 +- .../microsoft-defender-atp/software.md | 16 ++-- .../microsoft-defender-atp/tvm-remediation.md | 8 +- 5 files changed, 195 insertions(+), 13 deletions(-) create mode 100644 windows/security/threat-protection/microsoft-defender-atp/get-missing-kbs-machine.md create mode 100644 windows/security/threat-protection/microsoft-defender-atp/get-missing-kbs-software.md diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-missing-kbs-machine.md b/windows/security/threat-protection/microsoft-defender-atp/get-missing-kbs-machine.md new file mode 100644 index 0000000000..0a94ffa148 --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/get-missing-kbs-machine.md @@ -0,0 +1,86 @@ +--- +title: Get missing KBs +description: Retrieves a list of software inventory +keywords: apis, graph api, supported apis, get, list, file, information, software inventory, threat & vulnerability management api, mdatp tvm api +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 missing KBs + +**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 missing KBs by machine Id + +## HTTP request + +``` +GET /api/machines/{machineId}/getmissingkbs +``` + +## Request header + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + +## Request body + +Empty + +## Response + +If successful, this method returns 200 OK, with the specified machine missing kb data in the body. + +## Example + +### Request + +Here is an example of the request. + +``` +GET https://api.securitycenter.windows.com/api/machines/2339ad14a01bd0299afb93dfa2550136057bff96/getmissingkbs +``` + +### Response + +Here is an example of the response. + + +```json +{ + "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Collection(microsoft.windowsDefenderATP.api.PublicProductFixDto)", + "value": [ + { + "id": "4540673", + "name": "March 2020 Security Updates", + "productsNames": [ + "windows_10", + "edge", + "internet_explorer" + ], + "url": "https://catalog.update.microsoft.com/v7/site/Search.aspx?q=KB4540673", + "machineMissedOn": 1, + "cveAddressed": 97 + }, + ... + ] +} +``` + +## Related topics + +- [Risk-based Threat & Vulnerability Management](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/next-gen-threat-and-vuln-mgt) +- [Threat & Vulnerability software inventory](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/tvm-software-inventory) diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-missing-kbs-software.md b/windows/security/threat-protection/microsoft-defender-atp/get-missing-kbs-software.md new file mode 100644 index 0000000000..a42ffaea6b --- /dev/null +++ b/windows/security/threat-protection/microsoft-defender-atp/get-missing-kbs-software.md @@ -0,0 +1,93 @@ +--- +title: Get missing KBs +description: Retrieves a list of software inventory +keywords: apis, graph api, supported apis, get, list, file, information, software inventory, threat & vulnerability management api, mdatp tvm api +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 missing KBs + +**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 missing KBs by software Id + +## Permissions + +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md) for details. + +Permission type | Permission | Permission display name +:---|:---|:--- +Application |Software.Read.All | 'Read Threat and Vulnerability Management Software information' +Delegated (work or school account) | Software.Read | 'Read Threat and Vulnerability Management Software information' + +## HTTP request + +``` +GET /api/Software/{Id}/getmissingkbs +``` + +## Request header + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. + +## Request body + +Empty + +## Response + +If successful, this method returns 200 OK, with the specified software missing kb data in the body. + +## Example + +### Request + +Here is an example of the request. + +``` +GET https://api.securitycenter.windows.com/api/Software/microsoft-_-edge/getmissingkbs +``` + +### Response + +Here is an example of the response. + + +```json +{ + "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Collection(microsoft.windowsDefenderATP.api.PublicProductFixDto)", + "value": [ + { + "id": "4540673", + "name": "March 2020 Security Updates", + "productsNames": [ + "edge" + ], + "url": "https://catalog.update.microsoft.com/v7/site/Search.aspx?q=KB4540673", + "machineMissedOn": 240, + "cveAddressed": 14 + }, + ... + ] +} +``` + +## Related topics + +- [Risk-based Threat & Vulnerability Management](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/next-gen-threat-and-vuln-mgt) +- [Threat & Vulnerability software inventory](https://docs.microsoft.com/windows/security/threat-protection/microsoft-defender-atp/tvm-software-inventory) diff --git a/windows/security/threat-protection/microsoft-defender-atp/machine.md b/windows/security/threat-protection/microsoft-defender-atp/machine.md index a38094be67..92e5b76fd8 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/machine.md +++ b/windows/security/threat-protection/microsoft-defender-atp/machine.md @@ -25,6 +25,7 @@ ms.topic: article [!include[Prerelease information](../../includes/prerelease.md)] ## Methods + Method|Return Type |Description :---|:---|:--- [List machines](get-machines.md) | [machine](machine.md) collection | List set of [machine](machine.md) entities in the org. @@ -36,9 +37,11 @@ Method|Return Type |Description [Get security recommendations](get-security-recommendations.md) | [recommendation](recommendation.md) collection | Retrieves a collection of security recommendations related to a given machine ID. [Add or Remove machine tags](add-or-remove-machine-tags.md) | [machine](machine.md) | Add or Remove tag to a specific machine. [Find machines by IP](find-machines-by-ip.md) | [machine](machine.md) collection | Find machines seen with IP. +[Get missing KBs](get-missing-kbs-machine.md) | KB collection | Get a list of missing KBs associated with the machine ID ## Properties -Property | Type | Description + +Property | Type | Description :---|:---|:--- id | String | [machine](machine.md) identity. computerDnsName | String | [machine](machine.md) fully qualified name. diff --git a/windows/security/threat-protection/microsoft-defender-atp/software.md b/windows/security/threat-protection/microsoft-defender-atp/software.md index 49e8e4c12d..414a3a54fc 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/software.md +++ b/windows/security/threat-protection/microsoft-defender-atp/software.md @@ -20,11 +20,12 @@ ms.topic: article **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) [!include[Prerelease information](../../includes/prerelease.md)] ## Methods + Method |Return Type |Description :---|:---|:--- [List software](get-software.md) | Software collection | List the organizational software inventory. @@ -32,16 +33,17 @@ Method |Return Type |Description [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. +[Get missing KBs](get-missing-kbs-software.md) | KB collection | Get a list of missing KBs associated with the software ID ## Properties -Property | Type | Description + +Property | Type | Description :---|:---|:--- id | String | Software ID -Name | String | Software name -Vendor | String | Software vendor name -Weaknesses | Long | Number of discovered vulnerabilities +Name | String | Software name +Vendor | String | Software vendor name +Weaknesses | Long | Number of discovered vulnerabilities publicExploit | Boolean | Public exploit exists for some of the vulnerabilities activeAlert | Boolean | Active alert is associated with this software exposedMachines | Long | Number of exposed machines -impactScore | Double | Exposure score impact of this software - +impactScore | Double | Exposure score impact of this software diff --git a/windows/security/threat-protection/microsoft-defender-atp/tvm-remediation.md b/windows/security/threat-protection/microsoft-defender-atp/tvm-remediation.md index 255962e9a7..6162539530 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/tvm-remediation.md +++ b/windows/security/threat-protection/microsoft-defender-atp/tvm-remediation.md @@ -30,17 +30,15 @@ After your organization's cybersecurity weaknesses are identified and mapped to Lower your organization's exposure from vulnerabilities and increase your security configuration by remediating the security recommendations. -## Remediation - ## How remediation requests work When you submit a remediation request from Threat & Vulnerability Management, it kicks-off a remediation activity. A security task is created which will be tracked in the Threat & Vulnerability Management **Remediation** page, and a remediation ticket is created in Microsoft Intune. The dashboard will show the status of your top remediation activities. Select any of the entries to go to the **Remediation** page. You can mark the remediation activity as completed after the IT admin team remediates the task. -## Accessing the Remediation page +## Accessing the remediation page -You can access the Remediation page in a few places in the portal: +You can access the remediation page in a few places in the portal: - Security recommendations flyout panel - Navigation menu @@ -70,7 +68,7 @@ If you want to check how the ticket shows up in Intune, see [Use Intune to remed 2. Select the remediation activity that you want to view. ![Screenshot of the remediation page flyout for a software which reached end-of-support](images/remediation_flyouteolsw.png) -### Top remediation activities card the dashboard +### Top remediation activities in the dashboard 1. Go to the Threat & Vulnerability Management dashboard and scroll down to the **Top remediation activities** card. The list is sorted and prioritized based on what is listed in the **Top security recommendations**. 2. Select the remediation activity that you want to view.