Introduction to GAV/CSAM API Paradigm
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. |
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.
When includeFields or excludeFields are specified, the response is filtered as follows:
- includeFields: Only the specified fields are returned with values. All other fields are returned as null.
- excludeFields: All fields are returned with values except the specified fields, which are returned as null.
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: Bearer <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.
Supported Fields
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 | assignedLocation |
| totalMemory | isContainerHost | userAccount | lastBoot |
| volume | criticality | businessApps | businessInformation |
Fetching Source Details for an Asset
To fetch source details for an asset, include `inventory` in the `includeFields` parameter. When specified, the API returns source information in two places within the response:
- `inventoryListData.inventory`
Displays the complete list of sources that discovered the asset. - `inventory`
Displays the asset source data.
Example:
{
"inventory": {
"source": "QAGENT",
"created": 1728017705000,
"lastUpdated": 1767028258000
},
"inventoryListData": {
"inventory": [
{
"source": "CAPS",
"created": 1738673171000,
"lastUpdated": 1738715633000
},
{
"source": "Cloud Agent",
"created": 1728017705000,
"lastUpdated": 1767028258000
}
]
}
}
In this example:
The `inventory` and `activity` fields show the asset source data. To view the list of all source details for the asset, we recommend referring to the `inventoryListData.inventory` field in the response.
To fetch the Software Component details, use the Software Component API.