Export assessment methods and properties per device

Applies to:

Want to experience Microsoft Defender for Endpoint? Sign up for a free trial.

API description

Provides methods and property details about the APIs that pull threat and vulnerability management data on a per-device basis. There are different API calls to get different types of data. In general, each API call contains the requisite data for devices in your organization.

Note

Unless indicated otherwise, all export assessment methods listed are full export and by device (also referred to as per device).

You can use the export assessment APIs to retrieve (export) different types of information:

The APIs that correspond to the export information types are described in sections 1, 2, and 3.

For each method, there are different API calls to get different types of data. Because the amount of data can be large, there are two ways it can be retrieved:

  • 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.

  • via files This API solution enables pulling larger amounts of data faster and more reliably. Therefore, it is recommended for large organizations, with more than 100-K devices. This API pulls all data in your organization as download files. The response contains URLs to download all the data from Azure Storage. This API enables you to download all your data from Azure Storage as follows:

    • Call the API to get a list of download URLs with all your organization data.
    • Download all the files using the download URLs and process the data as you like.

Data that is collected (using either JSON response or via files) is the current snapshot of the current state, and does not contain historic data. In order to collect historic data, customers must save the data in their own data storages.

1. Export secure configurations assessment

Returns all of the configurations and their status, on a per-device basis.

1.1 Methods

Method Data type Description
Secure configuration by device collection. See: 1.2 Properties (JSON response) Returns a table with an entry for every unique combination of DeviceId, ConfigurationId. 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.
Secure configuration by device collection. See: 1.3 Properties (via files) Returns a table with an entry for every unique combination of DeviceId, ConfigurationId. This API solution enables pulling larger amounts of data faster and more reliably. Therefore, it is recommended for large organizations, with more than 100-K devices. This API pulls all data in your organization as download files. The response contains URLs to download all the data from Azure Storage. This API enables you to download all your data from Azure Storage as follows:
  1. Call the API to get a list of download URLs with all your organization data.
  2. Download all the files using the download URLs and process the data as you like.

1.2 Properties (JSON response)

Property (ID) Data type Description
configurationCategory string Category or grouping to which the configuration belongs: Application, OS, Network, Accounts, Security controls.
configurationId string Unique identifier for a specific configuration.
configurationImpact string Rated impact of the configuration to the overall configuration score (1-10).
configurationName string Display name of the configuration.
configurationSubcategory string Subcategory or subgrouping to which the configuration belongs. In many cases, this describes specific capabilities or features.
deviceId string Unique identifier for the device in the service.
deviceName string Fully qualified domain name (FQDN) of the device.
isApplicable bool Indicates whether the configuration or policy is applicable.
isCompliant bool Indicates whether the configuration or policy is properly configured.
isExpectedUserImpact bool Indicates whether there will be user impact if the configuration will be applied.
osPlatform string Platform of the operating system running on the device. This indicates specific operating systems, including variations within the same family, such as Windows 10 and Windows 7. See TVM supported operating systems and platforms for details.
osVersion string Specific version of the operating system running on the device.
rbacGroupName string The role-based access control (RBAC) group. If this device is not assigned to any RBAC group, the value will be "Unassigned." If the organization doesn't contain any RBAC groups, the value will be "None."
rbacGroupId string The role-based access control (RBAC) group ID.
recommendationReference string A reference to the recommendation ID related to this software.
timestamp string Last time the configuration was seen on the device.

1.3 Properties (via files)

Property (ID) Data type Description
Export files array[string] A list of download URLs for files holding the current snapshot of the organization.
GeneratedTime string The time that the export was generated.

2. Export software inventory assessment

Returns all of the installed software and their details on each device.

2.1 Methods

Method Data type Description
Software inventory by device collection. See: 2.2 Properties (JSON response) Returns a table with an entry for every unique combination of DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion. 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.
Software inventory by device files. See: 2.3 Properties (via files) Returns a table with an entry for every unique combination of DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion. This API solution enables pulling larger amounts of data faster and more reliably. Therefore, it is recommended for large organizations, with more than 100-K devices. This API pulls all data in your organization as download files. The response contains URLs to download all the data from Azure Storage. This API enables you to download all your data from Azure Storage as follows:
  1. Call the API to get a list of download URLs with all your organization data
  2. Download all the files using the download URLs and process the data as you like.

2.2 Properties (JSON response)

Property (ID) Data type Description
DeviceId string Unique identifier for the device in the service.
DeviceName string Fully qualified domain name (FQDN) of the device.
DiskPaths Array[string] Disk evidence that the product is installed on the device.
EndOfSupportDate string The date in which support for this software has or will end.
EndOfSupportStatus string End of support status. Can contain these possible values: None, EOS Version, Upcoming EOS Version, EOS Software, Upcoming EOS Software.
NumberOfWeaknesses int Number of weaknesses on this software on this device.
OSPlatform string Platform of the operating system running on the device. This indicates specific operating systems, including variations within the same family, such as Windows 10 and Windows 7. See tvm supported operating systems and platforms for details.
RbacGroupName string The role-based access control (RBAC) group. If this device is not assigned to any RBAC group, the value will be "Unassigned." If the organization doesn't contain any RBAC groups, the value will be "None."
rbacGroupId string The role-based access control (RBAC) group ID.
RegistryPaths Array[string] Registry evidence that the product is installed in the device.
SoftwareFirstSeenTimestamp string The first time this software was seen on the device.
SoftwareName string Name of the software product.
SoftwareVendor string Name of the software vendor.
SoftwareVersion string Version number of the software product.

2.3 Properties (via files)

Property (ID) Data type Description
Export files array[string] A list of download URLs for files holding the current snapshot of the organization.
GeneratedTime string The time that the export was generated.

3. Export software vulnerabilities assessment

Returns all the known vulnerabilities on a device and their details, for all devices.

3.1 Methods

Method Data type Description
Investigation collection See: 3.2 Properties (JSON response) Returns a table with an entry for every unique combination of DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion, CveId. 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.
Investigation entity See: 3.3 Properties (via files) Returns a table with an entry for every unique combination of DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion, CveId. This API solution enables pulling larger amounts of data faster and more reliably. Therefore, it is recommended for large organizations, with more than 100-K devices. This API pulls all data in your organization as download files. The response contains URLs to download all the data from Azure Storage. This API enables you to download all your data from Azure Storage as follows:
  1. Call the API to get a list of download URLs with all your organization data.
  2. Download all the files using the download URLs and process the data as you like.
Investigation collection See: 3.4 Properties Delta export (JSON response) Returns a table with an entry for every unique combination of: DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion, CveId, and EventTimestamp.

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 API call is used to fetch only the changes that have 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'll only get specific information on new, fixed, and updated vulnerabilities. Delta export 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?"

Because the Delta export API call for software vulnerabilities returns data for only a targeted date range, it is not considered a full export.

3.2 Properties (JSON response)

Property (ID) Data type Description
CveId string Unique identifier assigned to the security vulnerability under the Common Vulnerabilities and Exposures (CVE) system.
CvssScore string The CVSS score of the CVE.
DeviceId string Unique identifier for the device in the service.
DeviceName string Fully qualified domain name (FQDN) of the device.
DiskPaths Array[string] Disk evidence that the product is installed on the device.
ExploitabilityLevel string The exploitability level of this vulnerability (NoExploit, ExploitIsPublic, ExploitIsVerified, ExploitIsInKit)
FirstSeenTimestamp string First time the CVE of this product was seen on the device.
Id string Unique identifier for the record.
LastSeenTimestamp string Last time the CVE was seen on the device.
OSPlatform string Platform of the operating system running on the device. This indicates specific operating systems, including variations within the same family, such as Windows 10 and Windows 7. See tvm supported operating systems and platforms for details.
RbacGroupName string The role-based access control (RBAC) group. If this device is not assigned to any RBAC group, the value will be "Unassigned." If the organization doesn't contain any RBAC groups, the value will be "None."
rbacGroupId string The role-based access control (RBAC) group ID.
RecommendationReference string A reference to the recommendation ID related to this software.
RecommendedSecurityUpdate string Name or description of the security update provided by the software vendor to address the vulnerability.
RecommendedSecurityUpdateId string Identifier of the applicable security updates or identifier for the corresponding guidance or knowledge base (KB) articles.
Registry Paths Array[string] Registry evidence that the product is installed in the device.
SoftwareName string Name of the software product.
SoftwareVendor string Name of the software vendor.
SoftwareVersion string Version number of the software product.
VulnerabilitySeverityLevel string Severity level assigned to the security vulnerability based on the CVSS score and dynamic factors influenced by the threat landscape.

3.3 Properties (via files)

Property (ID) Data type Description
Export files array[string] A list of download URLs for files holding the current snapshot of the organization.
GeneratedTime string The time that the export was generated.

3.4 Properties (delta export JSON response)

Property (ID) Data type Description
CveId  string Unique identifier assigned to the security vulnerability under the Common Vulnerabilities and Exposures (CVE) system.
CvssScore string The CVSS score of the CVE.
DeviceId string Unique identifier for the device in the service.
DeviceName string Fully qualified domain name (FQDN) of the device.
DiskPaths Array[string] Disk evidence that the product is installed on the device.
EventTimestamp String The time this delta event was found.
ExploitabilityLevel string The exploitability level of this vulnerability (NoExploit, ExploitIsPublic, ExploitIsVerified, ExploitIsInKit)
FirstSeenTimestamp string First time the CVE of this product was seen on the device.
Id string Unique identifier for the record.  
LastSeenTimestamp string Last time the CVE was seen on the device.
OSPlatform string Platform of the operating system running on the device. This indicates specific operating systems, including variations within the same family, such as Windows 10 and Windows 7. See tvm supported operating systems and platforms for details.
RbacGroupName string The role-based access control (RBAC) group. If this device is not assigned to any RBAC group, the value will be "Unassigned." If the organization doesn't contain any RBAC groups, the value will be "None."
RecommendationReference string A reference to the recommendation ID related to this software.
RecommendedSecurityUpdate  string Name or description of the security update provided by the software vendor to address the vulnerability.
RecommendedSecurityUpdateId  string Identifier of the applicable security updates or identifier for the corresponding guidance or knowledge base (KB) articles
RegistryPaths  Array[string] Registry evidence that the product is installed in the device.
SoftwareName string Name of the software product.
SoftwareVendor string Name of the software vendor.
SoftwareVersion string Version number of the software product.
Status String New (for a new vulnerability introduced on a device). Fixed (for a vulnerability that doesn't exist anymore on the device, which means it was remediated). Updated (for a vulnerability on a device that has changed. The possible changes are: CVSS score, exploitability level, severity level, DiskPaths, RegistryPaths, RecommendedSecurityUpdate).
VulnerabilitySeverityLevel string Severity level assigned to the security vulnerability based on the CVSS score and dynamic factors influenced by the threat landscape.

See also

Other related