Generic Polling
playbooks
When working with third party products
(such as detonation, scan, search, etc.) you may have to wait for
a process to finish on the remote host before continuing. In those
cases, the playbook should stop and wait for the process to complete
on the 3rd party product, and continue when it is done. You may
not achieve this via integrations or automations due to hardware
limitations. One method for solving this is using the
GenericPolling
playbook.The
GenericPolling
playbook periodically
polls the status of a process being executed on a remote host, and
when the host returns that the process execution is done, the playbook
finishes execution.How to use
Follow these instructions to use the
GenericPolling
playbook.Prerequisites
- Start command: The command that fetches the initial state of the process and save it to the context. This command usually starts the process that should be polled. For example:Detonation: Submits a sample for analysis (detonated as part of the analysis). For example,joe-analysis-submit-sample.Scan: Starts a scan for specified asset IP addresses and host names. For example,nexpose-start-assets-scanSearch: Searches in QRadar using AQL. For example,qradar-searches.
- Polling command: The command that polls the status of the process and saves it to the context. The command inputmust be checkedasIs array, as this allows the playbook to poll at once more than a single process being executed. For example:Detonation: Returns the status of the analysis execution. For example,joe-analysis-info.Scan: Returns the specified scan. For example,nexpose-get-scan.Search: Gets a specific search id and status. For example,qradar-get-search
Inputs
Input | Description |
|---|---|
Ids | A list of process IDs to poll (usually a previous
task output). |
PollingCommandName | Name of the polling command to run. |
PollingCommandArgName | Argument name of the polling command. The argument
should be the name of the process identifier (usually an ID). |
dt | Cortex XSOAR Transform Language filter to be
checked against the polling command result. Polling will stop when
no results are returned from the DT filter. |
Interval | Interval between each poll (default is 1 minute). |
Timeout | The amount of time that'll pass until the playbook
will stop waiting for the process to finish. After this time has
passed the playbook will finish running, even if it didn't get a
satisfactory result (the action is done executing). |
AdditionalPollingCommandArgNames | If the polling command has more than a single
argument you can add their names via this input, for example: arg1,arg2,.... |
AdditionalPollingCommandArgValues | If the polling command has more than a single
argument you can add their values via this input for example: value1,value2,.... |
Generic Polling Example
Detonate File - JoeSecurity
- Start command: Thejoe-analysis-submit-samplecommand starts a new analysis of a file in Joe Security.
- Polling command: Thejoe-analysis-infocommand returns the status of the analysis execution.
- Argument name: Thewebidargument name of the polling command.
- Context path to store poll results:Joe.AnalysisID context path:webidstores the ID of the process to be polled.Status context path:Statusstores the status of the process.
- Possible values returned from polling command:starting,running,finished.
- DTWe want a list of IDs of the processes that are still running. Let's explain how it's built:Path.To.Object(val.Status !== ‘finished’).IDGet the object that has a status other than ‘finished’, then get its ID field. The polling is done only once the result isfinished. The dt filter returns an empty result in that case, which triggers the playbook to stop running.
Limitations of Generic Polling
- Global contextis not supported.
- Does not run from thePlayground.
- The polling command must support a list argument.
