แก้ไข

แชร์ผ่าน


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

Each method has 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. So, it's 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. It doesn't contain historic data. 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. So, it's 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 effect 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, 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 the user gets affected if the configuration will be applied.
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 Supported operating systems, platforms and capabilities for details.
osVersion String Specific version of the operating system running on the device.
rbacGroupName String The role-based access control (RBAC) group. If the device isn't 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 the 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
Export software inventory assessment (JSON response) 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.
Export software inventory assessment (via files) 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. So, it's 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 data from Azure Storage as follows:
  1. Call the API to get a list of download URLs with your organization data
  2. Download 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; specific operating systems with variations within the same family, such as Windows 10 and Windows 11. See Supported operating systems, platforms and capabilities for details.
RbacGroupName String The role-based access control (RBAC) group. If this device isn't 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. So, it's 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. The full software vulnerabilities assessment (JSON response) is used to obtain an entire snapshot of the software vulnerabilities assessment of your organization by device. However, 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 isn't 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; specific operating systems with variations within the same family, such as Windows 10 and Windows 11. See Supported operating systems, platforms and capabilities for details.
RbacGroupName String The role-based access control (RBAC) group. If this device isn't 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.
SecurityUpdateAvailable Boolean Indicates whether a security update is available for the software.
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 that is assigned to the security vulnerability based on the CVSS score.

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 the delta event was found.
ExploitabilityLevel String The exploitability level of the vulnerability (NoExploit, ExploitIsPublic, ExploitIsVerified, ExploitIsInKit)
FirstSeenTimestamp String First time the CVE of the 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; specific operating systems with variations within the same family, such as Windows 10 and Windows 11. See Supported operating systems, platforms and capabilities for details.
RbacGroupName String The role-based access control (RBAC) group. If this device isn't 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.

4. Export non product code software inventory assessment

Returns all of the installed software that does not have a Common Platform Enumeration(CPE) and their details on each device.

4.1 Methods

Method Data type Description
Export non product code software inventory assessment (JSON response) Non product code software inventory by device collection. See: 4.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.
Export non product code software inventory assessment (via files) Non product code software inventory by device files. See: 4.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. So, it's 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 data from Azure Storage as follows:
  1. Call the API to get a list of download URLs with your organization data
  2. Download the files using the download URLs and process the data as you like.

4.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.
OSPlatform string Platform of the operating system running on the device. These are specific operating systems with variations within the same family, such as Windows 10 and Windows 11. See Supported operating systems, platforms and capabilities for details.
RbacGroupName string The role-based access control (RBAC) group. If this device isn't 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.
SoftwareLastSeenTimestamp string The last 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.

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

See also

Other related

Tip

Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.