Qualys Global IT Asset Inventory API User Guide
File info: application/pdf · 56 pages · 658.91KB
Qualys Global IT Asset Inventory API User Guide
4 Preface About Qualys Preface This user guide is intended for application developers who will use the Qualys Global IT Asset Inventory API v2. It is recommended to use v2 APIs if you’re using Qualys Global IT
Global IT Asset Inventory API v2 - User Guide - Qualys
2021-04-19 — This user guide is intended for application developers who will use the Qualys Global IT ... "fullName": "Apple Mac mini Mac mini (Late. 2014)",.
Full PDF Document
If the inline viewer fails, it will open the original document in compatibility mode automatically. You can also open the file directly.
Extracted Text
Global IT Asset Inventory API v2
User Guide Version 1.3.5
April 19, 2021
Copyright 2021 by Qualys, Inc. All Rights Reserved.
Qualys and the Qualys logo are registered trademarks of Qualys, Inc. All other trademarks are the property of their respective owners.
Qualys, Inc. 919 E Hillsdale Blvd 4th Floor Foster City, CA 94404 1 (650) 801 6100
Table of Contents
Preface................................................................................................................. 4
About Qualys ........................................................................................................................... 4 Contact Qualys Support .......................................................................................................... 4
Chapter 1 - Welcome........................................................................................ 5
Qualys API Framework ........................................................................................................... 5 Qualys API Gateway URL ........................................................................................................ 6 Introduction to Global IT Asset Inventory API Paradigm .................................................... 7 API Rate Limits ......................................................................................................................... 9
Chapter 2 - Assets Host Data APIs .............................................................. 11
Count of Assets ...................................................................................................................... 11 List Host details of specific asset ......................................................................................... 13 List Host Details of All Assets .............................................................................................. 29
Appendix...........................................................................................................47
Error Messages ....................................................................................................................... 47 Supported Operators ............................................................................................................. 47
Preface About Qualys
Preface
This user guide is intended for application developers who will use the Qualys Global IT Asset Inventory API v2. It is recommended to use v2 APIs if you're using Qualys Global IT Asset Inventory 1.3.5 or later. We are still supporting the v1 APIs. Refer Global IT Asset Inventory API v1 user guide to use v1 APIs.
About Qualys
Qualys, Inc. (NASDAQ: QLYS) is a pioneer and leading provider of cloud-based security and compliance solutions. The Qualys Cloud Platform and its integrated apps help businesses simplify security operations and lower the cost of compliance by delivering critical security intelligence on demand and automating the full spectrum of auditing, compliance and protection for IT systems and web applications. Founded in 1999, Qualys has established strategic partnerships with leading managed service providers and consulting organizations including Accenture, BT, Cognizant Technology Solutions, Deutsche Telekom, Fujitsu, HCL, HP Enterprise, IBM, Infosys, NTT, Optiv, SecureWorks, Tata Communications, Verizon and Wipro. The company is also a founding member of the Cloud Security Alliance (CSA). For more information, please visit www.qualys.com.
Contact Qualys Support
Qualys is committed to providing you with the most thorough support. Through online documentation, telephone help, and direct email support, Qualys ensures that your questions will be answered in the fastest time possible. We support you 7 days a week, 24 hours a day. Access support information at www.qualys.com/support/.
4
Chapter 1 - Welcome Qualys API Framework
Chapter 1 - Welcome
Welcome to Global IT Asset Inventory API v2. Get Started Qualys API Framework - Learn the basics about making API requests. The base URL depends on the platform where your Qualys account is located. Introduction to Global IT Asset Inventory API Paradigm - Get tips on using the Curl command-line tool to make API requests. Every API request must authenticate using a JSON Web Token (JWT) obtained from the Qualys Authentication API. Get API Notifications Subscribe to our API Notifications RSS Feeds for announcements and latest news.
From our Community Join our Community API Notifications RSS Feeds
Qualys API Framework
The Qualys Global IT Asset Inventory API uses the following framework.
Request URL
The URL for making API requests respects the following structure:
https://<baseurl>/<module>/<object>/<object_id>/<operation>
where the components are described below.
<baseurl>
<module> <object> <object_id> <operation>
The Qualys API server URL that you should use for API requests depends on the platform where your account is located. The base URL for Qualys US Platform 1 is: https://gateway.qg1.apps.qualys.com
The API module. For the Global IT Asset Inventory, the module is: "am".
The module specific object.
(Optional) The module specific object ID, if appropriate.
The request operation, such as count.
5
Chapter 1 - Welcome Qualys API Gateway URL
Qualys API Gateway URL
The Qualys API URL you should use for API requests depends on the Qualys platform where your account is located. Click here to identify your Qualys platform and get the API URL This documentation uses the API gateway URL for Qualys US Platform 1 (https://gateway.qg1.apps.qualys.com) in sample API requests. If you're on another platform, please replace this URL with the appropriate gateway URL for your account.
6
Chapter 1 - Welcome Introduction to Global IT Asset Inventory API Paradigm
Introduction to Global IT Asset Inventory API Paradigm
Authentication
You must authenticate to the Qualys Cloud Platform using Qualys account credentials (user name and password) and get the JSON Web Token (JWT) before you can start using the Global IT Asset Inventory APIs. Use the Qualys Authentication API to get the JWT.
For example,
curl -X POST https://gateway.qg1.apps.qualys.com/auth -d "username=value1&password=passwordValue&token=true" -H "ContentType: application/x-www-form-urlencoded"
where gateway.qg1.apps.qualys.com is the base URL to the Qualys API server where your account is located.
- username and password are the credentials of the user account for which you want to fetch Global IT Asset Inventory data
- token should be true
- Content-Type should be "application/x-www-form-urlencoded"
The Authentication API returns a JSON Web Token (JWT) which you can use for authentication during Global IT Asset Inventory calls. The token expires in 4 hours. You must regenerate the token to continue using the Global IT Asset Inventory API.
Using Curl
Curl is a multi-platform command-line tool used to transfer data using multiple protocols. This tool is supported on many systems, including Windows, Unix, Linux and Mac. In this document Curl is used in the examples to build Qualys API requests using the HTTP over SSL (https) protocol, which is required.
Want to learn more? Visit https://curl.haxx.se/
The following Curl options are used according to different situations:
Option -X "POST"
-H "Authorization: Bearer <token>"
Description
The POST method is required for all Global IT Asset Inventory API requests.
This option is used to provide a custom HTTP request header parameter for authentication. Provide the JSON Web Token (JWT) received from Qualys authentication API in the following format: Authorization: Bearer <token> For information about Qualys authentication API, see Authentication.
The sample below shows a typical Curl request using options mentioned above and how they interact with each other.
curl -X POST "https://gateway.qg1.apps.qualys.com/rest/2.0/search/am/asset" -H "Authorization: Bearer <token>"
7
Chapter 1 - Welcome Introduction to Global IT Asset Inventory API Paradigm
Limit your results
Use the optional "fields" parameter for any API request to limit the amount of information returned in the results. Simply specify the fields you want to include or exclude in the output, and all other information will be filtered out (excluded). Multiple fields are comma separated.
Sample limit results
Use this request to get a list of all asset hosts with information for only the operatingSystem and hardware fields:
curl -X POST -H 'Accept: */*' -H 'Authorization: <JWT Token>' -H 'Content-Type: application/json' -i 'https://gateway.qg1.apps.qualys.com/rest/2.0/search/am/asset?pageSize=100&includeFie lds=operatingSystem,hardware'
Note:
The response would still include all the fields, but other than the included fields, the value returned for all other fields would be null.
You can include the following fields to limit your results:
address agent agentId assetName biosAssetTag biosDescription biosSerialNumber cloudProvider container cpuCount dnsName hardware hostId inventory isContainerHost lastBoot
lastLocation lastLoggedOnUser netbiosName networkInterface openPort operatingSystem processor provider sensor service software tag timeZone totalMemory userAccount volume
8
Chapter 1 - Welcome API Rate Limits
API Rate Limits
The Qualys API enforces limits on the API calls a customer can make based on their subscription settings. The limits apply to the use of all Qualys APIs except "auth" API (JWT Token Generation API). Default API control settings are provided by the service. Note these settings may be customized per subscription by Qualys Support. The rate count and period are calculated dynamically each time an API call is received. The rate period represents a rolling window when API calls are counted.
API Controls Definition
X-RateLimit-Remaining: This indicates the total API calls remaining in current rate limit window. X-RateLimit-ToWait-Sec: This time indicates the wait time for the rate limit to be reset. The customer has to wait for that time to execute next API calls. X-RateLimit-Window-Sec: This value indicates the total time window assigned for the APIs to be executed. X-RateLimit-Limit: This indicates the max number of API calls that can be executed in that particular rate limit window.
Sample Request
curl -X POST -H 'Accept: */*' -H 'Authorization: Bearer <JWT Token>' -H 'Content-Type: application/json' -i 'https://gateway.qg1.apps.qualys.com/rest/2.0/count/am/asset'
Note: Provide "-i" in the curl request as shown in the example returns the response headers which includes the rate limit related parameters. After executing a curl request, check the following parameters in response headers to check the rate-limit status: X-RateLimit-Remaining: 0 X-RateLimit-ToWait-Sec: 300 X-RateLimit-Window-Sec: 3600 X-RateLimit-Limit: 300 Example: A subscription for Standard API Service has the default API control settings. Consider that the API rate limit set for a customer is 300 API calls for a time window of 3600 seconds. If 300 API calls are received in a 5 minute period and none are blocked by any API limiting rules, then you need to wait 55 minutes before making the next call to the API. During the wait period API calls will be blocked by the rate limiting rule.
9
Chapter 1 - Welcome API Rate Limits
Sample HTTP Response Headers
Sample 1: Normal API call (API call not blocked)
Server: nginx/1.19.1 Date: Fri, 16 Apr 2021 12:29:52 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Vary: Accept-Encoding X-RateLimit-Remaining: 4 X-RateLimit-Window-Sec: 100 X-RateLimit-Limit: 5 Vary: Accept-Encoding Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-XSS-Protection: 1 ; mode=block Referrer-Policy: no-referrer
{"count":580,"responseCode":"SUCCESS","responseMessage":"Valid API Access"}
Sample 2: API Call Blocked - Rate Limit exceeded
Server: nginx/1.19.1 Date: Fri, 16 Apr 2021 12:28:53 GMT Content-Length: 0 Connection: keep-alive X-RateLimit-Remaining: 0 X-RateLimit-ToWait-Sec: 33 X-RateLimit-Window-Sec: 100 X-RateLimit-Limit: 5 Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 X-Content-Type-Options: nosniff X-Frame-Options: DENY X-XSS-Protection: 1 ; mode=block Referrer-Policy: no-referrer
10
Chapter 2 - Assets Host Data APIs Count of Assets
Chapter 2 - Assets Host Data APIs
Use these API functions to get host data from Global IT Asset Inventory
Permissions
- User must have the Global IT Asset Inventory module and the "App API Enabled" option enabled for that role.
Count of Assets
Get count of assets satisfying the specified filter criteria. rest/2.0/count/am/asset [POST]
Input Parameters
filter (String)
Filter the events list by providing a filter in json and xml format. Make sure your filter criteria is provided in xml/json format in the request body. If you don't provide filter parameter, it will show details of all the assets. For more information on supported operators, refer Supported Operators.
For example (json) {
"filters": [ { "field": "software.product", "operator": "CONTAINS", "value": "Python" }
] }
For example (xml) <FilterRequest>
<filters> <Criteria field="software.product"
operator="CONTAINS"><value>Python</value></Criteria> </filters>
</FilterRequest>
11
Chapter 2 - Assets Host Data APIs Count of Assets
assetLastUpdated (String)
lastSeenAssetId (Integer) Authorization (String)
Shows records updated on or after this date with the UTC format as yyyy-MM-ddTHH:mmZ e.g. 2019-03-01T11:30Z
This date gets updated whenever any activity happens on the asset. Few examples of such activity: - Vulnerability Management scan - Policy Compliance scan - Inventory collection - Security Configuration Assessment - CertView scan - AssetView or CloudView connector run - Secure Enterprise Mobility scan - Out-of-Band Configuration Assessment - Asset rename - Purge of VM, PC, OCA, CertView records - Agent manifest download - Asset Inventory asset identification updates
Use to get the count of assets having asset id greater than the specified last seen assetid.
(Required) Authorization token to authenticate to the Qualys Cloud Platform. Prepend token with "Bearer" and one space. For example - Bearer authToken
Sample - Get count of all assets
Request:
curl -X POST -H 'Accept: */*' -H 'Authorization: Bearer <JWTToken>' -H 'Content-Type: application/json' -i 'https://gateway.qg1.apps.qualys.com/rest/2.0/count/am/asset'
Response: {
}
"count": 850, "responseCode": "SUCCESS", "responseMessage": "Valid API Access"
12
Chapter 2 - Assets Host Data APIs List Host details of specific asset
List Host details of specific asset
Get details of specific asset by providing an asset id. rest/2.0/get/am/asset [GET]
Input Parameters
excludeFields (String)
includeFields (String)
assetId (Integer) Authorization (String)
Comma separated list of fields to be excluded from the asset object in the response. Default is None. You can choose from the list of fields specified in the section "Limit your results". For example, to exclude openPort and software from the response: excludeFields=openPort,software
Comma separated list of fields to be included in the asset object in the response. Default is All. You can choose from the list of fields specified in the section "Limit your results". For example, to include only operatingSystem and hardware in the response: includeFields=operatingSystem,hardware
(Required) Use to specify theAssetId for which you want to retrieve the details.
(Required) Authorization token to authenticate to the Qualys Cloud Platform. Prepend token with "Bearer" and one space. For example - Bearer authToken
Sample - List details of specified asset by assetid
Request:
curl -X GET -H 'Accept: */*' -H 'Authorization: Bearer <JWTToken>' -H 'Content-Type: application/json' -i 'https://gateway.qg1.apps.qualys.com/rest/2.0/get/am/asset?assetId =8194990'
Response: {
"responseMessage": "Valid API Access", "count": 1, "responseCode": "SUCCESS", "lastSeenAssetId": null, "hasMore": 0, "assetListData": {
"asset": [ { "assetId": 8194990, "assetUUID": "b788afab-88d1-45d1-81d8-
13
Chapter 2 - Assets Host Data APIs List Host details of specific asset
7e643ac912c4", "hostId": 1636263, "lastModifiedDate": "2021-04-01T13:04:08.000Z", "agentId": "b788afab-88d1-45d1-81d8-7e643ac912c4", "createdDate": "2021-03-30T08:33:43.000Z", "sensorLastUpdatedDate": "2021-04-
01T13:04:08.000Z", "assetType": "HOST", "address": "10.113.198.215", "dnsName": "Administrators-Mac-mini.local", "assetName": "Administrators-Mac-mini.local", "netbiosName": "MACMINI-C9E7B4", "timeZone": "+05:30", "biosDescription": "Macmini7,1, 236.0.0.0.0,
2.24f32", "lastBoot": "2021-03-30T07:02:09.983Z", "totalMemory": 4096, "cpuCount": 1, "lastLoggedOnUser": "Administrator", "hwUUID": "A1432A42-CE19-E096-BA88-79C0149A9B15", "biosSerialNumber": "C07NGCF8G1HV", "biosAssetTag": "NoAssetTag", "isContainerHost": false, "operatingSystem": { "osName": "Apple macOS Sierra (10.12.6)", "fullName": "Apple macOS Sierra (10.12.6)", "category": "Mac / Client", "category1": "Mac", "category2": "Client", "productName": "macOS", "publisher": "Apple", "edition": null, "marketVersion": "Sierra", "version": "10.12", "update": "10.12.6", "architecture": null, "lifecycle": { "gaDate": "2016-09-20T00:00:00.000Z", "eolDate": "Not Announced", "eosDate": "Not Announced", "stage": "GA", "lifeCycleConfidence": "Exact", "eolSupportStage": "Not Announced", "eosSupportStage": "Not Announced" }, "taxonomy": {
14
Chapter 2 - Assets Host Data APIs List Host details of specific asset
"id": null, "name": "Mac / Client", "category1": "Mac", "category2": "Client" }, "productUrl": "https://en.wikipedia.org/wiki/MacOS_version_history#Version_11:_% 22Big_Sur%22,,", "productFamily": null, "installDate": "2018-06-21T16:08:09.000Z" }, "hardware": { "fullName": "Apple Mac mini Mac mini (Late 2014)", "category": "Computers / Desktop", "category1": "Computers", "category2": "Desktop", "manufacturer": "Apple", "productName": "Mac mini", "model": "Mac mini (Late 2014)", "lifecycle": { "introDate": "2014-10-16T00:00:00.000Z", "gaDate": "2014-10-16T00:00:00.000Z", "eosDate": "2018-10-30T00:00:00.000Z", "obsoleteDate": "2025-10-30T00:00:00.000Z", "stage": "EOS", "lifeCycleConfidence": "Exact" }, "taxonomy": { "id": null, "name": "Computers / Desktop", "category1": "Computers", "category2": "Desktop" }, "productUrl": "https://support.apple.com/enin/HT201894,,", "productFamily": null }, "userAccountListData": { "userAccount": [ {
"name": "Administrator" } ] }, "openPortListData": {
15
Chapter 2 - Assets Host Data APIs List Host details of specific asset
"openPort": [ { "port": 50667, "description": "", "protocol": "TCP", "detectedService": "node", "firstFound": null, "lastUpdated": null }, { "port": 50035, "description": "", "protocol": "TCP", "detectedService": "node", "firstFound": null, "lastUpdated": null }
] }, "volumeListData": {
"volume": [ { "name": "/", "free": 394516393984, "size": 498985959424 }
] }, "networkInterfaceListData": {
"networkInterface": [ { "hostname": null, "addressIpV4": "10.113.198.215", "addressIpV6":
"2600:c02:1021:24c6:e0ee:b502:9c56:3993, 2600:c02:1021:24c6:d0b7:5169:11b6:f06f, 2600:c02:1021:24c6:8e6:d4f0:dcb6:5d61, 2600:c02:1021:24c6:443e:4b78:89ee:42e4, fe80:0:0:0:40b:3915:54da:d8fb",
"macAddress": "0c:4d:e9:c9:e7:b4", "interfaceName": "en0", "dnsAddress": "10.113.194.41, 10.113.198.42", "gatewayAddress": "10.113.198.1", "manufacturer": "Apple", "macVendorIntroDate": 1374624000000,
16
Chapter 2 - Assets Host Data APIs List Host details of specific asset
"addresses": null } ] }, "softwareListData": { "software": [ {
"id": 2659663078959614500, "fullName": "Qualys Cloud Agent 2.1 2.1.1 (2.1.1.34)",
"softwareType": "Application", "isIgnored": 0, "ignoredReason": null, "category": "Security / Agent", "category1": "Security", "category2": "Agent", "productName": "Cloud Agent", "component": "Client", "publisher": "Qualys", "edition": "", "marketVersion": "2.1", "version": "2.1.1", "update": "2.1.1.34", "architecture": "", "installDate": "2018-10-09T00: 00: 00.000Z", "lastUpdated": "2019-07-24T22: 57: 50.000Z", "lastUseDate": null, "language": null, "formerlyKnownAs": "", "isPackage": false, "isPackageComponent": false, "packageName": "", "productUrl": "https://www.qualys.com/docs/qualys-cloudagentbrief.pdf,https://www.qualys.com/documentation/releasenotes/,", "lifecycle": {
"gaDate": "2018-09-30T00:00:00.000Z", "eolDate": "Not Announced", "eosDate": "Not Announced", "stage": "GA", "lifeCycleConfidence": "Exact", "eolSupportStage": " ", "eosSupportStage": " "
17
Chapter 2 - Assets Host Data APIs List Host details of specific asset
}, "supportStageDesc": null, "license": {
"category": "Commercial", "subcategory": "Free" } }, { "fullName": "Apache httpd 2 2.4 (2.4.6)", "softwareType": "Application", "ignoredReason": null, "category": "Network Application / Web Servers", "category1": "Network Application", "category2": "Web Servers", "productName": "httpd", "component": "Server", "publisher": "Apache", "edition": "", "marketVersion": "2", "version": "2.4", "update": "2.4.6", "architecture": "", "installDate": "1970-0101T00:00:00.000Z", "lastUpdated": "1970-0101T00:00:00.000Z", "lastUseDate": null, "language": null, "formerlyKnownAs": "HTTP Server, Apache", "isPackage": false, "isPackageComponent": true, "packageName": "", "productUrl": "https://www.wikiwand.com/en/Apache_HTTP_Server,https://httpd.apac he.org/download.cgi,https://httpd.apache.org/docs/2.0/", "lifecycle": { "gaDate": "2012-02-21T00:00:00.000Z", "eolDate": null, "eosDate": null, "stage": "GA", "lifeCycleConfidence": "Exact", "eolSupportStage": "Not Announced", "eosSupportStage": "Not Announced" }, "supportStageDesc": null,
18
Chapter 2 - Assets Host Data APIs List Host details of specific asset
(Apache-2.0)" a3f576bb830f",
"license": { "category": "Open Source",
"subcategory": "Apache License 2.0
} } ] }, "provider": null, "cloudProvider": null, "agent": { "version": "2.5.1.71", "configurationProfile": "Initial Profile", "activations": [ {
"key": "98171724-8bb3-4a24-a19c-
"status": "ACTIVE" } ], "connectedFrom": "10.113.198.215", "lastActivity": 1617281690000, "lastCheckedIn": 1617281690000, "lastInventory": 1617281831000, "udcManifestAssigned": false, "errorStatus": false }, "sensor": { "activatedForModules": [ "VM", "AGENT_VM" ], "pendingActivationForModules": [], "lastVMScan": 1617259196000, "lastComplianceScan": 0, "lastFullScan": 1617259196000 }, "container": null, "inventory": { "source": "QAGENT", "created": 1617093223000, "lastUpdated": 1617282248000 }, "activity": null, "tagList": { "tag": [
19
Chapter 2 - Assets Host Data APIs List Host details of specific asset
{ "tagId": 8839750, "tagName": "Cloud Agent", "foregroundColor": 0, "backgroundColor": -26368, "businessImpact": null
}, {
"tagId": 13928948, "tagName": "Dynamic_child210323104955355", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13928946, "tagName": "Automation_dynamic210323104839339", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13906938, "tagName": "Automation_dynamic210322060759359", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13786620, "tagName": "Automation_dynamic210312104056356", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13906939, "tagName": "Dynamic_child210322060912312", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null
20
Chapter 2 - Assets Host Data APIs List Host details of specific asset
}, {
"tagId": 13858230, "tagName": "Automation_dynamic210318104836336", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13626617, "tagName": "tagset_1539143", "foregroundColor": 0, "backgroundColor": -2070938, "businessImpact": null }, { "tagId": 13858231, "tagName": "Dynamic_child210318104950350", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13906817, "tagName": "pp11", "foregroundColor": 0, "backgroundColor": -65281, "businessImpact": null }, { "tagId": 13626621, "tagName": "tagset_1539902", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13651646, "tagName": "sampleTag123", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, {
21
Chapter 2 - Assets Host Data APIs List Host details of specific asset
"tagId": 13786621, "tagName": "Dynamic_child210312104210310", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13822654, "tagName": "Automation_dynamic210316104844344", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13807614, "tagName": "Automation_dynamic210316032853353", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13822655, "tagName": "Dynamic_child21031610500030", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13807615, "tagName": "Dynamic_child21031603300737", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13786761, "tagName": "Dynamic_child210314105015315", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null
22
Chapter 2 - Assets Host Data APIs List Host details of specific asset
}, {
"tagId": 13438032, "tagName": "sampleTag", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13786759, "tagName": "Automation_dynamic21031410490131", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13906824, "tagName": "Dynamic_child210322104640340", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 11292014, "tagName": "groovy true", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13906823, "tagName": "Automation_dynamic210322104528328", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 11908212, "tagName": "test AI rule", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null },
23
Chapter 2 - Assets Host Data APIs List Host details of specific asset
{ "tagId": 13772815, "tagName":
"Dynamic_child210312124831331", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null
}, {
"tagId": 13772814, "tagName": "Automation_dynamic210312124717317", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13752022, "tagName": "Dynamic_child210309104828328", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13752021, "tagName": "Automation_dynamic210309104713313", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13893206, "tagName": "Dynamic_child210321104856356", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13893205, "tagName": "Automation_dynamic210321104742342", "foregroundColor": 0, "backgroundColor": -65536,
24
Chapter 2 - Assets Host Data APIs List Host details of specific asset
"businessImpact": null }, {
"tagId": 12066438, "tagName": "test groovy", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13751521, "tagName": "pp01", "foregroundColor": 0, "backgroundColor": -13159, "businessImpact": null }, { "tagId": 9475426, "tagName": "sayali :: abc", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13651623, "tagName": "f", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13751528, "tagName": "Dynamic_child210310103316316", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13751527, "tagName": "Automation_dynamic21031010320333", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null },
25
Chapter 2 - Assets Host Data APIs List Host details of specific asset
{ "tagId": 13906917, "tagName":
"Automation_dynamic210322104635335", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null
}, {
"tagId": 10128415, "tagName": "assetname1", "foregroundColor": 0, "backgroundColor": -26368, "businessImpact": null }, { "tagId": 13906919, "tagName": "Dynamic_child210322104748348", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13462313, "tagName": "sk-d", "foregroundColor": 0, "backgroundColor": -10006873, "businessImpact": null }, { "tagId": 10326424, "tagName": "sunny AWS 2121", "foregroundColor": 0, "backgroundColor": -3355444, "businessImpact": null }, { "tagId": 10418164, "tagName": "Open Port Test", "foregroundColor": 0, "backgroundColor": -256, "businessImpact": null }, { "tagId": 13849418,
26
Chapter 2 - Assets Host Data APIs List Host details of specific asset
"tagName": "auto_dynamicOpenPort_A3J4PO",
"foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 11725461, "tagName": "ddd", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 10271453, "tagName": "sk233", "foregroundColor": 0, "backgroundColor": -256, "businessImpact": null }, { "tagId": 10151220, "tagName": "ag1", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": "HIGH" } ] }, "serviceList": { "service": [ { "description": null, "name": "com.apple.security.agent.login.00000000-0000-0000-00000000000186BB", "status": "stopped" }, { "description": null, "name": "com.apple.security.authhost.00000000-0000-0000-00000000000186BB", "status": "stopped" } ]
27
Chapter 2 - Assets Host Data APIs List Host details of specific asset
}, "lastLocation": null, "processor": {
"description": "Intel Core i5", "speed": 1400, "numCPUs": 1 } } ] } }
28
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
List Host Details of All Assets
Get details of all assets that satisfy the filter criteria to include or exclude specified fields. If you don't provide filter parameter, it will show details of all the assets. rest/2.0/search/am/asset [POST]
Input Parameter
excludeFields (String)
includeFields (String)
assetLastUpdated (String)
Comma separated list of fields to be excluded from the asset object in the response. Default is None. You can choose from the list of fields specified in the section "Limit your results". For example, to exclude openPort and software from the response: excludeFields=openPort,software
Comma separated list of fields to be included in the asset object in the response. Default is All. You can choose from the list of fields specified in the section "Limit your results". For example, to include only operatingSystem and hardware in the response: includeFields=operatingSystem,hardware
Shows records updated on or after this date with the UTC format as yyyy-MM-ddTHH:mmZ e.g. 2019-03-01T11:30Z
lastSeenAssetId (Integer)
pageSize (Integer)
This date gets updated whenever any activity happens on the asset. Few examples of such activity: - Vulnerability Management scan - Policy Compliance scan - Inventory collection - Security Configuration Assessment - CertView scan - AssetView or CloudView connector run - Secure Enterprise Mobility scan - Out-of-Band Configuration Assessment - Asset rename - Purge of VM, PC, OCA, CertView records - Agent manifest download - Asset Inventory asset identification updates
Use to get the count of assets having asset id greater than the specified last seen assetid.
The number of records per page to be included in the response. If pageSize is not specified in the request, 100 records will be fetched by default. The maximum value supported for pageSize is 100.
29
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
filter (String)
Filter the events list by providing a filter in json and xml format. Make sure your filter criteria is provided in xml/json format in the request body. If you don't provide filter parameter, it will show details of all the assets. For more information on supported operators, refer Supported Operators.
For example (json) {
"filters": [ { "field": "software.product", "operator": "CONTAINS", "value": "Python" }
] }
For example (xml) <FilterRequest>
<filters> <Criteria field="software.product"
operator="CONTAINS"><value>Python</value></Criteria> </filters>
</FilterRequest>
Authorization (String) (Required) Authorization token to authenticate to the Qualys Cloud Platform. Prepend token with "Bearer" and one space. For example Bearer authToken
30
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
Sample - List details of all asset
Request (without filter):
curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <JWTToken>' -H 'Content-Type: application/json' -i 'https://gateway.qg1.apps.qualys.com/rest/2.0/search/am/asset'
Request (with filter - xml):
curl -X POST -H 'Accept: application/xml' -H 'Authorization: Bearer <JWTToken>' -H 'Content-Type: application/xml' -i 'https://gateway.qg1.apps.qualys.com/rest/2.0/search/am/asset' < filter.xml Here, filter.xml file is the request in xml format.
Request (with filter - json):
curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <JWTToken>' -H 'Content-Type: application/json' -i 'https://gateway.qg1.apps.qualys.com/rest/2.0/search/am/asset' < filter.json Here, filter.json file is the request in json format.
Sample Request body in xml format (filter.xml)
<FilterRequest> <filters> <Criteria field="operatingSystem.category1"
operator="EQUALS"><value>Mac</value></Criteria> </filters>
</FilterRequest>
Sample Request body in json format (filter.json)
{ "filters": [ { "field": "operatingSystem.category1", "operator": "EQUALS", "value": "Mac" } ]
}
Response: {
"responseMessage": "Valid API Access",
31
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
"count": 100, "responseCode": "SUCCESS", "lastSeenAssetId": 8195100, "hasMore": 1, "assetListData": {
"asset": [ { "assetId": 8194990, "assetUUID": "b788afab-88d1-45d1-81d8-
7e643ac912c4", "hostId": 1636263, "lastModifiedDate": "2021-04-01T13:04:08.000Z", "agentId": "b788afab-88d1-45d1-81d8-7e643ac912c4", "createdDate": "2021-03-30T08:33:43.000Z", "sensorLastUpdatedDate": "2021-04-
01T13:04:08.000Z", "assetType": "HOST", "address": "10.113.198.215", "dnsName": "Administrators-Mac-mini.local", "assetName": "Administrators-Mac-mini.local", "netbiosName": "MACMINI-C9E7B4", "timeZone": "+05:30", "biosDescription": "Macmini7,1, 236.0.0.0.0,
2.24f32", "lastBoot": "2021-03-30T07:02:09.983Z", "totalMemory": 4096, "cpuCount": 1, "lastLoggedOnUser": "Administrator", "hwUUID": "A1432A42-CE19-E096-BA88-79C0149A9B15", "biosSerialNumber": "C07NGCF8G1HV", "biosAssetTag": "NoAssetTag", "isContainerHost": false, "operatingSystem": { "osName": "Apple macOS Sierra (10.12.6)", "fullName": "Apple macOS Sierra (10.12.6)", "category": "Mac / Client", "category1": "Mac", "category2": "Client", "productName": "macOS", "publisher": "Apple", "edition": null, "marketVersion": "Sierra", "version": "10.12", "update": "10.12.6", "architecture": null, "lifecycle": {
32
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
"gaDate": "2016-09-20T00:00:00.000Z", "eolDate": "Not Announced", "eosDate": "Not Announced", "stage": "GA", "lifeCycleConfidence": "Exact", "eolSupportStage": "Not Announced", "eosSupportStage": "Not Announced" }, "taxonomy": { "id": null, "name": "Mac / Client", "category1": "Mac", "category2": "Client" }, "productUrl": "https://en.wikipedia.org/wiki/MacOS_version_history#Version_11:_% 22Big_Sur%22,,", "productFamily": null, "installDate": "2018-06-21T16:08:09.000Z" }, "hardware": { "fullName": "Apple Mac mini Mac mini (Late 2014)", "category": "Computers / Desktop", "category1": "Computers", "category2": "Desktop", "manufacturer": "Apple", "productName": "Mac mini", "model": "Mac mini (Late 2014)", "lifecycle": { "introDate": "2014-10-16T00:00:00.000Z", "gaDate": "2014-10-16T00:00:00.000Z", "eosDate": "2018-10-30T00:00:00.000Z", "obsoleteDate": "2025-10-30T00:00:00.000Z", "stage": "EOS", "lifeCycleConfidence": "Exact" }, "taxonomy": { "id": null, "name": "Computers / Desktop", "category1": "Computers", "category2": "Desktop" }, "productUrl": "https://support.apple.com/enin/HT201894,,", "productFamily": null
33
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
}, "userAccountListData": {
"userAccount": [ { "name": "Administrator" }
] }, "openPortListData": {
"openPort": [ { "port": 50667, "description": "", "protocol": "TCP", "detectedService": "node", "firstFound": null, "lastUpdated": null }, { "port": 50035, "description": "", "protocol": "TCP", "detectedService": "node", "firstFound": null, "lastUpdated": null }
] }, "volumeListData": {
"volume": [ { "name": "/", "free": 394516393984, "size": 498985959424 }
] }, "networkInterfaceListData": {
"networkInterface": [ { "hostname": null, "addressIpV4": "10.113.198.215", "addressIpV6":
"2600:c02:1021:24c6:e0ee:b502:9c56:3993, 2600:c02:1021:24c6:d0b7:5169:11b6:f06f, 2600:c02:1021:24c6:8e6:d4f0:dcb6:5d61,
34
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
2600:c02:1021:24c6:443e:4b78:89ee:42e4, fe80:0:0:0:40b:3915:54da:d8fb",
"macAddress": "0c:4d:e9:c9:e7:b4", "interfaceName": "en0", "dnsAddress": "10.113.194.41, 10.113.198.42", "gatewayAddress": "10.113.198.1", "manufacturer": "Apple", "macVendorIntroDate": 1374624000000, "addresses": null } ] }, "softwareListData": { "software": [ { "id": 2659663078959614500, "fullName": "Qualys Cloud Agent 2.1 2.1.1 (2.1.1.34)", "softwareType": "Application", "isIgnored": 0, "ignoredReason": null, "category": "Security / Agent", "category1": "Security", "category2": "Agent", "productName": "Cloud Agent", "component": "Client", "publisher": "Qualys", "edition": "", "marketVersion": "2.1", "version": "2.1.1", "update": "2.1.1.34", "architecture": "", "installDate": "2018-10-09T00: 00: 00.000Z", "lastUpdated": "2019-07-24T22: 57: 50.000Z", "lastUseDate": null, "language": null, "formerlyKnownAs": "", "isPackage": false, "isPackageComponent": false, "packageName": "", "productUrl": "https://www.qualys.com/docs/qualys-cloudagentbrief.pdf,https://www.qualys.com/documentation/release-
35
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
notes/,", "lifecycle": { "gaDate": "2018-09-30T00:00:00.000Z", "eolDate": "Not Announced", "eosDate": "Not Announced", "stage": "GA", "lifeCycleConfidence": "Exact", "eolSupportStage": " ", "eosSupportStage": " " }, "supportStageDesc": null, "license": { "category": "Commercial", "subcategory": "Free" }
}, {
"fullName": "Apache httpd 2 2.4 (2.4.6)", "softwareType": "Application", "ignoredReason": null, "category": "Network Application / Web
Servers", "category1": "Network Application", "category2": "Web Servers", "productName": "httpd", "component": "Server", "publisher": "Apache", "edition": "", "marketVersion": "2", "version": "2.4", "update": "2.4.6", "architecture": "", "installDate": "1970-01-
01T00:00:00.000Z", "lastUpdated": "1970-01-
01T00:00:00.000Z", "lastUseDate": null, "language": null,
"formerlyKnownAs": "HTTP Server, Apache", "isPackage": false, "isPackageComponent": true, "packageName": "", "productUrl":
"https://www.wikiwand.com/en/Apache_HTTP_Server,https://httpd.apac he.org/download.cgi,https://httpd.apache.org/docs/2.0/",
"lifecycle": {
36
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
(Apache-2.0)" a3f576bb830f",
"gaDate": "2012-02-21T00:00:00.000Z", "eolDate": null, "eosDate": null, "stage": "GA", "lifeCycleConfidence": "Exact",
"eolSupportStage": "Not Announced", "eosSupportStage": "Not Announced"
}, "supportStageDesc": null, "license": {
"category": "Open Source", "subcategory": "Apache License 2.0
} } ] }, "provider": null, "cloudProvider": null, "agent": { "version": "2.5.1.71", "configurationProfile": "Initial Profile", "activations": [ {
"key": "98171724-8bb3-4a24-a19c-
"status": "ACTIVE" } ], "connectedFrom": "10.113.198.215", "lastActivity": 1617281690000, "lastCheckedIn": 1617281690000, "lastInventory": 1617281831000, "udcManifestAssigned": false, "errorStatus": false }, "sensor": { "activatedForModules": [ "VM", "AGENT_VM" ], "pendingActivationForModules": [], "lastVMScan": 1617259196000, "lastComplianceScan": 0, "lastFullScan": 1617259196000 },
37
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
"container": null, "inventory": {
"source": "QAGENT", "created": 1617093223000, "lastUpdated": 1617282248000 }, "activity": null, "tagList": { "tag": [
{ "tagId": 8839750, "tagName": "Cloud Agent", "foregroundColor": 0, "backgroundColor": -26368, "businessImpact": null
}, {
"tagId": 13928948, "tagName": "Dynamic_child210323104955355", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13928946, "tagName": "Automation_dynamic210323104839339", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13906938, "tagName": "Automation_dynamic210322060759359", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13786620, "tagName": "Automation_dynamic210312104056356", "foregroundColor": 0, "backgroundColor": -65536,
38
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
"businessImpact": null }, {
"tagId": 13906939, "tagName": "Dynamic_child210322060912312", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13858230, "tagName": "Automation_dynamic210318104836336", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13626617, "tagName": "tagset_1539143", "foregroundColor": 0, "backgroundColor": -2070938, "businessImpact": null }, { "tagId": 13858231, "tagName": "Dynamic_child210318104950350", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13906817, "tagName": "pp11", "foregroundColor": 0, "backgroundColor": -65281, "businessImpact": null }, { "tagId": 13626621, "tagName": "tagset_1539902", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null
39
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
}, {
"tagId": 13651646, "tagName": "sampleTag123", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13786621, "tagName": "Dynamic_child210312104210310", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13822654, "tagName": "Automation_dynamic210316104844344", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13807614, "tagName": "Automation_dynamic210316032853353", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13822655, "tagName": "Dynamic_child21031610500030", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13807615, "tagName": "Dynamic_child21031603300737", "foregroundColor": 0, "backgroundColor": -65536,
40
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
"businessImpact": null }, {
"tagId": 13786761, "tagName": "Dynamic_child210314105015315", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13438032, "tagName": "sampleTag", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13786759, "tagName": "Automation_dynamic21031410490131", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13906824, "tagName": "Dynamic_child210322104640340", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 11292014, "tagName": "groovy true", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13906823, "tagName": "Automation_dynamic210322104528328", "foregroundColor": 0, "backgroundColor": -65536,
41
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
"businessImpact": null }, {
"tagId": 11908212, "tagName": "test AI rule", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13772815, "tagName": "Dynamic_child210312124831331", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13772814, "tagName": "Automation_dynamic210312124717317", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13752022, "tagName": "Dynamic_child210309104828328", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13752021, "tagName": "Automation_dynamic210309104713313", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13893206, "tagName": "Dynamic_child210321104856356", "foregroundColor": 0,
42
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
"backgroundColor": -65536, "businessImpact": null }, { "tagId": 13893205, "tagName": "Automation_dynamic210321104742342", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 12066438, "tagName": "test groovy", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13751521, "tagName": "pp01", "foregroundColor": 0, "backgroundColor": -13159, "businessImpact": null }, { "tagId": 9475426, "tagName": "sayali :: abc", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13651623, "tagName": "f", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 13751528, "tagName": "Dynamic_child210310103316316", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null
43
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
}, {
"tagId": 13751527, "tagName": "Automation_dynamic21031010320333", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13906917, "tagName": "Automation_dynamic210322104635335", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 10128415, "tagName": "assetname1", "foregroundColor": 0, "backgroundColor": -26368, "businessImpact": null }, { "tagId": 13906919, "tagName": "Dynamic_child210322104748348", "foregroundColor": 0, "backgroundColor": -65536, "businessImpact": null }, { "tagId": 13462313, "tagName": "sk-d", "foregroundColor": 0, "backgroundColor": -10006873, "businessImpact": null }, { "tagId": 10326424, "tagName": "sunny AWS 2121", "foregroundColor": 0, "backgroundColor": -3355444, "businessImpact": null },
44
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
{ "tagId": 10418164, "tagName": "Open Port Test", "foregroundColor": 0, "backgroundColor": -256, "businessImpact": null
}, {
"tagId": 13849418, "tagName": "auto_dynamicOpenPort_A3J4PO", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 11725461, "tagName": "ddd", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": null }, { "tagId": 10271453, "tagName": "sk233", "foregroundColor": 0, "backgroundColor": -256, "businessImpact": null }, { "tagId": 10151220, "tagName": "ag1", "foregroundColor": 0, "backgroundColor": 0, "businessImpact": "HIGH" } ] }, "serviceList": { "service": [ { "description": null, "name": "com.apple.security.agent.login.00000000-0000-0000-00000000000186BB", "status": "stopped"
45
Chapter 2 - Assets Host Data APIs List Host Details of All Assets
}, {
"description": null, "name": "com.apple.security.authhost.00000000-0000-0000-00000000000186BB", "status": "stopped" } ] }, "lastLocation": null, "processor": { "description": "Intel Core i5", "speed": 1400, "numCPUs": 1 } } ] } }
46
Appendix Error Messages
Appendix
This appendix describes the types of error messages returned from Global IT Asset Inventory API requests, list of operators with supported attributes.
Error Messages
Error Code 400
403 Forbidden
404 Not found 416 Requested Range Not Satisfiable 500 Failure
Description
The request could not be understood by the server due to malformed syntax. This error also occurs if you provide wrong (or unsupported) operator in the request.
This response code is returned for the following scenarios:
- If the Asset Inventory License is in "Pending Activation". - If "App API Enabled" option is not checked. - If "App API Enabled" option is checked, but the license expiration date (for Trial/Full customers) has elapsed. - If the customer's license subscription cannot be validated.
The server has not found anything matching the Request
Please provide a Page Size value less than the max page size limit set.
The server encountered an unexpected condition which prevented it from fulfilling the request
Supported Operators
This section of the appendix lists supported operators for tokens.
Operator NUMERIC_OPERATORS
NUMERIC_AND_NOT_E QUAL_OPERATORS STRING_OPERATORS STRING_AND_NOT_EQ UAL_OPERATORS
Values EQUALS, IN, NOT_EQUALS, GREATER, LESSER, GREATER_THAN_EQUAL, and LESS_THAN_EQUAL
EQUALS, IN, GREATER, LESSER, GREATER_THAN_EQUAL, LESS_THAN_EQUAL
CONTAINS, IN, EQUALS, and NOT_EQUALS
CONTAINS, IN, and EQUALS
47
Appendix Supported Operators
Operator DATE_OPERATORS
BOOLEAN_OPERATORS ENUM_OPERATORS UUID_OPERATORS IP_OPERATORS
Values EQUALS, NOT_EQUALS, GREATER, LESSER, GREATER_THAN_EQUAL, and LESS_THAN_EQUAL EQUALS EQUALS, NOT_EQUALS, and IN EQUALS and IN EQUALS and IN
Following table lists different attributes with supported operators:
Attribute Asset Attributes asset.assetID asset.name asset.created asset.lastUpdated asset.type asset.lastLoggedOnUser asset.totalMemory asset.timezone asset.trackingMethod asset.lastBoot asset.netbiosName asset.hostID asset.isContainerHost asset.biosAssetTag asset.biosDescription asset.biosHardwareUUID asset.biosSerialNumber asset.agentID accounts.username provider isDockerHost Inventory Attributes inventory.source inventory.created
Operator
NUMERIC_OPERATORS STRING_OPERATORS DATE_OPERATORS DATE_OPERATORS ENUM_OPERATORS STRING_OPERATORS NUMERIC_OPERATORS STRING_OPERATORS ENUM_OPERATORS DATE_OPERATORS STRING_OPERATORS NUMERIC_OPERATORS BOOLEAN_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS UUID_OPERATORS STRING_OPERATORS ENUM_OPERATORS BOOLEAN_OPERATORS
STRING_OPERATORS DATE_OPERATORS
48
Appendix Supported Operators
Attribute inventory.lastUpdated Processor Attributes processors processors.speed Container Attributes container.noOfContainers container.noOfImages container.version Interface Attributes interfaces.hostname interfaces.interfaceName interfaces.macAddress interfaces.manufacturer interfaces.address interfaces.dnsAddress interfaces.gatewayAddress Open Ports Attributes openPorts.description openPorts.detectedService openPorts.protocol openPorts.port openPorts.firstFound openPorts.lastUpdated Services Attributes services.description services.name services.status Sensors Attributes sensors.lastComplianceScan sensors.lastFullScan sensors.lastVmScan Tag Attributes tags.name tags.businessImpact
Operator DATE_OPERATORS
STRING_AND_NOT_EQUAL_OPERATORS NUMERIC_AND_NOT_EQUAL_OPERATORS
NUMERIC_AND_NOT_EQUAL_OPERATORS NUMERIC_AND_NOT_EQUAL_OPERATORS STRING_AND_NOT_EQUAL_OPERATORS
STRING_AND_NOT_EQUAL_OPERATORS STRING_AND_NOT_EQUAL_OPERATORS STRING_AND_NOT_EQUAL_OPERATORS STRING_AND_NOT_EQUAL_OPERATORS IP_OPERATORS IP_OPERATORS IP_OPERATORS
STRING_AND_NOT_EQUAL_OPERATORS STRING_AND_NOT_EQUAL_OPERATORS STRING_AND_NOT_EQUAL_OPERATORS NUMERIC_AND_NOT_EQUAL_OPERATORS DATE_OPERATORS DATE_OPERATORS
STRING_AND_NOT_EQUAL_OPERATORS STRING_AND_NOT_EQUAL_OPERATORS STRING_AND_NOT_EQUAL_OPERATORS
DATE_OPERATORS DATE_OPERATORS DATE_OPERATORS
EQUALS, IN, CONTAINS EQUALS, IN, CONTAINS
49
Attribute Volume Attributes volumes.free volumes.size volumes.name Agent Attributes agent.version agent.connectedFrom agent.errorStatus agent.lastActivity agent.lastCheckedIn Hardware Attributes hardware hardware.category hardware.category1 hardware.category2 hardware.manufacturer hardware.model hardware.product hardware.lifecycle.stage hardware.lifecycle.eos hardware.lifecycle.ga hardware.lifecycle.intro hardware.lifecycle.obs Software Attributes software.architecture software.category software.category1 software.category2 software.component software.edition software.marketVersion software.name software.product software.publisher
Appendix Supported Operators
Operator
NUMERIC_AND_NOT_EQUAL_OPERATORS NUMERIC_AND_NOT_EQUAL_OPERATORS STRING_AND_NOT_EQUAL_OPERATORS
NUMERIC_AND_NOT_EQUAL_OPERATORS IP_OPERATORS BOOLEAN_OPERATORS DATE_OPERATORS DATE_OPERATORS
STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS DATE_OPERATORS DATE_OPERATORS DATE_OPERATORS DATE_OPERATORS
STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS
50
Attribute software.supportStage software.version software.update software.isPackage software.isPackageComponent software.license.category software.license.subcategory software.lifecycle.stage software.installDate software.lastUseDate software.lastUpdated software.lifecycle.eol software.lifecycle.eos software.lifecycle.ga Operating System Attributes operatingSystem operatingSystem.category operatingSystem.category1 operatingSystem.category2 operatingSystem.architecture operatingSystem.component operatingSystem.edition operatingSystem.marketVersion operatingSystem.name operatingSystem.publisher operatingSystem.version operatingSystem.update operatingSystem.lifecycle.stage operatingSystem.installDate operatingSystem.lifecycle.eol operatingSystem.lifecycle.eos operatingSystem.lifecycle.ga AWS Attributes aws.ec2.availabilityZone
Operator STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS BOOLEAN_OPERATORS BOOLEAN_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS DATE_OPERATORS DATE_OPERATORS DATE_OPERATORS DATE_OPERATORS DATE_OPERATORS DATE_OPERATORS
STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS DATE_OPERATORS DATE_OPERATORS DATE_OPERATORS DATE_OPERATORS
STRING_OPERATORS
51
Appendix Supported Operators
Attribute aws.ec2.instanceType aws.ec2.publicDNS aws.ec2.privateDNS aws.ec2.accountId aws.ec2.imageId aws.ec2.instanceId aws.ec2.instanceState aws.ec2.region.code aws.ec2.subnetId aws.ec2.vpcId aws.ec2.hostname aws.ec2.privateIpAddress aws.ec2.publicIpAddress aws.tags.key aws.tags.value aws.ec2.spotInstance aws.ec2.launchDate aws.ec2.hasAgent Azure Attributes azure.vm.imageOffer azure.vm.imagePublisher azure.vm.imageVersion azure.vm.name azure.vm.size azure.vm.vmId azure.vm.resourceGroupName azure.vm.state azure.vm.subnet azure.vm.subscriptionId azure.vm.location azure.vm.platform azure.vm.macAddress azure.tags.value azure.tags.name
Operator STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS IP_OPERATORS IP_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS DATE_OPERATORS BOOLEAN_OPERATORS
STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS
52
Appendix Supported Operators
Appendix Supported Operators
Attribute azure.vm.privateIpAddress azure.vm.publicIpAddress azure.vm.hasAgent GCP Attributes gcp.compute.hostname gcp.compute.instanceId gcp.compute.machineType gcp.compute.network gcp.compute.projectId gcp.compute.projectNumber gcp.compute.macAddress gcp.compute.state gcp.compute.zone gcp.compute.privateIpAddres gcp.compute.publicIpAddress Geo IP Attributes asset.lastLocation asset.lastLocation.city asset.lastLocation.country asset.lastLocation.continent asset.lastLocation.postal asset.lastLocation.state
Operator IP_OPERATORS IP_OPERATORS BOOLEAN_OPERATORS
STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS IP_OPERATORS IP_OPERATORS
STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS STRING_OPERATORS
Note: Following tokens are not available for ITAM (Free) License Subscriber:
hardware.lifecycle.stage, hardware.lifecycle.eos, hardware.lifecycle.ga, hardware.lifecycle.intro, hardware.lifecycle.obs, software.license.category, software.license.subcategory, software.lifecycle.eol, software.lifecycle.eos, software.lifecycle.ga, software.lifecycle.stage, software.isPackage, software.isPackageComponent, operatingSystem.lifecycle.eol, operatingSystem.lifecycle.eos, operatingSystem.lifecycle.ga, operatingSystem.lifecycle.stage, asset.type
53
Appendix Supported Operators
Following are some example to understand the different supported operators by comparing QQL(UI) tokens:
Example 1 - hardware.category1:Computers
Request Body in XML: <FilterRequest> <filters> <Criteria field="hardware.category1" operator="CONTAINS"> <value>Computers</value> </Criteria> </filters> </FilterRequest>
OR Request Body in Json: { "filters": [ { "field": "hardware.category1", "operator": "CONTAINS", "value": "Computers" } ] }
Example 2 - hardware.manufacturer:`Apple` OR hardware.manufacturer:`HPE`
Request Body in XML: <FilterRequest> <filters> <Criteria field="hardware.manufacturer" operator="IN"> <value>Apple,HPE</value> </Criteria> </filters> </FilterRequest>
Example 3 - software:(product:Python and update:2.7.5)
Request Body in XML: <FilterRequest> <filters> <Criteria field="software.product" operator="CONTAINS"> <value>Python</value> </Criteria>
54
Appendix Supported Operators
<Criteria field="software.update" operator="CONTAINS"> <value>2.7.5</value>
</Criteria> </filters> </FilterRequest>
Example 4 - operatingSystem.category1:`Mac` and hardware.category:Notebook
Request Body in XML:
<FilterRequest> <filters> <Criteria field="operatingSystem.category1"
operator="EQUALS"> <value>Mac</value>
</Criteria> <Criteria field="hardware.category" operator="EQUALS">
<value>Notebook</value> </Criteria> </filters> </FilterRequest>
Example 5 - operatingSystem.category1:`Mac` or hardware.category:Notebook
Request Body in XML:
<FilterRequest> <filters> <Criteria field="operatingSystem.category1"
operator="EQUALS"> <value>Mac</value>
</Criteria> <Criteria field="hardware.category" operator="EQUALS">
<value>Notebook</value> </Criteria> </filters> <operation>OR</operation> </FilterRequest>
Example 6 - operatingSystem.category1:`Mac` and hardware.category:Notebook
Request Body in XML:
<FilterRequest> <filters> <Criteria field="operatingSystem.category1"
operator="EQUALS"> <value>Mac</value>
55
Appendix Supported Operators
</Criteria> <Criteria field="hardware.category" operator="EQUALS">
<value>Notebook</value> </Criteria> </filters> <operation>AND</operation> </FilterRequest>
56