You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: defender-endpoint/api/get-assessment-software-vulnerabilities.md
+26-27Lines changed: 26 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,7 +15,7 @@ ms.topic: reference
15
15
ms.subservice: reference
16
16
ms.custom: api
17
17
search.appverid: met150
18
-
ms.date: 02/11/2025
18
+
ms.date: 07/09/2025
19
19
---
20
20
21
21
# Export software vulnerabilities assessment per device
@@ -31,9 +31,7 @@ ms.date: 02/11/2025
31
31
32
32
> Want to experience Microsoft Defender for Endpoint? [Sign up for a free trial.](https://go.microsoft.com/fwlink/p/?linkid=2225630)
33
33
34
-
Returns all known software vulnerabilities and their details for all devices, on a per-device basis.
35
-
36
-
Different API calls get different types of data. Because the amount of data can be large, there are three ways it can be retrieved:
34
+
The ability to export software vulnerabilities per device returns all known software vulnerabilities and their details for all devices, on a per-device basis. Different API calls get different types of data. Because the amount of data can be large, there are three ways it can be retrieved:
37
35
38
36
1.[Export software vulnerabilities assessment: **JSON response**](#1-export-software-vulnerabilities-assessment-json-response) The API pulls all data in your organization as Json responses. This method is best for _small organizations with less than 100-K devices_. The response is paginated, so you can use the \@odata.nextLink field from the response to fetch the next results.
39
37
@@ -116,7 +114,6 @@ GET /api/machines/SoftwareVulnerabilitiesByMachine
116
114
|SoftwareVendor|String|Name of the software vendor.|Google|
117
115
|SoftwareVersion|String|Version number of the software product.|81.0.4044.138|
118
116
|VulnerabilitySeverityLevel|String|Severity level assigned to the security vulnerability based on the CVSS score.|Medium|
119
-
|||||
120
117
121
118
### 1.6 Examples
122
119
@@ -299,19 +296,13 @@ GET /api/machines/SoftwareVulnerabilitiesExport
299
296
> - The files are GZIP compressed & in multiline JSON format.
300
297
> - The download URLs are valid for 1 hour unless the `sasValidHours` parameter is used.
301
298
> - For maximum download speed of your data, you can make sure you're downloading from the same Azure region that your data resides.
302
-
>
303
299
> - Each record is 1KB of data. You should take this into account when choosing the correct pageSize parameter for you.
304
300
> - Some extra columns might be returned in the response. These columns are temporary and might be removed so use only the documented columns.
305
301
306
-
<br>
307
-
308
-
****
309
-
310
302
Property (ID)|Data type|Description|Example of a returned value
311
303
:---|:---|:---|:---
312
304
Export files|array[string]|A list of download URLs for files holding the current snapshot of the organization.|["https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"]
313
305
GeneratedTime|String|The time that the export was generated.|2021-05-20T08:00:00Z
314
-
|
315
306
316
307
### 2.6 Examples
317
308
@@ -342,7 +333,21 @@ GET https://api-us.securitycenter.contoso.com/api/machines/SoftwareVulnerabiliti
342
333
Returns a table with an entry for every unique combination of DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion, CveId. The API pulls data in your organization as Json responses. The response is paginated, so you can use the @odata.nextLink field from the response to fetch the next results. Unlike the full software vulnerabilities assessment (JSON response), which is used to obtain an entire snapshot of the software vulnerabilities assessment of your organization by device, the delta export JSON response API call is used to fetch only the changes that happened between a selected date and the current date (the "delta" API call). Instead of getting a full export with a large amount of data every time, you only get specific information on new, fixed, and updated vulnerabilities. Delta export JSON response API call can also be used to calculate different KPIs such as "how many vulnerabilities were fixed?" or "how many new vulnerabilities were added to my organization?"
343
334
344
335
> [!NOTE]
345
-
> It's highly recommended you use the full export software vulnerabilities assessment by device API call at least once a week and this extra export software vulnerabilities changes by device (delta) API call all the other days of the week. Unlike the other Assessments JSON response APIs, the "delta export" isn't a full export. The delta export includes only the changes that happened between a selected date and the current date (the "delta" API call).
336
+
> We refresh the __Full _Software Vulnerabilities Assessment(Flat/Full VA) by Device___ export every __six hours__ and store each snapshot in blob storage; the API always serves the latest snapshot, to emphasize calling the Get Endpoint won't to trigger a generation, call get endpoint will just read latest Flat OR Delta After sinceTime.
337
+
> A successful completion of Full VA export will trigger __delta export__ that captures the changes from latest Flat VA processed by Delta to new Flat VA.
338
+
> > __RBAC-scoped duplicates__
339
+
> > Because exports are scoped by __RBACGroup__, a device that moves from one RBAC group to another will appear __twice__ in a Delta export when you query with the global view (`RBACGroup=*`): once under its previous group with status "Fixed" and once under its current group with status "New". Use the `rbacGroupId` and device identifiers together (or de-duplicate on your side) if you need a single authoritative record per device.
340
+
>
341
+
> Recommended pull pattern
342
+
>
343
+
1.__Baseline__ – Download the full VA(Flat VA) export on your preferred cadence (weekly is often sufficient).
344
+
345
+
1.__Stay current__ – delta export between full snapshots(Delta can be queried up to 14 days into the past).
346
+
347
+
1.__Handle RBAC moves__ – When processing a Delta, de-duplicate entries where the same `Id(deviceId_software_` version _ cve`)`appears under multiple `rbacGroupId` values.
348
+
349
+
1. When "Status" = Fix" the calcualtion of "EventTimestamp"- "FirstSeenTimestamp" should give you an estimation on when the CVE was fixed up to a granularity of 6 hours(because of Delta worker run interval).
350
+
346
351
347
352
#### 3.1.1 Limitations
348
353
@@ -380,24 +385,21 @@ Each returned record contains all the data from the full export software vulnera
380
385
> - Some other columns might be returned in the response. These columns are temporary and might be removed so use only the documented columns.
381
386
> - The properties defined in the following table are listed alphabetically, by property ID. When running this API, the resulting output isn't necessarily returned in the same order listed in this table.
382
387
383
-
<br>
384
-
385
-
****
386
-
387
388
|Property (ID)|Data type|Description|Example of returned value|
388
389
|:---|:---|:---|:---|
389
390
|CveId |String|Unique identifier assigned to the security vulnerability under the Common Vulnerabilities and Exposures (CVE) system.|CVE-2020-15992|
390
391
|CvssScore|Double|The CVSS score of the CVE.|6.2|
391
392
|DeviceId|String|Unique identifier for the device in the service.|9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1|
392
393
|DeviceName|String|Fully qualified domain name (FQDN) of the device.|johnlaptop.europe.contoso.com|
393
394
|DiskPaths|Array[string]|Disk evidence that the product is installed on the device.|["C:\Program Files (x86)\Microsoft\Silverlight\Application\silverlight.exe"]|
394
-
|EventTimestamp|String|The time this delta event was found.|2021-01-11T11:06:08.291Z|
395
+
|EventTimestamp|String|The time this delta event was found.|2020-11-03 10:13:34.8476880|
395
396
|ExploitabilityLevel|String|The exploitability level of this vulnerability (NoExploit, ExploitIsPublic, ExploitIsVerified, ExploitIsInKit)|ExploitIsInKit|
397
+
|IsOnboarded |Boolean|Indicates whether a device is onboarded or not.| Possible values are true or false.|
396
398
|FirstSeenTimestamp|String|First time the CVE of this product was seen on the device.|2020-11-03 10:13:34.8476880|
397
399
|ID|String|Unique identifier for the record.|123ABG55_573AG&mnp!|
398
400
|LastSeenTimestamp|String|Last time the software was reported on the device.|2020-11-03 10:13:34.8476880|
399
401
|OSPlatform|String|Platform of the operating system running on the device; specific operating systems with variations within the same family, such as Windows 10 and Windows 11. See Microsoft Defender Vulnerability Management supported operating systems and platforms for details.|Windows10 and Windows 11|
400
-
|RbacGroupName|String|The role-based access control (RBAC) group. If this device isn't assigned to any RBAC group, the value is "Unassigned." If the organization doesn't contain any RBAC groups, the value is "None."|Servers|
402
+
|RbacGroupName|String|The role-based access control (RBAC) group. If this device isn't assigned to any RBAC group, the value is "Unassigned." |Servers|
401
403
|RecommendationReference|string|A reference to the recommendation ID related to this software.|va--microsoft--silverlight|
402
404
|RecommendedSecurityUpdate |String|Name or description of the security update provided by the software vendor to address the vulnerability.|April 2020 Security Updates|
403
405
|RecommendedSecurityUpdateId |String|Identifier of the applicable security updates or identifier for the corresponding guidance or knowledge base (KB) articles|4550961|
@@ -407,7 +409,6 @@ Each returned record contains all the data from the full export software vulnera
407
409
|SoftwareVersion|String|Version number of the software product.|81.0.4044.138|
408
410
|Status|String|**New** (for a new vulnerability introduced on a device) (1) **Fixed** (if this vulnerability doesn't exist anymore on the device, which means it was remediated). (2) **Updated** (if a vulnerability on a device changed. The possible changes are: CVSS score, exploitability level, severity level, DiskPaths, RegistryPaths, RecommendedSecurityUpdate). |Fixed|
409
411
|VulnerabilitySeverityLevel|String|Severity level that is assigned to the security vulnerability and is based on the CVSS score.|Medium|
410
-
|||||
411
412
412
413
#### Clarifications
413
414
@@ -460,7 +461,7 @@ GET https://api.securitycenter.microsoft.com/api/machines/SoftwareVulnerabilityC
0 commit comments