Edit

Export software inventory assessment per device

  • Article

Applies to:

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

This API returns all the data for installed software that has a Common Platform Enumeration(CPE), on a per-device basis.

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

  • Export software inventory 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.

  • Export software inventory assessment 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.

Note

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

1. Export software inventory assessment (JSON response)

1.1 API method description

This API response contains all the data of installed software that has a Common Platform Enumeration(CPE), per device. Returns a table with an entry for every unique combination of DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion.

1.1.1 Limitations

  • Maximum page size is 200,000.
  • Rate limitations for this API are 30 calls per minute and 1000 calls per hour.

1.2 Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs 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'

1.3 URL

GET /api/machines/SoftwareInventoryByMachine

1.4 Parameters

  • pageSize (default = 50,000): Number of results in response.
  • $top: Number of results to return (doesn't return @odata.nextLink and therefore doesn't pull all the data)

1.5 Properties

Note

  • Each record is approximately 0.5KB of data. You should take this into account when choosing the correct pageSize parameter for you.
  • The properties defined in the following table are listed alphabetically, by property ID. When running this API, the resulting output will not necessarily be returned in the same order listed in this table.
  • Some additional columns might be returned in the response. These columns are temporary and might be removed, please use only the documented columns.

Property (ID) Data type Description Example of a returned value
DeviceId string Unique identifier for the device in the service. 9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceName string Fully qualified domain name (FQDN) of the device. johnlaptop.europe.contoso.com
DiskPaths Array[string] Disk evidence that the product is installed on the device. ["C:\Program Files (x86)\Microsoft\Silverlight\Application\silverlight.exe"]
EndOfSupportDate string The date in which support for this software has or will end. 2020-12-30
EndOfSupportStatus string End of support status. Can contain these possible values: None, EOS Version, Upcoming EOS Version, EOS Software, Upcoming EOS Software. Upcoming EOS
NumberOfWeaknesses int Number of weaknesses on this software on this device 3
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 Microsoft Defender Vulnerability Management supported operating systems and platforms for details. Windows10 and Windows 11
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." Servers
RegistryPaths Array[string] Registry evidence that the product is installed in the device. ["HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\Microsoft Silverlight"]
SoftwareFirstSeenTimestamp string The first time this software was seen on the device. 2019-04-07 02:06:47
SoftwareName string Name of the software product. Silverlight
SoftwareVendor string Name of the software vendor. microsoft
SoftwareVersion string Version number of the software product. 81.0.4044.138

1.6 Examples

1.6.1 Request example

GET https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryByMachine?pageSize=5  &sinceTime=2021-05-19T18%3A35%3A49.924Z

1.6.2 Response example

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Collection(contoso.windowsDefenderATP.api.AssetSoftware)",
    "value": [
        {
            "deviceId": "00044f68765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eeb80d086e79dbfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": "windows_10" "Windows_11",
            "softwareVersion": "10.0.17763.1637",
            "numberOfWeaknesses": 58,
            "diskPaths": [],
            "registryPaths": [],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "Upcoming EOS Version",
            "endOfSupportDate": "2021-05-11T00:00:00+00:00"
        },
        {
            "deviceId": "00044f68765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eeb80d086e79dbfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": ".net_framework",
            "softwareVersion": "4.0.0.0",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "SOFTWARE\\Microsoft\\NET Framework Setup\\NDP\\v4.0\\Client\\Install"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        },
        {
            "deviceId": "00044f68765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eed80d086e79bdfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": "system_center_2012_endpoint_protection",
            "softwareVersion": "4.7.214.0",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\Microsoft Security Client"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        },
        {
            "deviceId": "00044f68765ddaf71234bde6bd733d6a9c59ad4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eeb80d086e79dbfa178aedfa25e8be9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": "configuration_manager",
            "softwareVersion": "5.0.8634.1000",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\{B7D3A842-E826-4542-B39B-1D883264B279}"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        },
        {
            "deviceId": "00044f38765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2de2f5ea3142726e63f16a.DomainPII_21eeb80d086e79bdfa178eadfa25e8be9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": "system_center_2012_endpoint_protection",
            "softwareVersion": "4.10.209.0",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\Microsoft Security Client"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        }
    ],
    "@odata.nextLink": "https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryByMachine?pagesize=5&$skiptoken=eyJFeHBvcnREZWZpbml0aW9uIjp7IlRpbWVQYXRoIjoiMjAyMS0wMS0yNS8wMjAwLyJ9LCJFeHBvcnRGaWxlSW5kZXgiOjAsIkxpbmVTdG9wcGVkQXQiOjV9"
}

Note

The information returned by this API, along with the information returned by the Export non product code software inventory assessment API, for software that doesn't have a CPE, gives you full visibility into the software installed across your organization and the devices it's installed on.

2. Export software inventory assessment (via files)

2.1 API method description

This API response contains all the data of installed software per device. Returns a table with an entry for every unique combination of DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion.

2.1.1 Limitations

Rate limitations for this API are 5 calls per minute and 20 calls per hour.

2.2 Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs 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'

2.3 URL

GET /api/machines/SoftwareInventoryExport

Parameters

  • sasValidHours: The number of hours that the download URLs will be valid for (Maximum 24 hours)

2.5 Properties

Note

  • The files are gzip compressed & in multiline JSON format.
  • The download URLs are only valid for 3 hours. Otherwise you can use the parameter.
  • For maximum download speed of your data, you can make sure you are downloading from the same Azure region that your data resides.

Property (ID) Data type Description Example of a returned value
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"]
GeneratedTime string The time that the export was generated. 2021-05-20T08:00:00Z

2.6 Examples

2.6.1 Request example

GET https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryExport

2.6.2 Response example

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#microsoft.windowsDefenderATP.api.ExportFilesResponse",
    "exportFiles": [
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/SoftwareInventory/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00393-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/SoftwareInventory/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/SoftwareInventory/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c001.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=..."
    ],
    "generatedTime": "2021-01-11T11:01:00Z"
}

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.