Release 4.4 API
January 06, 2025
Before understanding the API release highlights, learn more about the API server URL to be used in your API requests by referring to the Know Your Qualys API Server URL section. For this API Release Notes, <qualys_base_url> is mentioned in the sample API requests.
What's New?
Update in Data Retention Policy
To comply with data retention policies and regulations, we have restricted access to the data for up to 15 months. You now have access to data that is up to 15 months old. With the upcoming release, retrieval of data older than 15 months will no longer be possible. We recommend that you save any important data that is older than 15 months, if necessary.
The Impacted API are
- FIM Events APIs
- Fetch Events
- Get Event Count
- Ignored FIM Events APIs
- Fetch Ignored Events
- Get Ignored Events Count
- FIM Incidents APIs
- Fetch Events for an Incident
- Get Event Count for an Incident
FIM Events APIs
| New or Updated API | Updated |
| API Endpoint | /fim/v2/events/search /fim/v2/events/count |
| Method | POST |
| DTD or XSD changes | Not Applicable |
Ignored FIM Events APIs
| New or Updated API | Updated |
| API Endpoint | /fim/v2/events/ignore/search /fim/v2/events/ignore/count |
| Method | POST |
| DTD or XSD changes | Not Applicable |
FIM Incidents APIs
| New or Updated API | Updated |
| API Endpoint | /fim/v2/incidents/{incidentId}/events/search /fim/v2/incidents/{incidentId}/events/count |
| Method | POST |
| DTD or XSD changes | Not Applicable |
For example, even if you request an API to fetch data from the last four years, the response includes data from the last 15 months only. Refer to the following sample for API request and response for details.
Sample to fetch ignored events from the last 4 yearsSample to fetch ignored events from the last 4 years
API Request
curl -X POST
'<qualys_base_url>/fim/v2/events/ignore/search'
--header 'Authorization: Bearer <authToken>'
--header 'content-type: application/json'
--data-raw
'{
"filter":"dateTime:['2020-06-25T18:30:00.000Z'..'2024-02-20T18:29:59.999Z']"
}'
Response
[
{
"sortValues": [],
"data": {
"dateTime": "2023-09-21T00:27:11.774+0000",
"fullPath": "C:\\EventGenerator\\Incident-21092023_055729.fim",
"fileAttribute": null,
"ownerShip": null,
"registryPath": null,
"contentId": null,
"type": "File",
"platform": "WINDOWS",
"oldContent": null,
"contentStatus": null,
"oldRegistryValueType": null,
"newContent": null,
"ignoreDate": "2023-09-21",
"permissions": null,
"customerId": "c4efd662-1e31-f768-8387-c8bff1462d7d",
"action": "Create",
"id": "9acd0e94-de47-3d9b-b463-a0eb6092025e",
"class": "Disk",
"fileID": "0x8f2000080d0",
"group": null,
"severity": 3,
"trustStatus": null,
"fileCertificateHash": null,
"securitySettings": null,
"profiles": [
{
"name": "AutomationProfile",
"rules": [
{
"severity": 3,
"number": 1,
"name": "EventGenerator",
"description": "EventGenerator",
"section": {
"name": "AutomationSection",
"id": "72761eb0-082d-432f-8a2d-870dd89468fa"
},
"id": "97f0e305-d736-4b84-85f5-278588a273dc",
"type": "directory"
}
],
"id": "504bd892-ba00-4b01-8ad9-933d1aa8c8c0",
"type": "WINDOWS",
"category": {
"name": "PCI",
"id": "2dab5022-2fdd-11e7-93ae-92361f002671"
}
}
],
"baseline": false,
"registryName": null,
"changedAttributes": [
2
],
"processedTime": "2023-09-21T00:28:02.066+0000",
"actor": {
"process": "java.exe",
"auditUserName": null,
"auditUserID": null,
"processID": 5328,
"imagePath": "C:\\Program Files\\AdoptOpenJDK\\jdk-8.0.232.09-hotspot\\bin\\java.exe",
"procTitle": null,
"userName": "WIN1809FIM13\\Administrator",
"userID": "S-1-5-21-2870285161-1241506764-97586135-500"
},
"oldRegistryValueContent": null,
"newRegistryValueType": null,
"fileContentHashOld": null,
"size": {
"newSize": 0,
"oldSize": 0
},
"name": "Incident-21092023_055729.fim",
"fileContentHash": null,
"volumeID": "0x32139b02",
"reputationStatus": null,
"newRegistryValueContent": null,
"attributes": {
"newAttribute": [
"Normal"
],
"oldAttribute": null
},
"asset": {
"agentId": "d7121ee5-bdc3-43e8-8e4e-07b204f46e44",
"interfaces": [
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "10.115.105.179",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "2001:df1:f600:2469:1518:e5f1:c0d3:4fbb",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "2001:df1:f600:2469:5132:51f:b86c:3f0b",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "2001:df1:f600:2469:7116:ce88:237d:8c15",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "2001:df1:f600:2469:7915:c951:f95b:847e",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "2001:df1:f600:2469:add9:4df4:850c:3044",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "2001:df1:f600:2469:c89b:238:be89:22f1",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "2001:df1:f600:2469:d5e7:bc6d:8521:d328",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "2001:df1:f600:2469:dc4b:846c:21ef:f578",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "2001:df1:f600:2469:f43a:3376:6bf7:36d0",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
},
{
"hostname": "WIN1809FIM13",
"macAddress": "00:50:56:AA:8E:BF",
"address": "fe80:0:0:0:d5e7:bc6d:8521:d328",
"interfaceName": "Intel(R) 82574L Gigabit Network Connection"
}
],
"lastCheckedIn": "2023-09-20T02:46:48.196Z",
"created": "2021-03-25T14:37:55.407+00:00",
"hostId": null,
"operatingSystem": "Microsoft Windows 10 Pro 10.0.17763 64-bit N/A Build 17763",
"tags": [
"8383573"
],
"assetType": "HOST",
"system": {
"lastBoot": "2023-08-16T07:09:04.500Z"
},
"ec2": null,
"lastLoggedOnUser": "Administrator",
"netbiosName": "WIN1809FIM13",
"name": "Automation",
"agentVersion": "5.3.0.10",
"updated": "2021-06-29T12:13:51.821+00:00"
},
"incidentId": null
}
} ]
Support for OAuth 2.0 and OpenID Connect Authentication Standards
With this release, we have upgraded our API security by incorporating OAuth 2.0 and OpenID Connect for Qualys API authentication and authorization. When OpenID Connect API authentication is implemented along with OAuth 2.0, IdP is used for user authentication and JWT token generation for the Qualys API access.
Key Updates
- Seamless integration of OAuth 2.0 and OpenID Connect to enhance API authentication and authorization measures.
- Compatibility with current identity providers and authentication to facilitate a seamless integration experience.
- This authentication is supported by all Qualys APIs.
- It eliminates the need for users to provide a username and password. This streamlines Qualys API access by allowing users to use JWT tokens, bypassing the hassle associated with usernames and passwords.
Enable OpenID Connect API Authentication
This feature is not available by default. Contact Qualys support to enable it for your subscription. You must follow the onboarding process. This feature requires IdP.
Benefits
- Enhanced API security
OpenID Connect (OIDC) uses tokens to establish a user's identity and grant access.
- Standardized access control
OpenID Connect (OIDC) provides a standardized way to manage user identities and access control
- Centralized Authentication
By enabling IDP-initiated SSO, users can authenticate once through your organization’s Identity Provider (IDP) and gain access to all the necessary APIs without needing to log in again. This simplifies the user experience and reduces password fatigue, making access faster and more secure.
- Compliance and Security
Helps to meet compliance requirements by ensuring that user authentication processes adhere to established security protocols like SAML and OIDC.
Prerequisites
Public signing certificates for verifying the authenticity of SAML responses. Upto 3 certificates can be provided. The certificate must be in X.509 format (usuallyin .pem or .cer files).
- IdP Name
The name of the Identity Provider (IdP) being configured. This can be a customname or provided by the customer.
Example: "TestNameforIDP Qualys Internal" - Entity ID
The unique identifier for the customer’s IdP. Typically, this is a URN or URL that serves as the IdP’s primary identifier during OIDC communications.
Example: "https://example.com/idp" - Single Sign-On (SSO) URL
The URL where authentication requests will be sent. This is the endpoint where users are redirected to authenticate with the customer’s IdP.
Example: "https://example.com/login" - Single Logout (SLO) URL (if applicable)
The URL for handling logout requests. If you support Single Logout, this endpoint will manage the termination of sessions both at the IdP and within Qualys.
Example: "https://example.com/logout" - SSO Exit URL (optional)
The URL where users will be redirected after successful authentication.
- Certificates
Public signing certificates for verifying the authenticity of SAML responses. Upto 3 certificates can be provided. The certificate must be in X.509 format (usuallyin .pem or .cer files).
Onboarding Process
To start using OpenID Connect API authentication, the following onboarding process must be completed.
- Contact Qualys Support (www.qualys.com/support) to request OpenID Connect API authentication activation for your subscription. A CRM ticket is automatically created and is used as a reference and tracking for all discussions concerning the activation.
- Qualys Support replies to the ticket to share and request the required technical information used to enable OIDC. see the Prerequisites for the details.
- Upon receipt of the response, Qualys enables OpenID Connect API authentication support. This process takes approximately one week to complete.
Use OpenID Connect API Authentication
Once the onboarding process is complete and the OpenID Connect API authentication is enabled, you can begin using it. To start using it, you must first generate the JWT token and then use that token to execute the Qualys APIs. The following subsections provide API request and response samples for generating a JWT token and executing APIs using this token.
Sample API Request to Generate JWT Token for API Authentication and its sample responseSample API Request to Generate JWT Token for API Authentication and its sample response
The token generation URL may vary based on the IdP application you are using. The sample below illustrates the request and response for Okta.
API Request
curl --location ' https://qualys.oktapreview.com/oauth2/aus27sviwo8jbrP4T0h8/v1/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=password' --data-urlencode 'username=jdoe@qualysit.com' --data-urlencode 'password= ' --data-urlencode 'client_id=0oa27l586h672nMy90h8' --data-urlencode 'scope=openid profile'
Response
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": " ",
"scope": "openid profile",
"id_token": " "
}
Sample API Request to Execute API Using the above JWT Token and it's sample responseSample API Request to Execute API Using the above JWT Token and it's sample response
curl -X POST '<qualys_base_url>/fim/v3/incidents/search
--header 'Authorization: Bearer <access_token from above response>'
--header 'content-type: application/json'
--data-raw
'{
"filter":"status:CLOSED",
"sort":"[\{\"dateTime\":\"desc\"}
]'
Response
[
{
"sortValues": [
1728882000000
],
"data": {
"slaDurationKey": null,
"approvalDate": "2024-10-15T05:14:14.888+0000",
"approvalType": "MANUAL",
"markupStatus": "COMPLETED",
"type": "AUTOMATED",
"slaViolationDate": null,
"filterFromDate": "2024-10-14T05:00:00.000+0000",
"customerId": "25a14e60-80c1-4c25-8166-6653a4e2b094",
"ruleName": "test_4April",
"id": "486c1675-c752-4f5e-b34d-4b63774d252d",
"ruleId": "23db69b0-0876-48a2-bdf5-058913585bbb",
"approvalStatus": "APPROVED",
"marked": true,
"lastUpdatedBy": {
"date": 1728890505670,
"user": {
"name": "FIM Automation",
"id": "51fbdb4b-5fb5-fdf6-8141-5a7887ec557b"
}
},
"filterToDate": "2024-10-14T21:29:00.000+0000",
"assignDate": "2024-10-14T06:07:12.894+0000",
"changeType": "MANUAL",
"filters":
[
"dateTime: ['2024-10-14T05:00:00.000Z'..'
2024-10-14T21:29:00.000Z'] and (action:Create )"
],
"reviewedBy": {
"date": 1728969254876,
"user": {
"name": "FIM Automation",
"id": "51fbdb4b-5fb5-fdf6-8141-5a7887ec557b"
}
},
"reviewers": [
"john_doe",
"johndoe",
"johnsmith@qualys.com"
],
"slaDurationValue": 0,
"deleted": false,
"createdBy": {
"date": 1728886032875,
"user": {
"name": "FIM Automation",
"id": "51fbdb4b-5fb5-fdf6-8141-5a7887ec557b"
}
},
"slaRequired": false,
"name": "test_4April-20241014-060712",
"comment": "Events under this incident have been reviewed ",
"dispositionCategory": "PATCHING",
"status": "CLOSED"
}
}
]