Release 10.31 API

December 08, 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 /hostids
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.
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.

The following new input parameters have been introduced:

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. Earlier, this was a mandatory parameter.

statusChangedSince={value}

Optional

Date

Specify the date to resolve the hosts with posture modified (failed or passed ) on or after the specified date.

Here is the API sample request and response:

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)

The following new input parameters have been introduced:

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 criticality 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 5, 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 criticality labels. Possible values are: UNDEFINED MINIMAL MEDIUM SERIOUS CRITICAL URGENT When executing this API, you can use either the criticalityLabels parameter or criticalityValues parameter, but not both parameters simultaneously.

Here are sample API requests and responses:

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
    }
]

Issues Addressed

The following reported and notable customer API issues have been fixed in this release:

Component/Category	Application	Description
VM - Users API	Vulnerability Management	When the users tried to import user preferences, using the API endpoint /api/2.0/fo/user_prefs/, within a subscription, daily trouble ticket updates and Scanner Appliance heartbeat check notifications were not updated after import. The display of an input parameter USER_PREFS in the error message was creating confusion. Relevant code changes have been made to fix the issue.
VM - API General	Vulnerability Management	When the users attempted to update the tracking method, for the API endpoint /api/2.0/fo/asset/host/, between IP and DNS for multiple comma-separated host IDs, they encountered error 1905 stating, 'Parameter ids has an invalid value (ID must be a positive integer).' However, updates for a single host ID were successful. Relevant code changes have been made to fix the issue. Users can now update the tracking method for both single and multiple comma-separated host IDs.
PC - API	Policy Compliance	When the users executed the API endpoint /api/2.0/fo/compliance/exception/ for the exception list control, an error code 999 was displayed in the exception list output. Relevant code changes were been made to fix the issue.