Scheduled Commands - Developer Guide - Cortex XSIAM - Cortex

Abstract

Use commands to schedule the future execution of other commands in playbook tasks.

A command can schedule the future execution of another command. In playbook tasks using scheduled commands, the task does not proceed to the next task until it is done with all scheduled commands and there is no future execution scheduled. When a playbook waits for a command execution, it does not use a worker, since workers are only used at the time commands are executed.

You can use scheduled commands in a polling flow when a command cannot return the full result in a single execution (for example, when a remote process hasn't finished execution). Scheduled commands enable you to try the command again later and return the full results when available. Examples include Cortex XDRIR Endpoint Isolation and AutoFocus V2 Search Samples.

YAML prerequisite

Integration - in the integration YAML, under the command root, add polling: true.
Script - in the script YAML, in the root of the file, add polling: true

The polling_function decorator

The polling_function decorator can be used to avoid much of the code you would otherwise need to implement to write a polling function.

All functions implementing this decorator must always return a PollResult object.

Note

Args must be the first parameter in the function definition and call.

In the example below, we are polling against the client.call_api function. If the API has a successful response, we return our results wrapped in a PollResult object. If the response is not successful, we return whether to continue_to_poll according to the results of the should_not_keep_polling function. A Boolean or a predicate can be passed to continue_to_poll

@polling_function('cs-falcon-sandbox-result')
def some_polling_command(args: Dict[str, Any], client: Client):
    key = get_api_id(args)
    api_response = client.call_api()
    successful_response = api_response.status_code == 200

    if successful_response:
        success_return = show_successful_response()
        return PollResult(success_return)

    else:
        error_response = CommandResults(raw_response=report_response,
                                        readable_output='API returned an error',
                                        entry_type=entryTypes['error'])

        return PollResult(continue_to_poll=lambda: not should_not_keep_polling(client, key), response=error_response)

polling_function arguments

Arg	Type	Description	Default
name	str	The name of the command.	Not applicable
interval	int	How many seconds until the next run.	30
timeout	int	How long to poll until timeout.	600
poll_message	str	The message to display in the war room while polling.	Fetching Results:
polling_arg_name	str	The name of the argument to indicate polling should be done.	polling
requires_polling_arg	bool	Whether a polling argument should be expected as one of the demisto args.	True

PollResult class

Arg	Type	Description
response	Any	The response of the command in the event of success, or in case of failure but Polling is false.
continue_to_poll	Union [bool, Callable]	Whether to return a `ScheduledCommand` to the server to keep polling.
args_for_next_run	Dict	The arguments to use in the next iteration. Will use the input args in case of `None`. Note If you are using this argument, you must add it to the YAML file with the attribute "hidden: true", so that the polling command recognizes the argument for the next run.
partial_result	CommandResults	CommandResults to return, even though we will poll again.

Note

To ignore scheduled War Room entries, add hide_polling_output as a Boolean argument to the command in the YAML file. For an example, see the cs-falcon-sandbox-scan command.

Advanced example

In this example, we are trying to implement a command that submits a URL for analysis and then polls for the result. The proper way to implement this is to split the flow into two commands, the submit command and the find command. The find command is a polling command, and is useful on its own without the context of submit. We want to perform the submit command once and poll on the get_result command until we have a response. We will then have the submit-file command call the find-url command.

@polling_function('find-url')
def find_url_command(args: Dict[str, Any], client: Client):
    api_response = client.call_api(args.get('url')
    successful_response = api_response.status_code == 200

    if successful_response:
        success_return = show_successful_response(api_response)
        return PollResult(success_return)

    else:
        error_response = CommandResults(raw_response=report_response,
                                        readable_output='API returned an error',
                                        entry_type=entryTypes['error'])

        return PollResult(continue_to_poll=True, response=error_response)
        
def submit_url_command(args: Dict[str, Any], client: Client):
    client.submit_url(args.get('url))
    return find_url_command(args, client)

Scheduled Commands - Developer Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM Developer Guide

YAML prerequisite

The polling_function decorator

Note

polling_function arguments

PollResult class

Note

Note

Advanced example