Release 10.31 API
November 29, 2024
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.
We have implemented versioning for APIs. For more information on API versioning, refer to the Introducing API Versioning: A Strategic Upgrade for Enhanced Stability and Control for API Integrations blog.
Qualys Policy Compliance (PC)
Resolve Host IDs
New or Updated API | Updated |
API Endpoint (Deprecation Timeline- May 2025) |
/pcrs/2.0/posture /hosts |
API Endpoint (New Version) |
/pcrs/3.0/posture /hostids |
Method | GET |
DTD or XSD changes | No |
With this release, introducing a new version (/pcrs/3.0/posture/hostids) of this API to resolve hostIDs :
- With posture modified (failed or passed ) on or after the specified date.
- Scanned on or after the specified date.
- For all the policies or specific policies in your subscription without any limit on the number of policies.
The new version of the API can be executed only by the Manager user.
Input ParametersInput Parameters
Parameter Name |
Required/ Optional |
Data Type |
Description |
policyID={value} | Optional | String |
The ID of the policy for which you want to resolve hosts. You can specify a single policy or multiple/all the policies in your subscription using comma-separated values. If no Policy ID is provided in the API request, then the hosts are resolved for all the policies in the subscription. |
statusChangedSince={value} | Optional | Date | Specify the date to resolve the hosts with posture modified (failed or passed ) on or after the specified date. |
Sample-Resolve HostIDs based on the specific posture modification dateSample-Resolve HostIDs based on the specific posture modification date
API Request
curl -X GET https://<qualys_base_url>/pcrs/3.0/posture/hostids?policyId=<Policy_ID>& statusChangedSince= <Date>
-H "accept: */*" -H "Authorization: "
API Response
[
{
"policyId": <Policy_ID>,
"subscriptionId": <Subscription_id>,
"hostIds": [
<Host_IDs>,
<Host_IDs>,
<Host_IDs>,
]
}
]
Get Posture Info
New or Updated API | Updated |
API Endpoint (Deprecation Timeline- May 2025) |
/pcrs/2.0/posture/postureInfo |
API Endpoint (New Version) |
/pcrs/3.0/posture/postureInfo |
Method | POST |
DTD or XSD changes | No |
With this release, introducing a new version (/pcrs/3.0/posture/postureInfo) of this API. This new version enables you to:
- View cloud metadata in the API response.
- Retrieve the posture information based on the current posture status (passe/failed/error).
- Retrieve the posture information based on the previous status (passed/failed/error) of the posture.
- Retrieve posture information based on the following criticality categories:
- UNDEFINED (0)
- MINIMAL (1)
- MEDIUM (2)
- SERIOUS (3)
- CRITICAL (4)
- URGENT (5)
Input ParametersInput Parameters
Parameter Name |
Required/ Optional |
Data Type |
Description |
cloudMetaDataRequired={0|1} | Optional | Integer |
This parameter allows you to retrieve cloud metadata. Specify "1" to retrieve cloud metadata information in the API response. Specify "0" to not retrieve cloud metadata information in the API response. Cloud metadata is returned as null in the response for the postures that do not have cloud metadata. |
status={value} | Optional | String | This parameter lets you retrieve posture information based on the current posture status. Possible values are Passed, Failed, and Error. You can provide multiple comma-separated values. |
previousStatus={value} | Optional | String | This parameter lets you retrieve posture information based on the previous posture status. Possible values are Passed, Failed, and Error. You can provide a single value at a time. |
criticalityValues={0|1|2|3|4|5} | Optional | String |
This parameter lets you retrieve posture information based on the critcality levels. You can provide multiple comma-separated values. When set to 0, posture information with criticality level UNDEFINED is retrieved. When set to 1, posture information with criticality level MINIMAL is retrieved. When set to 2, posture information with criticality level MEDIUM is retrieved. When set to 3, posture information with criticality level SERIOUS is retrieved. When set to 4, posture information with criticality level CRITICAL is retrieved. When set to 6, posture information with criticality level URGENT is retrieved. When executing this API, you can use either the criticalityLabels parameter or criticalityValues parameter, but not both parameters simultaneously. |
criticalityLabels={value} | Optional | String |
This parameter lets you retrieve posture information based on the critcality levels. You can provide multiple comma-separated crticality labels. Possible values are:
When executing this API, you can use either the criticalityLabels parameter or criticalityValues parameter, but not both parameters simultaneously. |
Sample-Retrieve Cloud MetadataSample-Retrieve Cloud Metadata
API Request
curl -X POST "https://<qualys_base_url>/pcrs/3.0/posture/postureInfo?evidenceRequired=0&compressionRequired=0&cloudMetaDataRequired=1" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type:application/json" -d "[{\"policyId\":\"<POLICY ID>\",\"subscriptionId\":\"<SUBSCRIPTION_ID>\",\"hostIds\":[\"<HOST ID1>\",\"<HOST ID2>\"]}]"
API Response
[ {
"id": 19029070,
"instance": "os",
"policyId": 1438626,
"policyTitle": "CPS -Test",
"netBios": "INSTANCE-20240223-173020",
"controlId": 1131,
"controlStatement": "Status of the 'Trivial File Transfer Protocol (TFTP)' service",
"rationale": "The 'TFTP' service is both a command and TCP protocol that is normally used only for booting diskless workstations, getting or saving network component configuration files, or as a 'kickstart' type host configuration from a network-based template. The connection initiation and data transfer is all done in clear text without requiring credentials of any kind. As a malicious user with a 'sniffer' running on the network, could easily capture the data and/or reproduce the same operation, simply by knowing the name of the file(s) and the source address(es), this process should be disabled/restricted according to the needs of the business.",
"remediation": "Review \"/etc/inetd.conf\" file to check whether tftp service's configuration in line with business needs and organization's security policies.\n\nExample: To disable the tftp service,\n\nRemove or comment out any tftp lines in /etc/inetd.conf: \n# tftp stream tcp nowait root internal",
"category": "Services",
"subCategory": "Guidelines/Procedures (Services)",
"controlReference": null,
"technologyId": 346,
"status": "Passed",
"previousStatus": "Passed",
"firstFailDate": "",
"lastFailDate": "",
"firstPassDate": "2024-10-04T09:47:33Z",
"lastPassDate": "2024-10-04T09:47:33Z",
"postureModifiedDate": "2024-10-04T09:47:33Z",
"lastEvaluatedDate": "2024-10-04T09:47:33Z",
"created": "2024-11-12T06:20:49Z",
"hostId": 4980343,
"ip": "34.133.253.84",
"trackingMethod": "AGENT",
"os": "Debian Linux 11.1",
"osCpe": null,
"domainName": "179.87.224.35.bc.googleusercontent.com",
"dns": "179.87.224.35.bc.googleusercontent.com",
"qgHostid": "4bd9e81e-12f8-4d8f-a51d-c475131a55b8",
"networkId": 0,
"networkName": "Global Default Network",
"complianceLastScanDate": "2024-10-04T09:39:21Z",
"customerUuid": "93f7ad53-1590-e3ac-83cd-322b91180e13",
"customerId": "1337821",
"assetId": 42078290,
"technology": {
"id": 346,
"name": "Debian GNU/Linux 11.x"
},
"criticality": {
"label": "SERIOUS",
"value": 3
},
"evidence": {
"expectedValues": "\nDisabled (0)\n------------ OR ------------\nEnabled (1)\n------------ OR ------------\nSetting not found\n------------ OR ------------\nFile not found",
"currentValues": [
"File not found"
],
"actualValues": null,
"directoryFimUdc": null,
"lastUpdated": "2024-10-04T09:39:21Z",
"extendedEvidence": "Row 1:\n"
},
"causeOfFailure": null,
"userDefinedAttributesList": null,
"currentDataSizeKB": "2.98",
"totalDataSizeKB": "27.09",
"currentBatch": 1,
"totalBatches": 1,
"cloudMetaData": {
"cloudProvider": "GCP",
"cloudService": "Compute Engine",
"cloudResourceId": "2182777093928348127",
"cloudResourceType": "Instance",
"cloudAccountId": "175127636344",
"cloudImageId": null,
"cloudResourceMetadata": "{'Public IP Address':'35.224.87.179', 'Private IP Address':'10.128.0.27', 'Machine Type':'e2-medium', 'Zone':'null', 'ProjectId':'qlys-devqa-qweb', 'State':'RUNNING', 'Network':'N/A', 'MAC Address':'null'}"
},
"CLOUD_RESOURCE_ID": "2182777093928348127"
}
]
Sample-Retrieve Posture Information Based on Current Posture Status: PassedSample-Retrieve Posture Information Based on Current Posture Status: Passed
API Request
curl -X POST "https://<qualys_base_url>/pcrs/3.0/posture/postureInfo?evidenceRequired=0&compressionRequired=0&status=Passed" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type:application/json" -d "[{\"policyId\":\"<POLICY ID>\",\"subscriptionId\":\"<SUBSCRIPTION_ID>\",\"hostIds\":[\"<HOST ID1>\",\"<HOST ID2>\"]}]"
API Response
[ {
"id": 19029069,
"instance": "os",
"policyId": 1438626,
"policyTitle": "CPS -Test",
"netBios": "INSTANCE-20240223-173020",
"controlId": 1130,
"controlStatement": "Status of the 'telnet' service (Unix/Linux)",
"rationale": "'Telnet' is both a user command and a TCP/IP protocol, most commonly used for accessing remote computers via a command line interface (CLI) on tcp port 23. Telnet streams are transmitted in clear text including any uid/password input, so if a telnet session is used for privileged communication(s)/host configuration purposes, the entire session is susceptible to interception by eavesdroppers on the network. As this can lead to the session being hijacked or replayed by malicious users, this process should be disabled/restricted according to the needs of the business.",
"remediation": "Edit the file '/etc/inetd.conf' and add or comment the 'telnet' entry according to the business needs or organization's security policies.",
"category": "OS Security Settings",
"subCategory": "Performance Monitoring (All OSI Layers)",
"controlReference": null,
"technologyId": 346,
"status": "Passed",
"previousStatus": "Passed",
"firstFailDate": "",
"lastFailDate": "",
"firstPassDate": "2024-10-04T09:47:33Z",
"lastPassDate": "2024-10-04T09:47:33Z",
"postureModifiedDate": "2024-10-04T09:47:33Z",
"lastEvaluatedDate": "2024-10-04T09:47:33Z",
"created": "2024-11-12T06:32:08Z",
"hostId": 4980343,
"ip": "34.133.253.84",
"trackingMethod": "AGENT",
"os": "Debian Linux 11.1",
"osCpe": null,
"domainName": "179.87.224.35.bc.googleusercontent.com",
"dns": "179.87.224.35.bc.googleusercontent.com",
"qgHostid": "4bd9e81e-12f8-4d8f-a51d-c475131a55b8",
"networkId": 0,
"networkName": "Global Default Network",
"complianceLastScanDate": "2024-10-04T09:39:21Z",
"customerUuid": "93f7ad53-1590-e3ac-83cd-322b91180e13",
"customerId": "1337821",
"assetId": 42078290,
"technology": {
"id": 346,
"name": "Debian GNU/Linux 11.x"
},
"criticality": {
"label": "SERIOUS",
"value": 3
},
"evidence": {
"expectedValues": "\nDisabled (0)\n------------ OR ------------\nEnabled (1)\n------------ OR ------------\nSetting not found\n------------ OR ------------\nFile not found",
"currentValues": [
"File not found"
],
"actualValues": null,
"directoryFimUdc": null,
"lastUpdated": "2024-10-04T09:39:21Z",
"extendedEvidence": "Row 1:\n"
},
"causeOfFailure": null,
"userDefinedAttributesList": null,
"currentDataSizeKB": "2.35",
"totalDataSizeKB": "20.78",
"currentBatch": 1,
"totalBatches": 1,
"CLOUD_RESOURCE_ID": "2182777093928348127"
}
]
Sample-Retrieve Posture Information Based on the Previous Status: PassedSample-Retrieve Posture Information Based on the Previous Status: Passed
API Request
curl -X POST "https://<qualys_base_url>/pcrs/3.0/posture/postureInfo?evidenceRequired=0&compressionRequired=0&previousStatus=Passed" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type:application/json" -d "[{\"policyId\":\"<POLICY ID>\",\"subscriptionId\":\"<SUBSCRIPTION_ID>\",\"hostIds\":[\"<HOST ID1>\",\"<HOST ID2>\"]}]"
API Response
[ {
"id": 19029069,
"instance": "os",
"policyId": 1438626,
"policyTitle": "CPS -Test",
"netBios": "INSTANCE-20240223-173020",
"controlId": 1130,
"controlStatement": "Status of the 'telnet' service (Unix/Linux)",
"rationale": "'Telnet' is both a user command and a TCP/IP protocol, most commonly used for accessing remote computers via a command line interface (CLI) on tcp port 23. Telnet streams are transmitted in clear text including any uid/password input, so if a telnet session is used for privileged communication(s)/host configuration purposes, the entire session is susceptible to interception by eavesdroppers on the network. As this can lead to the session being hijacked or replayed by malicious users, this process should be disabled/restricted according to the needs of the business.",
"remediation": "Edit the file '/etc/inetd.conf' and add or comment the 'telnet' entry according to the business needs or organization's security policies.",
"category": "OS Security Settings",
"subCategory": "Performance Monitoring (All OSI Layers)",
"controlReference": null,
"technologyId": 346,
"status": "Passed",
"previousStatus": "Passed",
"firstFailDate": "",
"lastFailDate": "",
"firstPassDate": "2024-10-04T09:47:33Z",
"lastPassDate": "2024-10-04T09:47:33Z",
"postureModifiedDate": "2024-10-04T09:47:33Z",
"lastEvaluatedDate": "2024-10-04T09:47:33Z",
"created": "2024-11-12T06:32:08Z",
"hostId": 4980343,
"ip": "34.133.253.84",
"trackingMethod": "AGENT",
"os": "Debian Linux 11.1",
"osCpe": null,
"domainName": "179.87.224.35.bc.googleusercontent.com",
"dns": "179.87.224.35.bc.googleusercontent.com",
"qgHostid": "4bd9e81e-12f8-4d8f-a51d-c475131a55b8",
"networkId": 0,
"networkName": "Global Default Network",
"complianceLastScanDate": "2024-10-04T09:39:21Z",
"customerUuid": "93f7ad53-1590-e3ac-83cd-322b91180e13",
"customerId": "1337821",
"assetId": 42078290,
"technology": {
"id": 346,
"name": "Debian GNU/Linux 11.x"
},
"criticality": {
"label": "SERIOUS",
"value": 3
},
"evidence": {
"expectedValues": "\nDisabled (0)\n------------ OR ------------\nEnabled (1)\n------------ OR ------------\nSetting not found\n------------ OR ------------\nFile not found",
"currentValues": [
"File not found"
],
"actualValues": null,
"directoryFimUdc": null,
"lastUpdated": "2024-10-04T09:39:21Z",
"extendedEvidence": "Row 1:\n"
},
"causeOfFailure": null,
"userDefinedAttributesList": null,
"currentDataSizeKB": "2.35",
"totalDataSizeKB": "20.78",
"currentBatch": 1,
"totalBatches": 1,
"CLOUD_RESOURCE_ID": "2182777093928348127"
}
]
Sample-Retrieve Posture Information Based on Criticality Value:2Sample-Retrieve Posture Information Based on Criticality Value:2
API Request
curl -X POST "https://<qualys_base_url>/pcrs/3.0/posture/postureInfo?evidenceRequired=0&compressionRequired=0& criticalityValues=2" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type:application/json" -d "[{\"policyId\":\"<POLICY ID>\",\"subscriptionId\":\"<SUBSCRIPTION_ID>\",\"hostIds\":[\"<HOST ID1>\",\"<HOST ID2>\"]}]"
API Response
[
{
"id": 20244862,
"instance": "os",
"policyId": 1455059,
"policyTitle": "WINDOWS_IP_TRACKED_IPV4_POLICY_AG",
"netBios": "SYS_25_25_25_25",
"controlId": 1161,
"controlStatement": "Status of the 'Fax' service",
"rationale": "The Microsoft 'Fax' service provides a software-based facsimile service that can take system documents and send these out to a fax-recipient via a hardware modem and analog phone line. (One reported public exploit uses the Windows Picture and Fax Viewer (SHIMGVW.DLL) to execute code arbitrarily.) As this transfer capability can potentially compromise sensitive system documents, by transmitting information to unauthorized recipients and can be activated remotely, this capability should be restricted/set according to the needs of the business.",
"remediation": "Remove or disable the Fax (fax) service.",
"category": "OS Security Settings",
"subCategory": "Performance Monitoring (All OSI Layers)",
"controlReference": null,
"technologyId": 21,
"status": "Passed",
"previousStatus": "Passed",
"firstFailDate": "",
"lastFailDate": "",
"firstPassDate": "2024-11-06T09:17:38Z",
"lastPassDate": "2024-11-06T09:20:57Z",
"postureModifiedDate": "2024-11-06T09:17:38Z",
"lastEvaluatedDate": "2024-11-06T09:20:57Z",
"created": "2024-11-12T07:38:05Z",
"hostId": 6396343,
"ip": "25.25.25.25",
"trackingMethod": "IP",
"os": null,
"osCpe": "cpe:/o:microsoft:windows_server_2008:r2::enterprise_x64:",
"domainName": "25-25-25-25.bogus.tld",
"dns": "25-25-25-25.bogus.tld",
"qgHostid": null,
"networkId": 0,
"networkName": "Global Default Network",
"complianceLastScanDate": "2024-11-06T09:12:22Z",
"customerUuid": "e57ba830-15e4-714c-8243-6d1740d3577e",
"customerId": "2309240",
"assetId": 50622236,
"technology": {
"id": 21,
"name": "Windows 2008 Server"
},
"criticality": {
"label": "MEDIUM",
"value": 2
},
"evidence": {
"expectedValues": "\nAutomatic (2)\n------------ OR ------------\nAutomatic (Delayed Start) (21)\n------------ OR ------------\nManual (3)\n------------ OR ------------\nKey not found\n------------ OR ------------\nDisabled (4)",
"currentValues": [
"Key not found"
],
"actualValues": null,
"directoryFimUdc": null,
"lastUpdated": "2024-11-06T09:12:22Z",
"extendedEvidence": "Row 1:Service Name,Registry Key,Start Value,Delayed Start\nRow 2:Fax,HKLM\\SYSTEM\\CurrentControlSet\\Services\\Fax,,\n"
},
"causeOfFailure": null,
"userDefinedAttributesList": null,
"currentDataSizeKB": "2.34",
"totalDataSizeKB": "7.61",
"currentBatch": 1,
"totalBatches": 1,
"CLOUD_RESOURCE_ID": null
}
]
Sample-Retrieve Posture Information based on Criticality Label-MEDIUMSample-Retrieve Posture Information based on Criticality Label-MEDIUM
API Request
curl -X POST "https://<qualys_base_url>/pcrs/3.0/posture/postureInfo?evidenceRequired=0&compressionRequired=0& criticalityLabels= MEDIUM" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type:application/json" -d "[{\"policyId\":\"<POLICY ID>\",\"subscriptionId\":\"<SUBSCRIPTION_ID>\",\"hostIds\":[\"<HOST ID1>\",\"<HOST ID2>\"]}]"
API Respone
[
{
"id": 20244862,
"instance": "os",
"policyId": 1455059,
"policyTitle": "WINDOWS_IP_TRACKED_IPV4_POLICY_AG",
"netBios": "SYS_25_25_25_25",
"controlId": 1161,
"controlStatement": "Status of the 'Fax' service",
"rationale": "The Microsoft 'Fax' service provides a software-based facsimile service that can take system documents and send these out to a fax-recipient via a hardware modem and analog phone line. (One reported public exploit uses the Windows Picture and Fax Viewer (SHIMGVW.DLL) to execute code arbitrarily.) As this transfer capability can potentially compromise sensitive system documents, by transmitting information to unauthorized recipients and can be activated remotely, this capability should be restricted/set according to the needs of the business.",
"remediation": "Remove or disable the Fax (fax) service.",
"category": "OS Security Settings",
"subCategory": "Performance Monitoring (All OSI Layers)",
"controlReference": null,
"technologyId": 21,
"status": "Passed",
"previousStatus": "Passed",
"firstFailDate": "",
"lastFailDate": "",
"firstPassDate": "2024-11-06T09:17:38Z",
"lastPassDate": "2024-11-06T09:20:57Z",
"postureModifiedDate": "2024-11-06T09:17:38Z",
"lastEvaluatedDate": "2024-11-06T09:20:57Z",
"created": "2024-11-12T07:38:05Z",
"hostId": 6396343,
"ip": "25.25.25.25",
"trackingMethod": "IP",
"os": null,
"osCpe": "cpe:/o:microsoft:windows_server_2008:r2::enterprise_x64:",
"domainName": "25-25-25-25.bogus.tld",
"dns": "25-25-25-25.bogus.tld",
"qgHostid": null,
"networkId": 0,
"networkName": "Global Default Network",
"complianceLastScanDate": "2024-11-06T09:12:22Z",
"customerUuid": "e57ba830-15e4-714c-8243-6d1740d3577e",
"customerId": "2309240",
"assetId": 50622236,
"technology": {
"id": 21,
"name": "Windows 2008 Server"
},
"criticality": {
"label": "MEDIUM",
"value": 2
},
"evidence": {
"expectedValues": "\nAutomatic (2)\n------------ OR ------------\nAutomatic (Delayed Start) (21)\n------------ OR ------------\nManual (3)\n------------ OR ------------\nKey not found\n------------ OR ------------\nDisabled (4)",
"currentValues": [
"Key not found"
],
"actualValues": null,
"directoryFimUdc": null,
"lastUpdated": "2024-11-06T09:12:22Z",
"extendedEvidence": "Row 1:Service Name,Registry Key,Start Value,Delayed Start\nRow 2:Fax,HKLM\\SYSTEM\\CurrentControlSet\\Services\\Fax,,\n"
},
"causeOfFailure": null,
"userDefinedAttributesList": null,
"currentDataSizeKB": "2.34",
"totalDataSizeKB": "7.61",
"currentBatch": 1,
"totalBatches": 1,
"CLOUD_RESOURCE_ID": null
}
]