Getting Started

Welcome to Qualys Custom Assessment and Remediation (CAR) APIs.

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 CAR 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 the latest news.

From Our Community

Join Our Community

API Notifications RSS Feeds

Introduction to CAR API 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 CAR APIs. Use the Qualys Authentication API to get the JWT.

ExampleExample

curl -X POST https://qualys_base_url/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 CAR 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 CAR API calls. The token expires in 4 hours. You must regenerate the token to continue using the CAR 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:The following Curl options are used according to different situations:

Option	Description
-X GET/POST	The GET method or the POST method is used as per requirement.
-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.
-H 'content-type: application/json'	Denotes that content is in JSON format.
-d @request.json	Provide a request.json file for parameter input.
--data-urlencode	Used to encode spaces and special characters in the URL/Parameter values.

The sample below shows a typical Curl request using the options mentioned above and how they interact with each other.

SampleSample

API Request

curl --location --request GET
'https://qualys_base_url/sm/v1/scripts/exportids=1
6515' \
--header 'Authorization: Bearer 
{}'

Response Code

HTTP response codes are messages sent by servers to indicate how they have handled a request. To know the HTTP response code you receive when you make API requests, refer to the Appendix.

Pagination Support for APIs

CAR APIs are designed to fetch 10 records per page by default. You can use pageSize and pageNumber paramaters to fetch more records.

ExampleExample

{
    "filter": "status:APPROVED",
    "pageSize": 30,
    "pageNumber": 0
}

Here, ’pageSize’ indicates the number of records that should be included in a page. ’pagenumber’ indicates the page number from which records must be fetched. For example, "pageNumber":0 would fetch results from page 1.

Fetching More than Ten Thousand Events

CAR APIs are designed to fetch less than 10,000 (9999 jobs or asset jobs) per page. However, you can use the ‘searchAfter’ parameter in order to fetch more than 10,000 records of assets, jobs, and asset jobs.

For this parameter to function accurately, use the ‘sort’ parameter to sort assets, script jobs, or asset jobs by using a filter that has unique values such as ID or name. Each asset/job/asset job is returned with an identifier called ‘sortValue’. In the subsequent API request, to fetch records beyond the current page size, provide the sortValue of an asset, job, or asset job to the searchAfter parameter to fetch records after the specific ID.

The ‘searchAfter’ parameter is supported for the following APIs:

sm/v2/jobs/search
sm/v2/assetjobs/search
sm/v1/assets/search

To understand this better, let’s consider the following scenario:

You have 15000 jobs in your account. The first API request will only return 9999 jobs. To get jobs beyond 9999, in a subsequent API request, provide the sortValue of the 9999th job in the searchAfter parameter. The second API request will fetch the remaining job starting from the 10000th job.

For better performance, it is recommended that you use smaller page sizes of 1000 to 2000 records.

Example:

You need to sort a list before you can use ’searchAfter’.

Step 1: Search events using the sort parameterStep 1: Search events using the sort parameter

URI: sm/v2/jobs/search

API Request

curl --location --request POST "https://qualys_base_url/sm/v2/jobs/search" \
--header "Authorization: Bearer <Bearer Token>" \
--header "Content-Type: application/json" \
--data-raw '{
    "filter": "script.name:Auto_script_22062022_074300047",
    "sort": [
        {"created.dateTime": "desc"}, {"id": "desc"}
        ],
    "pageSize": 10
}'

Request Body

{
    "filter": "script.name:Auto_script_22062022_074300047",
    "sort": [
        { "created.dateTime": "desc" },
        { "id": "desc" }
    ],
    "pageSize": 10
}

Response

{
  "errorCode": null,
  "message": null,
  "body": {
    "totalCount": 80,
    "list": [
      {
        "sortValues": [1674216006119, "25943"],
        "data": {
          "severity": 1,
          "test": false,
          "created": {
            "dateTime": 1674216006119
          },
          "executionType": "Automated",
          "schedulerId": "23f97a1f-76f4-4e85-a7c2-566f120874fc",
          "correlationUuid": "bbc62201-cec7-4f9d-8edc-37b55b7b55f4",
          "threshold": 250,
          "title": "Auto_script_22062022_074300047-1674216006",
          "platform": "WINDOWS",
          "updatedDateTime": 1674216006119,
          "scriptId": 19218,
          "customerUuid": "74c1bcdd-9bbb-e9dd-802a-65e2c579abc0",
          "isTest": false,
          "scriptType": "PowerShell",
          "id": "25943",
          "category": {
            "name": "Data Backup",
            "id": 1
          },
          "schedulerName": "dfdfdfd"
        }
      },
      {
        "sortValues": [1674201598656, "25934"],
        "data": {
          "severity": 1,
          "test": false,
          "created": {
            "dateTime": 1674201598656
          },
          "executionType": "Automated",
          "schedulerId": "23f97a1f-76f4-4e85-a7c2-566f120874fc",
          "correlationUuid": "07084308-5e75-4368-86b6-c4f2d7ad29af",
          "threshold": 250,
          "title": "Auto_script_22062022_074300047-1674201598",
          "platform": "WINDOWS",
          "updatedDateTime": 1674201598656,
          "scriptId": 19218,
          "customerUuid": "74c1bcdd-9bbb-e9dd-802a-65e2c579abc0",
          "isTest": false,
          "scriptType": "PowerShell",
          "id": "25934",
          "category": {
            "name": "Data Backup",
            "id": 1
          },
          "schedulerName": "dfdfdfd"
        }
      }
    ]
  }
}

Step 2: Take one of the sortValues from the above response and provide it as input for searchAfter. This will fetch Jobs after that particular sortValueStep 2: Take one of the sortValues from the above response and provide it as input for searchAfter. This will fetch Jobs after that particular sortValue

API Request

curl --location --request POST "https://qualys_base_url/sm/v2/jobs/search"
--header "Authorization: Bearer <Bearer Token>"
--header "Content-Type: application/json"
--data-raw '{
  "filter": "script.name:Auto_script_22062022_074300047",
  "sort": [
    {"created.dateTime": "desc"},
    {"id": "desc"}
  ],
  "pageSize": 10,
  "searchAfter": [
    1674129606914,
    "25890"
  ]
}'

Request Body:

{
   "filter":"script.name:Auto_script_22062022_074300047",
   "sort":"[
         {\"created.dateTime\":\"desc\"},
         {\"id\":\"desc\"}
         ]",
   "pageSize":10,
   "searchAfter":[1674129606914,"25890"]
}

Response

{
  "errorCode": null,
  "message": null,
  "body": {
    "totalCount": 80,
    "list": [
      {
        "sortValues": [1674115200508, "25875"],
        "data": {
          "severity": 1,
          "test": false,
          "created": { "dateTime": 1674115200508 },
          "executionType": "Automated",
          "schedulerId": "23f97a1f-76f4-4e85-a7c2-566f120874fc",
          "correlationUuid": "917e2217-e747-4ae5-8100-58a96ebb8386",
          "threshold": 250,
          "title": "Auto_script_22062022_074300047-1674115200",
          "platform": "WINDOWS",
          "updatedDateTime": 1674115200508,
          "scriptId": 19218,
          "customerUuid": "74c1bcdd-9bbb-e9dd-802a-65e2c579abc0",
          "isTest": false,
          "scriptType": "PowerShell",
          "id": "25875",
          "category": { "name": "Data Backup", "id": 1 },
          "schedulerName": "dfdfdfd"
        }
      },
      {
        "sortValues": [1674100804290, "25862"],
        "data": {
          "severity": 1,
          "test": false,
          "created": { "dateTime": 1674100804290 },
          "executionType": "Automated",
          "schedulerId": "23f97a1f-76f4-4e85-a7c2-566f120874fc",
          "correlationUuid": "534181ea-9644-4052-a654-546af75192ca",
          "threshold": 250,
          "title": "Auto_script_22062022_074300047-1674100804",
          "platform": "WINDOWS",
          "updatedDateTime": 1674100804290,
          "scriptId": 19218,
          "customerUuid": "74c1bcdd-9bbb-e9dd-802a-65e2c579abc0",
          "isTest": false,
          "scriptType": "PowerShell",
          "id": "25862",
          "category": { "name": "Data Backup", "id": 1 },
          "schedulerName": "dfdfdfd"
        }
      },
      {
        "sortValues": [1674086404113, "25859"],
        "data": {
          "severity": 1,
          "test": false,
          "created": { "dateTime": 1674086404113 },
          "executionType": "Automated",
          "schedulerId": "23f97a1f-76f4-4e85-a7c2-566f120874fc",
          "correlationUuid": "a89dce45-9b6c-4d11-8f69-2cf7777ca96a",
          "threshold": 250,
          "title": "Auto_script_22062022_074300047-1674086404",
          "platform": "WINDOWS",
          "updatedDateTime": 1674086404113,
          "scriptId": 19218,
          "customerUuid": "74c1bcdd-9bbb-e9dd-802a-65e2c579abc0",
          "isTest": false,
          "scriptType": "PowerShell",
          "id": "25859",
          "category": { "name": "Data Backup", "id": 1 },
          "schedulerName": "dfdfdfd"
        }
      },
      {
        "sortValues": [1674072000447, "25856"],
        "data": {
          "severity": 1,
          "test": false,
          "created": { "dateTime": 1674072000447 },
          "executionType": "Automated",
          "schedulerId": "23f97a1f-76f4-4e85-a7c2-566f120874fc",
          "correlationUuid": "ed6cb107-00d3-40f7-bc31-17661cd6c467",
          "threshold": 250,
          "title": "Auto_script_22062022_074300047-1674072000",
          "platform": "WINDOWS",
          "updatedDateTime": 1674072000447,
          "scriptId": 19218,
          "customerUuid": "74c1bcdd-9bbb-e9dd-802a-65e2c579abc0",
          "isTest": false,
          "scriptType": "PowerShell",
          "id": "25856",
          "category": { "name": "Data Backup", "id": 1 },
          "schedulerName": "dfdfdfd"
        }
      }
    ]
  }
}

Qualys API Framework

The Qualys CAR 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 CAR API, the module is: “sm”.
<object>	The module specific object.
<object_id>	(Optional) The module specific object ID, if appropriate.
<operation>	The request operation, such as count and search.

Qualys API Postman Collection

Interact with Qualys APIs using Postman. Instead of creating calls manually to send over the command line, you can use the Qualys Postman Collection to get started with Qualys APIs quickly.

Click here to view the steps involved

Qualys API 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 document uses as sample API gateway URL for Qualys platform (https://qualys_base_url) in sample API requests. Please replace this URL with the appropriate gateway URL for your account.