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.

Sample: 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"

Here, 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) that you can use for authentication during GAV/CSAM calls. The token expires in 4 hours, and you must regenerate it 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: Bearer <token>”	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.

Option

Description

-X “POST”

The POST method is required for all GAV/CSAM API requests.

-H “Authorization: Bearer <token>”

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.

Sample

curl -X POST "https://gateway.qg1.apps.qualys.com/rest/2.0/search/am/asset" -H "Authorization: Bearer  "

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:

Sample - limit results

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&includeFields=operatingSystem,hardware"

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	domain	agent
lastLoggedOnUser	subdomain	agentId	netbiosName
whois	assetName	networkInterface	isp
biosAssetTag	openPort	asn	biosDescription
operatingSystem	customAttributes	biosSerialNumber	processor
container	sensor	cpuCount	service
dnsName	software	hardware	tag
hostId	timeZone	inventory	totalMemory
isContainerHost	userAccount	lastBoot	volume
criticality	businessApps	businessInformation	assignedLocation