{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":46058,"path":"security-management/vulnerability-response/qualys-rest-messages.md","title":"Qualys REST messages","bundle":null,"doc_type":null,"release":"australia","body":"\n# Qualys REST messages\n\nQualys REST messages are used to make calls to the Qualys API.\n\nStarting with version 12.9.2 of Qualys, you can authenticate Qualys REST messages using either **Basic Authentication** or **OAuth**. By default, the **Authentication method** integration parameter is configured to use **Basic Authentication**.\n\nSetting the **Authentication method** parameter to **OAuth** only prevents the integration from applying **Basic Authentication** credentials to REST messages. It doesn't configure **OAuth** authentication.\n\nFor information on setting up **OAuth** authentication, see [Configure OAuth authentication for Qualys REST messages](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/security-management/vulnerability-response/configure-qualys-oauth-authentication.md).\n\n## Supported authentication sources\n\nThe Qualys Vulnerability Integration doesn't use **Connection &amp; Credential** aliases for authentication. **Basic Authentication** and **OAuth** credentials are configured directly on the integration and the REST message, as described in this topic.\n\nThe integration is tested and supported using **Basic Authentication** or **OAuth** credentials issued by Qualys. Authenticating with an OAuth or OIDC token issued by a third-party or customer-managed identity provider isn't an officially validated configuration for this integration. For authentication requirements specific to your Qualys account, contact Qualys support.\n\n## Qualys Host Detection REST message\n\nThe Qualys Host Detection REST message makes the initial call to the Host List Detection API for the Qualys Host Detection Integration.\n\n<table id=\"table_v2g_x1q_dt\"><thead><tr><th>\n\nParameter Name\n\n</th><th>\n\nValue\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\naction\n\n</td><td>\n\nlist\n\n</td><td>\n\nIndicates the type of operation requested. Required parameter. Changes aren’t required.\n\n</td></tr><tr><td>\n\noutput\\_format\n\n</td><td>\n\nXML\n\n</td><td>\n\nSets the format of the report returned by Qualys. The various scripts and transforms assume XML, so changes to the value aren’t recommended.\n\n</td></tr><tr><td>\n\ndetection\\_processed\\_after\n\n</td><td>\n\n$\\{lastScanDate\\}\n\n</td><td>\n\nShows only detections whose detection status changed after a certain date and time. For detections that have never changed, the date is applied to the last detection date.\n\n</td></tr><tr><td>\n\ntruncation\\_limit\n\n</td><td>\n\n500\n\n</td><td>\n\nThe number of hosts to retrieve data from, according to request. This parameter is used for pagination purposes.\n\n The default value is 500, but larger or smaller values can be used. Don’t set at less than 100 since it significantly increases system load.\n\n Smaller values require more calls to the Qualys API and larger values result in larger result sets to process and potential data retrieval/processing timeouts.\n\n</td></tr><tr><td>\n\nstatus\n\n</td><td>\n\nNew, Fixed, Active, Reopened\n\n</td><td>\n\nDetection statuses to retrieve from Qualys. The default is to retrieve all statuses. For large data pulls \\(often the initial pull of data\\), it can be beneficial to exclude Fixed statuses from this list.\n\n It’s important to include the Fixed status when updating vulnerabilities already in the system.\n\n</td></tr></tbody>\n</table>## Qualys Host Detection Integration REST message\n\nThe Qualys Host Detection – Standard REST message retrieves host detection data from Qualys.\n\nStarting with v12.21.0 of Qualys Integration for Security Operations and v30.3.0 of Unified Security Exposure Management, the API version has been updated to version 5.0.\n\n|Parameter Name|Value|Description|\n|--------------|-----|-----------|\n|vuln\\_detection\\_source|1|Returns the vulnerability detection source in the response.|\n|show\\_tags|$\\{showTag\\}|Displays asset tags associated with each host in the XML output.|\n|show\\_cloud\\_tags|1|Returns cloud provider tags for each scanned host asset in the output.|\n|host\\_metadata|all|Lists all assets \\(cloud and non-cloud\\) and the metadata output applicable for cloud assets.|\n|action|$\\{action\\}|Action to list host detections.|\n|output\\_format|$\\{outputFormat\\}|Specifies the format of the host detection list output.|\n|truncation\\_limit|$\\{truncationLimit\\}|Specifies the maximum number of host records processed per request.|\n|status|$\\{status\\}|Returns only hosts with one or more of these status values.|\n|severities|$\\{severities\\}|Returns only detection records that have the specified severities.|\n\n## Qualys Comprehensive Host Detection Integration REST message\n\nThe Qualys Host Detection - Standard REST message retrieves host detection data from Qualys.\n\nStarting with v12.21.0 of Qualys Integration for Security Operations and v30.3.0 of Unified Security Exposure Management, the API version has been updated to version 5.0.\n\n|Parameter Name|Value|Description|\n|--------------|-----|-----------|\n|vuln\\_detection\\_source|1|Returns the vulnerability detection source in the response.|\n|show\\_tags|$\\{showTag\\}|Displays asset tags associated with each host in the XML output.|\n|show\\_cloud\\_tags|1|Returns cloud provider tags for each scanned host asset in the output.|\n|host\\_metadata|all|Lists all assets \\(cloud and non-cloud\\) and the metadata output applicable for cloud assets.|\n|action|$\\{action\\}|Action to list host detections.|\n|output\\_format|$\\{outputFormat\\}|Specifies the format of the host detection list output.|\n|truncation\\_limit|$\\{truncationLimit\\}|Specifies the maximum number of host records processed per request.|\n|status|$\\{status\\}|Returns only hosts with one or more of these status values.|\n|severities|$\\{severities\\}|Returns only detection records that have the specified severities.|\n\n## Qualys Host List Integration REST message\n\nThe Qualys Host Detection - Standard REST message retrieves host detection data from Qualys.\n\nStarting with v12.21.0 of Qualys Integration for Security Operations and v30.3.0 of Unified Security Exposure Management, the API version has been updated to version 5.0.\n\n|Parameter Name|Value|Description|\n|--------------|-----|-----------|\n|show\\_tags|$\\{showTag\\}|Displays asset tags associated with each host in the XML output.|\n|show\\_cloud\\_tags|1|Returns cloud provider tags for each scanned host asset in the output.|\n|host\\_metadata|all|Lists all assets \\(cloud and non-cloud\\) and the metadata output applicable for cloud assets.|\n|action|$\\{action\\}|Action to list host detections.|\n|truncation\\_limit|$\\{truncationLimit\\}|Specifies the maximum number of host records processed per request.|\n|details|$\\{status\\}|Specifies the requested amount of host information for each host to be returned in the response.|\n\n## Qualys Knowledge Base REST message\n\nThe Qualys Knowledge Base \\(Date Based\\) REST message retrieves vulnerability data from Qualys.\n\nStarting with v12.21.0 of Qualys Integration for Security Operations and v30.3.0 of Unified Security Exposure Management, the API version has been updated to version 5.0.\n\n|Parameter Name|Value|Description|\n|--------------|-----|-----------|\n|action|$\\{action\\}|Action to list host detections.|\n|details|$\\{status\\}|Specifies the requested amount of host information for each host to be returned in the response.|\n|last\\_modified\\_after|$\\{dateStart\\}|Filters the XML output to show only vulnerabilities last modified after a certain date and time.|\n|last\\_modified\\_before|$\\{dateEnd\\}|Filters the XML output to show only vulnerabilities last modified before a certain date and time.|\n\n## Qualys Knowledge Base \\(Backfill\\) REST message\n\nThe Qualys Knowledge Base \\(Backfill\\) REST message retrieves vulnerability backfill data from Qualys.\n\nStarting with v12.21.0 of Qualys Integration for Security Operations and v30.3.0 of Unified Security Exposure Management, the API version has been updated to version 5.0.\n\n|Parameter Name|Value|Description|\n|--------------|-----|-----------|\n|action|$\\{action\\}|Action to list host detections.|\n|details|$\\{status\\}|Specifies the requested amount of host information for each host to be returned in the response.|\n|ids|$\\{qids\\}|Filters the XML output to include only vulnerabilities that have QID numbers matching the QID numbers specified.|\n\n## Qualys host detection pagination REST message\n\nThe Host Detection Pagination REST message handles pagination requests to the Host Detection API.\n\nWhen the primary host detection runs, if the Qualys API provides a URL to fetch the next page of data, this REST message retrieves that additional data. This data is used by the Host Detection Pagination Handler.\n\nHost detection pagination REST is a specialized REST message and isn’t intended to be modified.\n\n## Qualys knowledge base \\(backfill\\) REST message\n\nThe Qualys Knowledge Base \\(Backfill\\) REST message retrieves Qualys knowledge base data based on the last modified timestamp of the vulnerability data for the Qualys Knowledge Base integration.\n\nChanges to the REST message method record impact the request made to Qualys to retrieve knowledge base information.\n\nThe following table shows the request parameters that are sent.\n\n<table id=\"table_v2g_x1q_du\"><thead><tr><th>\n\nParameter\n\n</th><th>\n\nValue\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\naction\n\n</td><td>\n\nlist\n\n</td><td>\n\nIndicates the type of operation being requested. Required parameter. Changes aren’t recommended.\n\n</td></tr><tr><td>\n\ndetails\n\n</td><td>\n\nAll\n\n</td><td>\n\nIndicates the level of detail shown for vulnerabilities retrieved.\n\n Safe to modify as needed.\n\n</td></tr><tr><td>\n\nids\n\n</td><td>\n\n$\\{qids\\}\n\n</td><td>\n\nSpecifies which QIDs to retrieve from Qualys.\n\n Referenced in code. Modifications aren’t recommended.\n\n</td></tr></tbody>\n</table>## Qualys knowledge base \\(date-based\\) REST message\n\nThe Qualys Knowledge Base \\(Date-Based\\) REST message is used to retrieve Qualys knowledge base data based on the last modified timestamp of the vulnerability data. This message is used by the Qualys Knowledge Base integration.\n\nChanges to the REST message method record impact the request made to Qualys to retrieve knowledge base information.\n\nThe following table shows the request parameters that are sent.\n\n<table id=\"table_v2g_x1q_dv\"><thead><tr><th>\n\nSource Field\n\n</th><th>\n\nTarget Field\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\naction\n\n</td><td>\n\nlist\n\n</td><td>\n\nIndicates the type of operation requested. Required parameter. Changes aren’t recommended.\n\n</td></tr><tr><td>\n\ndetails\n\n</td><td>\n\nAll\n\n</td><td>\n\nIndicates the level of detail shown for vulnerabilities retrieved. Safe to modify as needed.\n\n</td></tr><tr><td>\n\nlast\\_modified\\_after\n\n</td><td>\n\n$\\{dateStart\\}\n\n</td><td>\n\nIndicates when to start retrieving historical data. Used by code to determine both the start time and to assist with pagination.\n\n Modifications or removal isn’t recommended.\n\n</td></tr><tr><td>\n\nlast\\_modifiedbefore\n\n</td><td>\n\n$\\{dateEnd\\}\n\n</td><td>\n\nIndicates when to end retrieving historical data. Used by code to determine both the end time and to assist with pagination.\n\n Modifications or removal isn’t recommended.\n\n</td></tr></tbody>\n</table>## Qualys tickets REST message\n\nThe Qualys tickets REST message retrieves Qualys ticket information for the Qualys Ticket Integration. Changes to the REST message method record impact the requests made to Qualys to retrieve ticket information.\n\nThe table shows the request parameters that are sent.\n\n<table id=\"table_v2g_x1q_dw\"><thead><tr><th>\n\nParameter Name\n\n</th><th>\n\nValue\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nmodified\\_since\\_datetime\n\n</td><td>\n\n$\\{lastRunDatetime\\}\n\n</td><td>\n\nIndicates the last run date of the integration and the date after which to pull data.\n\n Used by code. Changes aren’t recommended.\n\n</td></tr><tr><td>\n\nsince\\_ticket\\_number\n\n</td><td>\n\n$\\{lastTicketNumber\\}\n\n</td><td>\n\nIndicates which ticket was last retrieved from Qualys.\n\n Used for pagination. Changes aren’t recommended.\n\n</td></tr><tr><td>\n\nshow\\_vuln\\_details\n\n</td><td>\n\n1\n\n</td><td>\n\nIndicates whether the vulnerability details are retrieved.\n\n</td></tr></tbody>\n</table>"}}