Introduction to Global AssetView API Paradigm
This topic helps to understand Global AssetView paradigm.
Authentication
You must authenticate to the Qualys Enterprise TruRisk™ Platform using Qualys account credentials (user name and password) and get the JSON Web Token (JWT) before you can start using the Global AssetView 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 Global AssetView 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 AssetView calls. The token expires in 4 hours. You must regenerate the token to continue using the Global AssetView 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 Global AssetView 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 the options mentioned above and how they interact with each other.
curl -X POST "https://gateway.qg1.apps.qualys.com/am/v1/assets" -H "Authorization: Bearer <token>"
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 ResultsSample 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 "<qualys_base_url>/am/v1/assets/host/list?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.
- Public API having filters with '>', '<', '=', '>=', '<=' or '[]' operators works only when you use encodeURIComponent() function.
You can include the following fields to limit your results:
|
activity |
lastLocation |
|
address |
lastLoggedOnUser |
|
agent |
netbiosName |
|
agentId |
networkInterface |
|
assetName |
openPort |
|
biosAssetTag |
operatingSystem |
|
biosDescription |
processor |
|
biosSerialNumber |
provider |
|
cloudProvider |
sensor |
|
container |
service |
|
cpuCount |
software |
|
dnsName |
tag |
|
hardware |
timeZone |
|
hostId |
totalMemory |
|
inventory |
userAccount |
|
isContainerHost |
volume |
|
lastBoot |
|