Qualys REST messages

  • Release version: Washingtondc
  • Updated February 1, 2024
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Qualys REST Messages

    Qualys REST messages facilitate interactions with the Qualys API, allowing users to perform various operations related to host detection, knowledge base retrieval, and ticket management. Starting with version 12.9.2, users can opt for Basic Authentication or OAuth for authentication purposes, with Basic Auth pre-configured for the integration instance.

    Show full answer Show less

    Key Features

    • Qualys Host Detection REST Message: Initiates calls to the Host List Detection API. Key parameters include:
      • action: Specifies the operation type (required).
      • outputformat: Default is XML, recommended to remain unchanged.
      • detectionprocessedafter: Filters detections based on their status change date.
      • truncationlimit: Manages pagination, with a recommended minimum of 100.
      • status: Allows selection of specific detection statuses to retrieve.
    • Host Detection Pagination REST Message: Handles pagination requests to fetch additional data if provided by the Qualys API.
    • Qualys Knowledge Base (Backfill) REST Message: Retrieves knowledge base data using the last modified timestamp for vulnerabilities. Key parameters include:
      • action: Specifies operation type (required).
      • details: Level of detail for vulnerabilities, editable.
      • ids: Identifies specific QIDs to retrieve (modifications not recommended).
    • Qualys Knowledge Base (Date-Based) REST Message: Retrieves knowledge base data based on a defined date range. Parameters include:
      • action: Specifies operation type (required).
      • details: Level of detail for vulnerabilities, editable.
      • lastmodifiedafter: Start date for historical data retrieval.
      • lastmodifiedbefore: End date for historical data retrieval.
    • Qualys Tickets REST Message: Retrieves ticket information for the Ticket Integration. Key parameters include:
      • modifiedsincedatetime: Last run date for data retrieval (not recommended for changes).
      • sinceticketnumber: Tracks the last ticket retrieved for pagination.
      • showvulndetails: Indicates whether to retrieve vulnerability details.

    Key Outcomes

    By utilizing these REST messages, ServiceNow customers can effectively manage host detections, access vital knowledge base information, and track tickets seamlessly. The defined parameters facilitate targeted data retrieval while maintaining system performance and integrity.

    Qualys REST messages are used to make calls to the Qualys API.

    Starting with version 12.9.2 of Qualys, you have the option to choose between Basic Authentication or OAuth. The instance parameter Qualys Cloud Authentication method is pre-configured for Basic Auth. If you prefer to use OAuth, you must modify integration instance parameter and then set up the rest message directly for the OAuth.

    Qualys Host Detection REST message

    The Qualys Host Detection REST message makes the initial call to the Host List Detection API for the Qualys Host Detection Integration.

    Table 1. Qualys host detection REST message parameters
    Parameter Name Value Description
    action list Indicates the type of operation requested.

    Required parameter. Changes aren’t required.
    output_format XML Sets the format of the report returned by Qualys.

    The various scripts and transforms assume XML, so changes to the value aren’t recommended.
    detection_processed_after ${lastScanDate} Shows 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.
    truncation_limit 500

    The number of hosts to retrieve data from, according to request. This parameter is used for pagination purposes.

    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.

    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.
    status New, Fixed, Active, Reopened Detection 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.

    It’s important to include the Fixed status when updating vulnerabilities already in the system.

    Qualys host detection pagination REST message

    The Host Detection Pagination REST message handles pagination requests to the Host Detection API.

    When 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.

    Host detection pagination REST is a specialized REST message and isn’t intended to be modified.

    Qualys knowledge base (backfill) REST message

    The 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.

    Changes to the REST message method record impact the request made to Qualys to retrieve knowledge base information.

    The following table shows the request parameters that are sent.

    Table 2. Qualys knowledge base (backfill) REST message parameters
    Parameter Value Description
    action list Indicates the type of operation being requested.

    Required parameter. Changes aren’t recommended.
    details All

    Indicates the level of detail shown for vulnerabilities retrieved.

    Safe to modify as needed.
    ids ${qids}

    Specifies which QIDs to retrieve from Qualys.

    Referenced in code. Modifications aren’t recommended.

    Qualys knowledge base (date-based) REST message

    The 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.

    Changes to the REST message method record impact the request made to Qualys to retrieve knowledge base information.

    The following table shows the request parameters that are sent.

    Table 3. Qualys knowledge base (date-based) REST message parameters
    Source Field Target Field Description
    action list Indicates the type of operation requested.

    Required parameter. Changes aren’t recommended.
    details All Indicates the level of detail shown for vulnerabilities retrieved.

    Safe to modify as needed.
    last_modified_after ${dateStart} Indicates when to start retrieving historical data.

    Used by code to determine both the start time and to assist with pagination.

    Modifications or removal isn’t recommended.
    last_modifiedbefore ${dateEnd}

    Indicates when to end retrieving historical data. Used by code to determine both the end time and to assist with pagination.

    Modifications or removal isn’t recommended.

    Qualys tickets REST message

    The 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.

    The table shows the request parameters that are sent.

    Table 4. Qualys tickets REST message parameters
    Parameter Name Value Description
    modified_since_datetime ${lastRunDatetime}

    Indicates the last run date of the integration and the date after which to pull data.

    Used by code. Changes aren’t recommended.
    since_ticket_number ${lastTicketNumber}

    Indicates which ticket was last retrieved from Qualys.

    Used for pagination. Changes aren’t recommended.
    show_vuln_details 1

    Indicates whether the vulnerability details are retrieved.