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
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.
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/
| 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.
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.
{
"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"
}
}
]
}
}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.
API Versioning
We have implemented API versioning, a strategic change that empowers our customers with greater control, better stability, and smoother integration processes.
Benefits of API versioning
- Extended testing window: Under the new strategy, customers benefit from a more extended time window than the current 30-day period to experiment with new APIs, allowing for thorough testing and integration, ensuring that new functionalities can be seamlessly incorporated into your existing systems.
- Dual API access: To facilitate a smooth transition and minimize disruptions, customers have access to both the new and old versions of an API concurrently for conducting comprehensive tests against the new API while maintaining the production environment with the old API. This reduces the risk of integration issues and ensures that customers can confidently and systematically adopt new features.
- Enhanced agility for Qualys: This new strategy empowers Qualys with increased agility in API releases. By streamlining the versioning process and providing clear frameworks for updates and EOS, we can rapidly adapt to changing technological landscapes and customer needs.
To ensure continued support and access to the latest features, we encourage all customers using the endpoints listed here to upgrade to the latest version of the API endpoints within the specified timelines. This will help you avoid potential disruptions and ensure alignment with ongoing enhancements from Qualys.
To support your understanding, definitions of key terms such as End-of-Support(EOS) and End-of-life (EOL) are also included, explaining the lifecycle of each endpoint.
End-of-Support (EOS):
End-of-Support for an API version signifies the point at which Qualys will no longer actively maintain or enhance that specific version. While the API may continue to function, it will not receive new features, performance improvements, or security updates. This phase is intended to provide a grace period for API consumers to migrate to newer versions.
Implications of End-of-Support
- No New Features: The API version will not receive any further functional enhancements or new capabilities.
- Limited Bug Fixes: Critical security vulnerabilities may be addressed on a case-by-case basis, but general bug fixes for non-critical issues will stop.
- No Performance Improvements: Optimization efforts focus solely on newer API versions.
- Reduced Support Channels: Technical support for issues related to this specific API version may become limited, and users are strongly recommended to upgrade.
- No Guarantees of Reliability: While the API may remain operational, Qualys offers no guarantees regarding its continued reliability beyond the EOS date.
End-of-Life (EOL)
End-of-Life for an API version is the final stage where the API version is officially retired and will be completely decommissioned. After the EOL date, the API will no longer be available, and any calls to it will result in errors. This marks the complete discontinuation of service for that specific API version.
Implications of End-of-Life
- API Decommissioning: The API endpoint for this version is shut down and will no longer accept requests.
- Complete Service Stoppage: All functionalities provided by this API version will cease to exist.
- Error Responses: Any attempt to call the EOL API results in HTTP error codes, such as 404 Not Found or 410 Gone, or similar error messages.
- No Support: All forms of support, documentation, and resources related to this API version will be discontinued.