Playbook polling - Administrator Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM Administrator Guide

Product
Cortex XSIAM
Creation date
2024-02-26
Last date published
2024-04-18
Category
Administrator Guide
Abstract

Generic Polling playbook enables you to periodically poll the status of a process on a remote host.

When working with third party products (such as detonation, scan, search, etc.) you may need to wait for a process to finish on the remote host before continuing. In these cases, the playbook should stop and wait for the process to complete on the third party product, and continue when it is done. You may not achieve this via integrations or automations due to hardware limitations.

The GenericPolling playbook is used as a sub-playbook to block the execution of the master playbook until the remote action is complete. There are a number of playbooks that use the Generic Polling playbook that come out-of-the box, or installed from a content pack such as:

Generally polling is used in the following circumstances:

  • File detonation in a sandbox

  • URL detonation

  • Queries that take a long time to complete

Polling prerequisites

You need to use the GenericPolling playbook as a sub-playbook in a master playbook, such as Detonate File - JoeSecurity. The main playbook should follow this structure:

  1. Start Command: The task contains a command that fetches the initial state of the process and saves it to context. This command starts the process that should be polled. For example:

    Detonation: Submits a sample for analysis (detonated as part of the analysis), using the joe-analysis-submit-sample command.

    Scan: Starts a scan for specified asset IP addresses and host names using the nexpose-start-assets-scan command.

    Search: Searches in QRadar using AQL using the qradar-searches command.

  2. Polling Command: The task contains the GenericPolling sub-playbook that polls for an answer. For example:

    • Detonation: After the file is submitted to Joe Security, the playbook polls for specific information for analysis, such as ID, status, comments, errors, SHA-256 hash details.

    • Scan: After the scan runs in Nexpose, using the playbook polls for scan information such as the scan type, the number of assets found, the scan ID, etc.

    • Search: The playbook runs the qradar-get-search to poll for the search ID and status.

  3. Results Task: Returns the results of the operation. The task contains the results that were polled, which are added to context. For example, after polling JoeSecurity, the results are added to context.

For information about the GenericPolling playbook inputs, such as Ids, Interval, and dt, etc., see Playbook inputs.

Generic polling example

This example uses the Detonate File - JoeSecurity playbook from the Joe Security content pack.

The Detonate File - JoeSecurity playbook detonates one or more files using the Joe Security integration and returns relevant reports to the War Room and file reputations to the context data.

  1. If you have not done so, go to Marketplace and download the Joe Security content pack.

  2. Go Playbooks and search for Detonate File - JoeSecurity.

  3. Open the JoeSecurity Upload File task. This task uses the joe-analysis-submit-sample command, which starts a new analysis of a file in Joe Security. This is the Start command.

  4. Open the GenericPolling task. This is the Polling command.

    • Ids: Returns a list of Joe.Analysis.ID’s to poll.

    • PollingCommandName: The joe-analysis-info command returns information for a specified analysis, such as status, MD5, SHA256, vendor, etc.

    • PollingCommandArgName: The webid argument name of the polling command.

    • dt: The filter for polling. This is defined as Joe.Analysis(val.Status!==’finished’).ID.

      Joe.Analysis: The object to return.

      (val.Status !==‘finished’).ID Gets the object that has a status other than ‘finished’, and then gets its ID field. The polling is done only once the result is finished. Once finished, the dt filter returns an empty result, which triggers the playbook to stop running.

      You can change the Status to: starting, running, or finished.

      generic-eg.png
  5. Open the JoeSecurity Get Info task. The joe-analysis-info command returns details of the IDs that have finished polling. This is the Results task.

  6. Open the Set Context task. The context path to store the poll results is Joe.Analysis.

Limitations of generic polling
  • Global context is not supported.

  • Does not run from the Playground.

  • The GenericPolling playbook uses the ScheduleGenericPolling script, which must support a list argument.

    generic-limit.png
Troubleshoot playbook polling
  • The playbook is “stuck” on Waiting for polling to complete.

    As generic polling schedules tasks are outside the context of the playbook (not visible in the playbook run), errors may appear only in the Alerts War Room. Go to the War Room of the alert and check for errors or warnings related to GenericPolling tasks.

  • The GenericPolling task completes but the status has still not "finished".

    If the timeout is reached, the playbook successfully finishes even if there are items that did not complete. Try increasing the timeout value for the GenericPolling task.

  • The integration returns an ID not found error when running from the GenericPolling sub-playbook, but when running manually, it finishes successfully.

    Some products cannot handle consecutive requests to query an action status right after the request to perform the action. After you initiate the action, try adding a Sleep task before calling the GenericPolling sub-playbook.