Global AssetView

CyberSecurity Asset Management

API User Guide v2
Version 2.2

November 6, 2021

Verity Confidential
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

Get Started ......................................................................................................... 5

Qualys API Framework ........................................................................................................... 5
Qualys API Gateway URL ........................................................................................................ 6
Introduction to GAV/CSAM API Paradigm ............................................................................ 7
API Rate Limits ......................................................................................................................... 9

Assets Host Data APIs .................................................................................... 11

Count of Assets ...................................................................................................................... 11
Get Host details of specific asset ......................................................................................... 14
Get Host Details of All Assets ............................................................................................... 23
Import Business Information Metadata .............................................................................. 35

Import Business Information Metadata .....................................................39

Import Business App Metadata ............................................................................................ 39
Import Asset Business Metadata ......................................................................................... 41

Appendix...........................................................................................................45
Error Messages ....................................................................................................................... 45
Supported Operators ............................................................................................................. 45

Verity Confidential
 Preface
About Qualys

Preface
This user guide is intended for application developers who will use the Qualys Global
AssetView (GAV)/CyberSecurity Asset Management (CSAM) API v2. It is recommended to
use v2 APIs.
For GAV, we are still supporting the v1 APIs. Refer 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
 Get Started
Qualys API Framework

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 GAV/CSAM 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 GAV/CSAM 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> 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
<module> The API module. For the GAV/CSAM, the module is:
“am”.
<object> The module specific object.
<object_id> (Optional) The module specific object ID, if appropriate.
<operation> The request operation, such as count.

5
 Get Started
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
 Get Started
Introduction to GAV/CSAM API Paradigm

Introduction to GAV/CSAM 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 GAV/CSAM 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 "Content-
Type: 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 GAV/CSAM 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 GAV/CSAM calls. The token expires in 4 hours. You must
regenerate the token to continue using the GAV/CSAM 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 Description
-X “POST” The POST method is required for all GAV/CSAM API requests.
-H “Authorization: This option is used to provide a custom HTTP request header parameter
Bearer <token>” 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
 Get Started
Introduction to GAV/CSAM 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 lastLocation
agent lastLoggedOnUser
agentId netbiosName
assetName networkInterface
biosAssetTag openPort
biosDescription operatingSystem
biosSerialNumber processor
cloudProvider provider
container sensor
cpuCount service
dnsName software
hardware tag
hostId timeZone
inventory totalMemory
isContainerHost userAccount
lastBoot volume
criticality businessApps
businessInformation assignedLocation

8
 Get Started
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
 Get Started
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
 Assets Host Data APIs
Count of Assets

Assets Host Data APIs

Use these API functions to get host data from GAV/CSAM.
Note: The software.authorization and lifecycle related parameters are available only for
CSAM subscription. Hence, you can use it in filter criteria and you can see it in the
response if you’ve subscribed for CSAM.

Permissions
- User must have the GAV/CSAM 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 Filter the events list by providing a filter in json and xml format. Make sure
(String) 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
 Assets Host Data APIs
Count of Assets

assetLastUpdated (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
lastSeenAssetId (Integer) Use to get the count of assets having asset id greater than the
specified last seen assetid.
Authorization (String) (Required) Authorization token to authenticate to the Qualys
Cloud Platform. Prepend token with "Bearer" and one space.
For example - Bearer authToken

12
 Assets Host Data APIs
Count of Assets

Sample - Get count of all assets with filter criteria

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' <
filter.json

Here, filter.json file is the request in json format.

Sample Request body in json format (filter.json)
{
"filters": [
{
"field": "software.authorization",
"operator": "EQUALS",
"value": "Authorized"
}
]
}

Response:
{
"count": 850,
"responseCode": "SUCCESS",
"responseMessage": "Valid API Access"
}

13
 Assets Host Data APIs
Get Host details of specific asset

Get 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) 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
includeFields (String) 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
assetId (Integer) (Required) Use to specify theAssetId for which you want to
retrieve the details.
softwareType (String) (Optional) Specify the software type to get the host details for
specified software type. Available values for softwareType
parameter are Application, Unknown, and Others.
Authorization (String) (Required) Authorization token to authenticate to the Qualys
Cloud Platform. Prepend token with "Bearer" and one space.
For example - Bearer authToken

Sample - Get host 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",
"responseCode": "SUCCESS",
"assetListData": {
"asset": [
{
"assetId": 6920718,
"assetUUID": "50d20290-c66a-42e7-8c0a-

14
 Assets Host Data APIs
Get Host details of specific asset

ba6e92b6324c",
"hostId": 1437386,
"lastModifiedDate": "2021-04-06T10:02:33.000Z",
"agentId": null,
"createdDate": "2020-11-25T12:49:25.000Z",
"sensorLastUpdatedDate": "2021-04-
06T10:02:33.000Z",
"assetType": "HOST",
"address": "10.115.110.95",
"dnsName": "localhost.localdomain",
"assetName": "localhost.localdomain",
"netbiosName": null,
"timeZone": "IST",
"biosDescription": null,
"lastBoot": null,
"totalMemory": 5806,
"cpuCount": null,
"lastLoggedOnUser": "root",
"hwUUID": "422a2b16-4c8b-588a-a20c-c1851ad7e376",
"biosSerialNumber": "VMware-42 2a 2b 16 4c 8b 58 8a-
a2 0c c1 85 1a d7 e3 76",
"biosAssetTag": "No Asset Tag",
"isContainerHost": false,
"operatingSystem": {
"osName": "The CentOS Project CentOS 7 (1810)",
"fullName": "The CentOS Project CentOS 7
(1810)",
"category": "Linux / Server",
"category1": "Linux",
"category2": "Server",
"productName": "CentOS",
"publisher": "The CentOS Project",
"edition": null,
"marketVersion": "7",
"version": "1810",
"update": null,
"architecture": null,
"lifecycle": {
"gaDate": "2018-12-03T00:00:00.000Z",
"eolDate": "2020-12-31T00:00:00.000Z",
"eosDate": "2024-06-30T00:00:00.000Z",
"stage": "EOL",
"lifeCycleConfidence": "Exact",
"eolSupportStage": "Full updates",
"eosSupportStage": "Maintenance Updates"
},

15
 Assets Host Data APIs
Get Host details of specific asset

"taxonomy": {
"id": null,
"name": "Linux / Server",
"category1": "Linux",
"category2": "Server"
},
"productUrl":
"https://www.centos.org/,https://en.wikipedia.org/wiki/CentOS,",
"productFamily": null,
"installDate": null
},
"hardware": {
"fullName": "VMware VMware Virtual Platform
VMware Virtual Platform",
"category": "Virtualized / Virtual Machine",
"category1": "Virtualized",
"category2": "Virtual Machine",
"manufacturer": "VMware",
"productName": "VMware Virtual Platform",
"model": "VMware Virtual Platform",
"lifecycle": {
"introDate": null,
"gaDate": null,
"eosDate": null,
"obsoleteDate": null,
"stage": "Unknown",
"lifeCycleConfidence": " "
},
"taxonomy": {
"id": null,
"name": "Virtualized / Virtual Machine",
"category1": "Virtualized",
"category2": "Virtual Machine"
},
"productUrl":
"https://www.linuxjournal.com/article/3458,,",
"productFamily": null
},
"userAccountListData": null,
"openPortListData": {
"openPort": [
{
"port": 709,
"description": "",
"protocol": "UDP",
"detectedService": "portmap/rpcbind",

16
 Assets Host Data APIs
Get Host details of specific asset

"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},
{
"port": 50000,
"description": "",
"protocol": "TCP",
"detectedService":
"IBM_DB2_Universal_Database",
"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},
{
"port": 6000,
"description": "",
"protocol": "TCP",
"detectedService": "x11",
"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},
{
"port": 22,
"description": "",
"protocol": "TCP",
"detectedService": "ssh",
"firstFound": "2020-11-
25T12:46:41.000Z",
"lastUpdated": "2020-11-
25T12:46:41.000Z"
},
{
"port": 3389,
"description": "",
"protocol": "TCP",
"detectedService": null,
"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},

17
 Assets Host Data APIs
Get Host details of specific asset

{
"port": 111,
"description": "",
"protocol": "UDP",
"detectedService": "rpc_udp",
"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},
{
"port": 111,
"description": "",
"protocol": "TCP",
"detectedService": "rpc",
"firstFound": "2020-11-
25T12:46:41.000Z",
"lastUpdated": "2020-11-
25T12:46:41.000Z"
}
]
},
"volumeListData": {
"volume": [
{
"name": "tmpfs",
"free": 2737078272,
"size": 3043934208
},
{
"name": "/dev/mapper/centos-home",
"free": 18629619712,
"size": 18700304384
},
{
"name": "devtmpfs",
"free": 3026444288,
"size": 3026444288
},
{
"name": "/dev/mapper/centos-root",
"free": 19672580096,
"size": 38304645120
},
{
"name": "/dev/sda1",

18
 Assets Host Data APIs
Get Host details of specific asset

"free": 876040192,
"size": 1063256064
}
]
},
"networkInterfaceListData": {
"networkInterface": [
{
"hostname": "localhost.localdomain",
"addressIpV4": "192.168.122.1",
"addressIpV6": null,
"macAddress": "52:54:00:77:e1:71",
"interfaceName": "virbr0",
"dnsAddress": null,
"gatewayAddress": "",
"manufacturer": null,
"macVendorIntroDate": null,
"addresses": null
},
{
"hostname": "localhost.localdomain",
"addressIpV4": "10.115.110.95",
"addressIpV6":
"fe80:0:0:0:250:56ff:feaa:e2da",
"macAddress": "00:50:56:aa:e2:da",
"interfaceName": "ens192",
"dnsAddress": null,
"gatewayAddress": "",
"manufacturer": "VMware",
"macVendorIntroDate": 946944000000,
"addresses": null
}
]
},
"softwareListData": {
"software": [
{
"id": -5698725809391962787,
"fullName": "Python 2.7.5 64-Bit",
"softwareType": "Application",
"isIgnored": false,
"ignoredReason": null,
"category": "Application Development /
Programming Languages",
"category1": "Application Development",
"category2": "Programming Languages",

19
 Assets Host Data APIs
Get Host details of specific asset

"productName": "Python",
"component": null,
"publisher": "Python",
"edition": null,
"marketVersion": "2",
"version": "2.7",
"update": "2.7.5",
"architecture": "64-Bit",
"installDate": "2020-03-
27T16:11:47.000Z",
"installPath": null,
"lastUpdated": "2020-11-
25T12:46:46.000Z",
"lastUseDate": null,
"language": null,
"formerlyKnownAs": null,
"isPackage": false,
"isPackageComponent": false,
"packageName": null,
"productUrl":
"https://en.wikipedia.org/wiki/History_of_Python,,",
"lifecycle": {
"gaDate": "2010-07-03T00:00:00.000Z",
"eolDate": "2020-01-
01T00:00:00.000Z",
"eosDate": "2020-01-
01T00:00:00.000Z",
"stage": "EOL/EOS",
"lifeCycleConfidence": "Exact",
"eolSupportStage": "End-of-life",
"eosSupportStage": "End-of-life"
},
"supportStageDesc": "Python's policy is
to drop support major versions once they reach their end of life",
"license": {
"category": "Open Source",
"subcategory": "Python License
(Python-2.0)"
},
"authorization": "Authorized"
},
{
"id": 9136542396418607016,
"fullName": "OpenBSD OpenSSH Server
7.4p1",
"softwareType": "Application",

20
 Assets Host Data APIs
Get Host details of specific asset

"isIgnored": false,
"ignoredReason": null,
"category": "Networking / Access
Software",
"category1": "Networking",
"category2": "Access Software",
"productName": "OpenSSH",
"component": "Server",
"publisher": "OpenBSD",
"edition": null,
"marketVersion": "7",
"version": "7.4",
"update": "7.4p1",
"architecture": null,
"installDate": "2020-03-
05T14:23:53.000Z",
"installPath": null,
"lastUpdated": "2020-11-
25T12:46:53.000Z",
"lastUseDate": null,
"language": null,
"formerlyKnownAs": "OpenBSD Secure
Shell",
"isPackage": true,
"isPackageComponent": false,
"packageName": null,
"productUrl":
"https://en.wikipedia.org/wiki/OpenSSH,,",
"lifecycle": {
"gaDate": "2016-12-19T00:00:00.000Z",
"eolDate": null,
"eosDate": null,
"stage": "EOL",
"lifeCycleConfidence": "Calculated",
"eolSupportStage": " ",
"eosSupportStage": " "
},
"supportStageDesc": null,
"license": {
"category": "Open Source",
"subcategory": "BSD 2-Clause License
(FreeBSD/Simplified)"
},
"authorization": "Authorized"
}
]

21
 Assets Host Data APIs
Get Host details of specific asset

},
"provider": null,
"cloudProvider": null,
"agent": null,
"sensor": {
"activatedForModules": [
"VM"
],
"pendingActivationForModules": [],
"lastVMScan": 1606306572000,
"lastComplianceScan": 0,
"lastFullScan": 1606306572000
},
"container": null,
"inventory": {
"source": "IP",
"created": 1606308565000,
"lastUpdated": 1617703353000
},
"activity": null,
"tagList": {
"tag": [
{
"tagId": 14151022,
"tagName": "static split",
"foregroundColor": 0,
"backgroundColor": -65536,
"businessImpact": null,
"criticalityScore": 2
}
]
},
"serviceList": null,
"lastLocation": null,
"criticality": {
"score": 2,
"isDefault": true,
"lastUpdated": "2021-06-30T09:43:27.000Z"
},
"processor": null
}
]
}
}

22
 Assets Host Data APIs
Get Host Details of All Assets

Get 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) 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
includeFields (String) 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
assetLastUpdated Shows records updated on or after this date with the UTC format as
(String) 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
lastSeenAssetId Use to get the count of assets having asset id greater than the
(Integer) specified last seen assetid.
pageSize (Integer) 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 300.

23
 Assets Host Data APIs
Get 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>

softwareType (String) (Optional) Specify the software type to get the host details for
specified software type. Available values for softwareType parameter
are Application, Unknown, and Others.
Authorization (String) (Required) Authorization token to authenticate to the Qualys Cloud
Platform. Prepend token with "Bearer" and one space. For example -
Bearer authToken

24
 Assets Host Data APIs
Get Host Details of All Assets

Sample - Get 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",

25
 Assets Host Data APIs
Get Host Details of All Assets

"count": 1,
"responseCode": "SUCCESS",
"lastSeenAssetId": 6920718,
"hasMore": 1,
"assetListData": {
"asset": [
{
"assetId": 6920718,
"assetUUID": "50d20290-c66a-42e7-8c0a-
ba6e92b6324c",
"hostId": 1437386,
"lastModifiedDate": "2021-04-06T10:02:33.000Z",
"agentId": null,
"createdDate": "2020-11-25T12:49:25.000Z",
"sensorLastUpdatedDate": "2021-04-
06T10:02:33.000Z",
"assetType": "HOST",
"address": "10.115.110.95",
"dnsName": "localhost.localdomain",
"assetName": "localhost.localdomain",
"netbiosName": null,
"timeZone": "IST",
"biosDescription": null,
"lastBoot": null,
"totalMemory": 5806,
"cpuCount": null,
"lastLoggedOnUser": "root",
"hwUUID": "422a2b16-4c8b-588a-a20c-c1851ad7e376",
"biosSerialNumber": "VMware-42 2a 2b 16 4c 8b 58 8a-
a2 0c c1 85 1a d7 e3 76",
"biosAssetTag": "No Asset Tag",
"isContainerHost": false,
"operatingSystem": {
"osName": "The CentOS Project CentOS 7 (1810)",
"fullName": "The CentOS Project CentOS 7
(1810)",
"category": "Linux / Server",
"category1": "Linux",
"category2": "Server",
"productName": "CentOS",
"publisher": "The CentOS Project",
"edition": null,
"marketVersion": "7",
"version": "1810",
"update": null,
"architecture": null,

26
 Assets Host Data APIs
Get Host Details of All Assets

"lifecycle": {
"gaDate": "2018-12-03T00:00:00.000Z",
"eolDate": "2020-12-31T00:00:00.000Z",
"eosDate": "2024-06-30T00:00:00.000Z",
"stage": "EOL",
"lifeCycleConfidence": "Exact",
"eolSupportStage": "Full updates",
"eosSupportStage": "Maintenance Updates"
},
"taxonomy": {
"id": null,
"name": "Linux / Server",
"category1": "Linux",
"category2": "Server"
},
"productUrl":
"https://www.centos.org/,https://en.wikipedia.org/wiki/CentOS,",
"productFamily": null,
"installDate": null
},
"hardware": {
"fullName": "VMware VMware Virtual Platform
VMware Virtual Platform",
"category": "Virtualized / Virtual Machine",
"category1": "Virtualized",
"category2": "Virtual Machine",
"manufacturer": "VMware",
"productName": "VMware Virtual Platform",
"model": "VMware Virtual Platform",
"lifecycle": {
"introDate": null,
"gaDate": null,
"eosDate": null,
"obsoleteDate": null,
"stage": "Unknown",
"lifeCycleConfidence": " "
},
"taxonomy": {
"id": null,
"name": "Virtualized / Virtual Machine",
"category1": "Virtualized",
"category2": "Virtual Machine"
},
"productUrl":
"https://www.linuxjournal.com/article/3458,,",
"productFamily": null

27
 Assets Host Data APIs
Get Host Details of All Assets

},
"userAccountListData": null,
"openPortListData": {
"openPort": [
{
"port": 709,
"description": "",
"protocol": "UDP",
"detectedService": "portmap/rpcbind",
"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},
{
"port": 50000,
"description": "",
"protocol": "TCP",
"detectedService":
"IBM_DB2_Universal_Database",
"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},
{
"port": 6000,
"description": "",
"protocol": "TCP",
"detectedService": "x11",
"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},
{
"port": 22,
"description": "",
"protocol": "TCP",
"detectedService": "ssh",
"firstFound": "2020-11-
25T12:46:41.000Z",
"lastUpdated": "2020-11-
25T12:46:41.000Z"
},
{

28
 Assets Host Data APIs
Get Host Details of All Assets

"port": 3389,
"description": "",
"protocol": "TCP",
"detectedService": null,
"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},
{
"port": 111,
"description": "",
"protocol": "UDP",
"detectedService": "rpc_udp",
"firstFound": "2020-11-
25T12:46:42.000Z",
"lastUpdated": "2020-11-
25T12:46:42.000Z"
},
{
"port": 111,
"description": "",
"protocol": "TCP",
"detectedService": "rpc",
"firstFound": "2020-11-
25T12:46:41.000Z",
"lastUpdated": "2020-11-
25T12:46:41.000Z"
}
]
},
"volumeListData": {
"volume": [
{
"name": "tmpfs",
"free": 2737078272,
"size": 3043934208
},
{
"name": "/dev/mapper/centos-home",
"free": 18629619712,
"size": 18700304384
},
{
"name": "devtmpfs",
"free": 3026444288,

29
 Assets Host Data APIs
Get Host Details of All Assets

"size": 3026444288
},
{
"name": "/dev/mapper/centos-root",
"free": 19672580096,
"size": 38304645120
},
{
"name": "/dev/sda1",
"free": 876040192,
"size": 1063256064
}
]
},
"networkInterfaceListData": {
"networkInterface": [
{
"hostname": "localhost.localdomain",
"addressIpV4": "192.168.122.1",
"addressIpV6": null,
"macAddress": "52:54:00:77:e1:71",
"interfaceName": "virbr0",
"dnsAddress": null,
"gatewayAddress": "",
"manufacturer": null,
"macVendorIntroDate": null,
"addresses": null
},
{
"hostname": "localhost.localdomain",
"addressIpV4": "10.115.110.95",
"addressIpV6":
"fe80:0:0:0:250:56ff:feaa:e2da",
"macAddress": "00:50:56:aa:e2:da",
"interfaceName": "ens192",
"dnsAddress": null,
"gatewayAddress": "",
"manufacturer": "VMware",
"macVendorIntroDate": 946944000000,
"addresses": null
}
]
},
"softwareListData": {
"software": [
{

30
 Assets Host Data APIs
Get Host Details of All Assets

"id": -5698725809391962787,
"fullName": "Python 2.7.5 64-Bit",
"softwareType": "Application",
"isIgnored": false,
"ignoredReason": null,
"category": "Application Development /
Programming Languages",
"category1": "Application Development",
"category2": "Programming Languages",
"productName": "Python",
"component": null,
"publisher": "Python",
"edition": null,
"marketVersion": "2",
"version": "2.7",
"update": "2.7.5",
"architecture": "64-Bit",
"installDate": "2020-03-
27T16:11:47.000Z",
"installPath": null,
"lastUpdated": "2020-11-
25T12:46:46.000Z",
"lastUseDate": null,
"language": null,
"formerlyKnownAs": null,
"isPackage": false,
"isPackageComponent": false,
"packageName": null,
"productUrl":
"https://en.wikipedia.org/wiki/History_of_Python,,",
"lifecycle": {
"gaDate": "2010-07-03T00:00:00.000Z",
"eolDate": "2020-01-
01T00:00:00.000Z",
"eosDate": "2020-01-
01T00:00:00.000Z",
"stage": "EOL/EOS",
"lifeCycleConfidence": "Exact",
"eolSupportStage": "End-of-life",
"eosSupportStage": "End-of-life"
},
"supportStageDesc": "Python's policy is
to drop support major versions once they reach their end of life",
"license": {
"category": "Open Source",
"subcategory": "Python License

31
 Assets Host Data APIs
Get Host Details of All Assets

(Python-2.0)"
},
"authorization": "Authorized"
},
{
"id": 9136542396418607016,
"fullName": "OpenBSD OpenSSH Server
7.4p1",
"softwareType": "Application",
"isIgnored": false,
"ignoredReason": null,
"category": "Networking / Access
Software",
"category1": "Networking",
"category2": "Access Software",
"productName": "OpenSSH",
"component": "Server",
"publisher": "OpenBSD",
"edition": null,
"marketVersion": "7",
"version": "7.4",
"update": "7.4p1",
"architecture": null,
"installDate": "2020-03-
05T14:23:53.000Z",
"installPath": null,
"lastUpdated": "2020-11-
25T12:46:53.000Z",
"lastUseDate": null,
"language": null,
"formerlyKnownAs": "OpenBSD Secure
Shell",
"isPackage": true,
"isPackageComponent": false,
"packageName": null,
"productUrl":
"https://en.wikipedia.org/wiki/OpenSSH,,",
"lifecycle": {
"gaDate": "2016-12-19T00:00:00.000Z",
"eolDate": null,
"eosDate": null,
"stage": "EOL",
"lifeCycleConfidence": "Calculated",
"eolSupportStage": " ",
"eosSupportStage": " "
},

32
 Assets Host Data APIs
Get Host Details of All Assets

"supportStageDesc": null,
"license": {
"category": "Open Source",
"subcategory": "BSD 2-Clause License
(FreeBSD/Simplified)"
},
"authorization": "Authorized"
}
]
},
"provider": null,
"cloudProvider": null,
"agent": null,
"sensor": {
"activatedForModules": [
"VM"
],
"pendingActivationForModules": [],
"lastVMScan": 1606306572000,
"lastComplianceScan": 0,
"lastFullScan": 1606306572000
},
"container": null,
"inventory": {
"source": "IP",
"created": 1606308565000,
"lastUpdated": 1617703353000
},
"activity": null,
"tagList": {
"tag": [
{
"tagId": 14151022,
"tagName": "static split",
"foregroundColor": 0,
"backgroundColor": -65536,
"businessImpact": null,
"criticalityScore": 3
}
]
},
"serviceList": null,
"lastLocation": null,
"criticality": {
"score": 2,
"isDefault": true,

33
 Assets Host Data APIs
Get Host Details of All Assets

"lastUpdated": "2021-06-30T09:43:27.000Z"
},
"processor": null
}
]
}
}

34
 Assets Host Data APIs
Import Business Information Metadata

Import Business Information Metadata

API affected rest/2.0/update/am/asset/business/metadata
rest/2.0/upsert/am/businessapp/metadata
New or Updated APIs New

With this release, we’ve added support to import asset business metadata and business
app metadata using v2 APIs. This support is available for CSAM Paid and Trial
subscriptions only. You’ll be able to import maximum 250 records in the single request.

Sample - Import Business App Metadata

These parameters are mandatory in the request body to import business app metadata:
businessAppId, name, created, and lastUpdated
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/upsert/am/businessap
p/metadata' < business-app-metadata.json

Request body:
{
"data": [
{
"businessAppId": "2fc86c650a0a0bb4003698b5331640df",
"name": "Banking Service",
"businessCriticality": "1 - Most Critical",
"status": "Installed",
"environment": "Production",
"usedFor": "Production",
"created": 1620643264000,
"lastUpdated": 1620653309000,
"operationalStatus": "Installed",
"ownedBy": "Joey Bolick",
"managedBy": "Byron Fortuna",
"supportedBy": "John Doe",
"supportGroup": "IT Operations"
},
{
"businessAppId": "5678f28f933a31003b4bb095e57ffb88",
"name": "Customer Support Portal",
"businessCriticality": "3 - Low",
"status": "Installed",
"environment": "Development",
"usedFor": "Development",

35
 Assets Host Data APIs
Import Business Information Metadata

"created": 1620643264000,
"lastUpdated": 1620653309000,
"operationalStatus": "Installed",
"ownedBy": "Joey Bolick",
"managedBy": "Byron Fortuna",
"supportedBy": "John Doe",
"supportGroup": "Application Security"
}
]
}
Response:
{
"requestId": "8e9b3fd5-bb89-4666-a472-4bc5758335a2",
"responseMessage": "Business app metadata imported successfully",
"responseCode": "SUCCESS",
"failedIds": null
}

Note: If the business app data for the associated business app id of the asset is not present
then the association of that business app with the asset will not happen but the rest of all
the data will get updated.

Sample - Import Asset Business Metadata

API 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/update/am/asset/busi
ness/metadata' < asset-business-metadata.json

Request Body
{
"data": [
{
"qualysAssetId": "6420613",
"metadata": {
"operationalStatus": "Operational",
"environment": "Production",
"company": "ACME US",
"department": "IT Operations",
"ownedBy": "Joey Bolick",
"managedBy": "Byron Fortuna",
"supportedBy": "John Doe",
"supportGroup": "IT Operations",
"businessAppIds": ["2fc86c650a0a0bb4003698b5331640df"],
"assignedLocation": {
"name": "401 Biscayne St, Miami FL",
"street": "401 Biscayne St, Miami FL",
"city": "Miami",

36
 Assets Host Data APIs
Import Business Information Metadata

"state": "FL",
"country": "USA"
}
}
},
{
"qualysAssetId": "6286688",
"metadata": {
"operationalStatus": "Repair",
"environment": "Development",
"company": "ACME Italy",
"department": "Customer Support",
"ownedBy": "Joey Bolick",
"managedBy": "Byron Fortuna",
"supportedBy": "John Doe",
"supportGroup": "Customer Support",
"businessAppIds":
["27d415a8c0a8000b00ffe2ab0f82e8d2","5678f28f933a31003b4bb095e57ffb88"],
"assignedLocation": {
"name": "123 Plazuela Roma Italy",
"street": "123 Plazuela Roma Italy",
"city": "Roma",
"state": "Roma",
"country": "Italy"
}
}
}
]
}

Response:
{
"requestId": "9017b662-01c9-4e74-97c5-eae6d29f08ed",
"responseMessage": "Asset metadata imported successfully",
"responseCode": "SUCCESS",
"failedIds": null
}

37
 Assets Host Data APIs
Import Business Information Metadata

38
 Import Business Information Metadata
Import Business App Metadata

Import Business Information Metadata

Use these API functions to import asset business metadata and business app metadata
using v2 APIs. This support is available for CSAM Paid and Trial subscriptions only. You’ll
be able to import maximum 250 records in the single request.

Permissions
- User must have the GAV/CSAM module and the "App API Enabled" option enabled for
that role.
Note:

1) For updating business information metadata, you need to send new request with
desired attributes to be changed along with all the attributes. If you don’t include an
attribute in the request, the value of the attribute will be override with NULL value.
2) If you have changed business app metadata then you need to explicitly send a request
to change the asset business metadata for those assets.

Import Business App Metadata

Import business app metadata as per input criteria in the request body.
rest/2.0/update/am/asset/business/metadata
[POST]

Input Parameters for Business Information Metadata

Attribute Description Character Limit
name (Required to import business app 255
metadata) Name of the business
application
businessAppid (Required to import business app 32
metadata) Unique ID of the business
application
operationalStatus Operational status of the application 255
businessCriticality How critical the application is to the 255
business.
environment Designates how this business app is 255
used, e.g. Production, Staging, QA, etc
ownedBy Person who owns the application from 255
the business side.
managedBy Person who owns the application from 255
the IT side

39
 Import Business Information Metadata
Import Business App Metadata

supportedBy User supporting the business 255

application
supportGroup Group supporting the business 255
application
created (Required to import business app NA
metadata) Business app created date
lastUpdated (Required to import business app NA
metadata) Business app last updated
date

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/upsert/am/businessap
p/metadata' < business-app-metadata.json

Request body:
{
"data": [
{
"businessAppId": "2fc86c650a0a0bb4003698b5331640df",
"name": "Banking Service",
"businessCriticality": "1 - Most Critical",
"status": "Installed",
"environment": "Production",
"usedFor": "Production",
"created": 1620643264000,
"lastUpdated": 1620653309000,
"operationalStatus": "Installed",
"ownedBy": "Joey Bolick",
"managedBy": "Byron Fortuna",
"supportedBy": "John Doe",
"supportGroup": "IT Operations"
},
{
"businessAppId": "5678f28f933a31003b4bb095e57ffb88",
"name": "Customer Support Portal",
"businessCriticality": "3 - Low",
"status": "Installed",
"environment": "Development",
"usedFor": "Development",
"created": 1620643264000,
"lastUpdated": 1620653309000,
"operationalStatus": "Installed",

40
 Import Business Information Metadata
Import Asset Business Metadata

"ownedBy": "Joey Bolick",

"managedBy": "Byron Fortuna",
"supportedBy": "John Doe",
"supportGroup": "Application Security"
}
]
}
Response:
{
"requestId": "8e9b3fd5-bb89-4666-a472-4bc5758335a2",
"responseMessage": "Business app metadata imported successfully",
"responseCode": "SUCCESS",
"failedIds": null
}

Note: If the business app data for the associated business app id of the asset is not present
then the association of that business app with the asset will not happen but the rest of all
the data will get updated.

Import Asset Business Metadata

Import asset business metadata as per input criteria in the request body.
rest/2.0/upsert/am/businessapp/metadata
[POST]

Input Parameters
Attribute Description Character Limit
qualysAssetId (Required to import asset business NA
metadata) Unique ID of the asset
businessAppIds Unique IDs of the business application NA
operationalStatus Operational status of the asset 128
environment The environment this asset is 128
connected to / runs on
ownedBy Person who owns the asset from the 255
business side.
managedBy Person who owns the asset from the IT 255
side
supportedBy User supporting the asset 255
supportGroup Group supporting the asset 255
company The Company or Subsidiary 128

41
 Import Business Information Metadata
Import Asset Business Metadata

department The departmental organizational 128

structure
assignedLocation.name The assigned location name, for 255
example building name
assignedLocation.citty The assigned location's city 128
assignedLocation.state The assigned location's state 128
assignedLocation.country The assigned location's country 128

API 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/update/am/asset/busi
ness/metadata' < asset-business-metadata.json

Request Body
{
"data": [
{
"qualysAssetId": "6420613",
"metadata": {
"operationalStatus": "Operational",
"environment": "Production",
"company": "ACME US",
"department": "IT Operations",
"ownedBy": "Joey Bolick",
"managedBy": "Byron Fortuna",
"supportedBy": "John Doe",
"supportGroup": "IT Operations",
"businessAppIds": ["2fc86c650a0a0bb4003698b5331640df"],
"assignedLocation": {
"name": "401 Biscayne St, Miami FL",
"street": "401 Biscayne St, Miami FL",
"city": "Miami",
"state": "FL",
"country": "USA"
}
}
},
{
"qualysAssetId": "6286688",
"metadata": {
"operationalStatus": "Repair",
"environment": "Development",
"company": "ACME Italy",
"department": "Customer Support",
"ownedBy": "Joey Bolick",
"managedBy": "Byron Fortuna",
"supportedBy": "John Doe",

42
 Import Business Information Metadata
Import Asset Business Metadata

"supportGroup": "Customer Support",

"businessAppIds":
["27d415a8c0a8000b00ffe2ab0f82e8d2","5678f28f933a31003b4bb095e57ffb88"],
"assignedLocation": {
"name": "123 Plazuela Roma Italy",
"street": "123 Plazuela Roma Italy",
"city": "Roma",
"state": "Roma",
"country": "Italy"
}
}
}
]
}

Response:
{
"requestId": "9017b662-01c9-4e74-97c5-eae6d29f08ed",
"responseMessage": "Asset metadata imported successfully",
"responseCode": "SUCCESS",
"failedIds": null
}

43
 Import Business Information Metadata
Import Asset Business Metadata

44
 Appendix
Error Messages

Appendix
This appendix describes the types of error messages returned from GAV/CSAM API
requests, list of operators with supported attributes.

Error Messages

Error Code Description

400 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.
403 Forbidden 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.
404 Not found The server has not found anything matching the
Request
416 Requested Range Not Please provide a Page Size value less than the max
Satisfiable page size limit set.
500 Failure 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 Values
NUMERIC_OPERATORS EQUALS, IN, NOT_EQUALS, GREATER, LESSER,
GREATER_THAN_EQUAL, and LESS_THAN_EQUAL
NUMERIC_AND_NOT_E EQUALS, IN, GREATER, LESSER, GREATER_THAN_EQUAL,
QUAL_OPERATORS LESS_THAN_EQUAL
STRING_OPERATORS CONTAINS, IN, EQUALS, and NOT_EQUALS
STRING_AND_NOT_EQ CONTAINS, IN, and EQUALS
UAL_OPERATORS

45
 Appendix
Supported Operators

Operator Values
DATE_OPERATORS EQUALS, NOT_EQUALS, GREATER, LESSER, GREATER_THAN_EQUAL,
and LESS_THAN_EQUAL
BOOLEAN_OPERATORS EQUALS
ENUM_OPERATORS EQUALS, NOT_EQUALS, and IN
UUID_OPERATORS EQUALS and IN
IP_OPERATORS EQUALS and IN

Following table lists different attributes with supported operators:

Attribute Operator
Asset Attributes
asset.assetID NUMERIC_OPERATORS
asset.name STRING_OPERATORS
asset.created DATE_OPERATORS
asset.lastUpdated DATE_OPERATORS
asset.type ENUM_OPERATORS
asset.lastLoggedOnUser STRING_OPERATORS
asset.totalMemory NUMERIC_OPERATORS
asset.timezone STRING_OPERATORS
asset.trackingMethod ENUM_OPERATORS
asset.lastBoot DATE_OPERATORS
asset.netbiosName STRING_OPERATORS
asset.hostID NUMERIC_OPERATORS
asset.isContainerHost BOOLEAN_OPERATORS
asset.biosAssetTag STRING_OPERATORS
asset.biosDescription STRING_OPERATORS
asset.biosHardwareUUID STRING_OPERATORS
asset.biosSerialNumber STRING_OPERATORS
asset.agentID UUID_OPERATORS
asset.criticalityScore NUMERIC_OPERATORS
accounts.username STRING_OPERATORS
provider ENUM_OPERATORS
isDockerHost BOOLEAN_OPERATORS
Inventory Attributes
inventory.source STRING_OPERATORS

46
 Appendix
Supported Operators

Attribute Operator
inventory.created DATE_OPERATORS
inventory.lastUpdated DATE_OPERATORS
Processor Attributes
processors STRING_AND_NOT_EQUAL_OPERATORS
processors.speed NUMERIC_AND_NOT_EQUAL_OPERATORS
Container Attributes
container.noOfContainers NUMERIC_AND_NOT_EQUAL_OPERATORS
container.noOfImages NUMERIC_AND_NOT_EQUAL_OPERATORS
container.version STRING_AND_NOT_EQUAL_OPERATORS
Interface Attributes
interfaces.hostname STRING_AND_NOT_EQUAL_OPERATORS
interfaces.interfaceName STRING_AND_NOT_EQUAL_OPERATORS
interfaces.macAddress STRING_AND_NOT_EQUAL_OPERATORS
interfaces.manufacturer STRING_AND_NOT_EQUAL_OPERATORS
interfaces.address IP_OPERATORS
interfaces.dnsAddress IP_OPERATORS
interfaces.gatewayAddress IP_OPERATORS
Open Ports Attributes
openPorts.description STRING_AND_NOT_EQUAL_OPERATORS
openPorts.detectedService STRING_AND_NOT_EQUAL_OPERATORS
openPorts.protocol STRING_AND_NOT_EQUAL_OPERATORS
openPorts.port NUMERIC_AND_NOT_EQUAL_OPERATORS
openPorts.firstFound DATE_OPERATORS
openPorts.lastUpdated DATE_OPERATORS
Services Attributes
services.description STRING_AND_NOT_EQUAL_OPERATORS
services.name STRING_AND_NOT_EQUAL_OPERATORS
services.status STRING_AND_NOT_EQUAL_OPERATORS
Sensors Attributes
sensors.lastComplianceScan DATE_OPERATORS
sensors.lastFullScan DATE_OPERATORS
sensors.lastVmScan DATE_OPERATORS
Tag Attributes
tags.name EQUALS, IN, CONTAINS

47
 Appendix
Supported Operators

Attribute Operator
tags.businessImpact EQUALS, IN, CONTAINS
Volume Attributes
volumes.free NUMERIC_AND_NOT_EQUAL_OPERATORS
volumes.size NUMERIC_AND_NOT_EQUAL_OPERATORS
volumes.name STRING_AND_NOT_EQUAL_OPERATORS
Agent Attributes
agent.version NUMERIC_AND_NOT_EQUAL_OPERATORS
agent.connectedFrom IP_OPERATORS
agent.errorStatus BOOLEAN_OPERATORS
agent.lastActivity DATE_OPERATORS
agent.lastCheckedIn DATE_OPERATORS
Hardware Attributes
hardware STRING_OPERATORS
hardware.category STRING_OPERATORS
hardware.category1 STRING_OPERATORS
hardware.category2 STRING_OPERATORS
hardware.manufacturer STRING_OPERATORS
hardware.model STRING_OPERATORS
hardware.product STRING_OPERATORS
hardware.lifecycle.stage STRING_OPERATORS
hardware.lifecycle.eos DATE_OPERATORS
hardware.lifecycle.ga DATE_OPERATORS
hardware.lifecycle.intro DATE_OPERATORS
hardware.lifecycle.obs DATE_OPERATORS
Software Attributes
software.architecture STRING_OPERATORS
software.category STRING_OPERATORS
software.category1 STRING_OPERATORS
software.category2 STRING_OPERATORS
software.component STRING_OPERATORS
software.edition STRING_OPERATORS
software.marketVersion STRING_OPERATORS
software.name STRING_OPERATORS
software.product STRING_OPERATORS

48
 Appendix
Supported Operators

Attribute Operator
software.publisher STRING_OPERATORS
software.supportStage STRING_OPERATORS
software.version STRING_OPERATORS
software.update STRING_OPERATORS
software.isPackage BOOLEAN_OPERATORS
software.isPackageComponent BOOLEAN_OPERATORS
software.license.category STRING_OPERATORS
software.license.subcategory STRING_OPERATORS
software.lifecycle.stage STRING_OPERATORS
software.installDate DATE_OPERATORS
software.lastUseDate DATE_OPERATORS
software.lastUpdated DATE_OPERATORS
software.lifecycle.eol DATE_OPERATORS
software.lifecycle.eos DATE_OPERATORS
software.lifecycle.ga DATE_OPERATORS
software.authorization EQUALS, NOT_EQUALS, and IN
Operating System Attributes
operatingSystem STRING_OPERATORS
operatingSystem.category STRING_OPERATORS
operatingSystem.category1 STRING_OPERATORS
operatingSystem.category2 STRING_OPERATORS
operatingSystem.architecture STRING_OPERATORS
operatingSystem.component STRING_OPERATORS
operatingSystem.edition STRING_OPERATORS
operatingSystem.marketVersion STRING_OPERATORS
operatingSystem.name STRING_OPERATORS
operatingSystem.publisher STRING_OPERATORS
operatingSystem.version STRING_OPERATORS
operatingSystem.update STRING_OPERATORS
operatingSystem.lifecycle.stage STRING_OPERATORS
operatingSystem.installDate DATE_OPERATORS
operatingSystem.lifecycle.eol DATE_OPERATORS
operatingSystem.lifecycle.eos DATE_OPERATORS
operatingSystem.lifecycle.ga DATE_OPERATORS

49
 Appendix
Supported Operators

Attribute Operator
AWS Attributes
aws.ec2.availabilityZone STRING_OPERATORS
aws.ec2.instanceType STRING_OPERATORS
aws.ec2.publicDNS STRING_OPERATORS
aws.ec2.privateDNS STRING_OPERATORS
aws.ec2.accountId STRING_OPERATORS
aws.ec2.imageId STRING_OPERATORS
aws.ec2.instanceId STRING_OPERATORS
aws.ec2.instanceState STRING_OPERATORS
aws.ec2.region.code STRING_OPERATORS
aws.ec2.subnetId STRING_OPERATORS
aws.ec2.vpcId STRING_OPERATORS
aws.ec2.hostname STRING_OPERATORS
aws.ec2.privateIpAddress IP_OPERATORS
aws.ec2.publicIpAddress IP_OPERATORS
aws.tags.key STRING_OPERATORS
aws.tags.value STRING_OPERATORS
aws.ec2.spotInstance STRING_OPERATORS
aws.ec2.launchDate DATE_OPERATORS
aws.ec2.hasAgent BOOLEAN_OPERATORS
Azure Attributes
azure.vm.imageOffer STRING_OPERATORS
azure.vm.imagePublisher STRING_OPERATORS
azure.vm.imageVersion STRING_OPERATORS
azure.vm.name STRING_OPERATORS
azure.vm.size STRING_OPERATORS
azure.vm.vmId STRING_OPERATORS
azure.vm.resourceGroupName STRING_OPERATORS
azure.vm.state STRING_OPERATORS
azure.vm.subnet STRING_OPERATORS
azure.vm.subscriptionId STRING_OPERATORS
azure.vm.location STRING_OPERATORS
azure.vm.platform STRING_OPERATORS
azure.vm.macAddress STRING_OPERATORS

50
 Appendix
Supported Operators

Attribute Operator
azure.tags.value STRING_OPERATORS
azure.tags.name STRING_OPERATORS
azure.vm.privateIpAddress IP_OPERATORS
azure.vm.publicIpAddress IP_OPERATORS
azure.vm.hasAgent BOOLEAN_OPERATORS
GCP Attributes
gcp.compute.hostname STRING_OPERATORS
gcp.compute.instanceId STRING_OPERATORS
gcp.compute.machineType STRING_OPERATORS
gcp.compute.network STRING_OPERATORS
gcp.compute.projectId STRING_OPERATORS
gcp.compute.projectNumber STRING_OPERATORS
gcp.compute.macAddress STRING_OPERATORS
gcp.compute.state STRING_OPERATORS
gcp.compute.zone STRING_OPERATORS
gcp.compute.privateIpAddres IP_OPERATORS
gcp.compute.publicIpAddress IP_OPERATORS
Geo IP Attributes
asset.lastLocation STRING_OPERATORS
asset.lastLocation.city STRING_OPERATORS
asset.lastLocation.country STRING_OPERATORS
asset.lastLocation.continent STRING_OPERATORS
asset.lastLocation.postal STRING_OPERATORS
asset.lastLocation.state STRING_OPERATORS
Business Information Attributes
asset.org.company STRING_OPERATORS
asset.org.department STRING_OPERATORS
asset.ownedBy STRING_OPERATORS
asset.managedBy STRING_OPERATORS
asset.supportedBy STRING_OPERATORS
asset.supportGroup STRING_OPERATORS
asset.environment STRING_OPERATORS
asset.operationalStatus STRING_OPERATORS
asset.assignedLocation.name STRING_OPERATORS

51
 Appendix
Supported Operators

Attribute Operator
asset.assignedLocation.city STRING_OPERATORS
asset.assignedLocation.state STRING_OPERATORS
asset.assignedLocation.country STRING_OPERATORS
businessApp.name STRING_OPERATORS
businessApp.id STRING_OPERATORS
businessApp.businessCriticality STRING_OPERATORS
businessApp.ownedBy STRING_OPERATORS
businessApp.supportGroup STRING_OPERATORS
businessApp.operationalStatus STRING_OPERATORS
businessApp.environment STRING_OPERATORS
businessApp.managedBy STRING_OPERATORS
businessApp.supportedBy STRING_OPERATORS

Note: Following tokens are available only for CSAM License Subscriber:
hardware.lifecycle.stage, hardware.lifecycle.eos, hardware.lifecycle.ga,
hardware.lifecycle.intro, hardware.lifecycle.obs,
software.authorization, 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, and operatingSystem.lifecycle.stage

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:

52
 Appendix
Supported Operators

{
"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>
<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>

53
 Appendix
Supported Operators

<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>
</Criteria>
<Criteria field="hardware.category" operator="EQUALS">
<value>Notebook</value>
</Criteria>
</filters>
<operation>AND</operation>
</FilterRequest>

54