Integration commands used in playbooks and in the CLI. Command design, arguments, and outputs.
In addition to fetching incidents or indicators, your integration can map product APIs in commands that you want to expose to Cortex XSIAM.
Every command takes inputs (arguments) and returns outputs.
Command names follow a naming convention that makes it easy for users to understand their function: !vendor-object-action. Use kebab-case for command names. For example, a command of an integration from vendor HelloWorld that performs an update action of an object of type alert, should be named: !helloworld-alert-update.
Integration commands are used in two ways in Cortex XSIAM:
Playbooks - integration commands can be used for playbook tasks.
CLI - users can manually run commands within an incident using the Cortex XSIAM CLI by typing
!commandnameand specifying the arguments.
Customers typically use a combination of both methods. They use commands to automate processes through playbooks. When they are conducting manual investigations, they run commands from the CLI to analyze the data.
It is important to understand how arguments and outputs work in Cortex XSIAM and to understand design best practices.
Command design
Commands should ideally run a single API call to your product. This simplifies the handling of conditions where some calls fail and others succeed. Whenever possible such logic should be implemented in playbooks rather than in integrations.
Verify that commands run quickly and are non-blocking. A command should never take more than 2 to 3 seconds to run and return the information, or it can have significant performance impacts in Cortex XSIAM.
Important
Do not use sleep() in your code. If you have commands that need to run for longer periods of time, there are two options:
Make the commands asynchronous and implement a generic polling mechanism, as used in the HelloWorld integration. For example, if you need to run a search across your endpoints, instead of a single command that waits until the search is completed, you should implement three separate commands.
A command that triggers the search and returns immediately a job ID as output. For example,
!helloworld-start-scan.A command that checks the status of the job taking the job ID as input. For example,
!helloworld-scan-status.A command that retrieves the results of a job when it's complete, taking the job ID as input. For example,
!helloworld-scan-results.
Use long running containers. This is suitable for services that need to keep a connection open for a long time or need to open a listening TCP port. For example, Slack.
In some cases you want to build commands that perform generic well-known actions that are common across several use cases. For example, reputation commands that return enrichment and reputation information about indicators, such as IPs. For those scenarios, we have standardized ways to define command names, inputs and outputs that make interoperability easier. For more information, see Generic commands and DBotScore.
Command arguments
Arguments are the inputs of your integration commands. They can be mandatory or optional, and can have default and predefined values. For more information, see the commands section of the Metadata YAML file documentation.
Command arguments should be named using snake_case.
When you design commands and their inputs, keep in mind how they are invoked. If a user, either manually or through a playbook, has to provide an input, where do they get that input data from? Is it an input they are likely to know? Or the output of another command?
We recommend making the argument values consistent with what the user needs to provide in the user interface of the original product you are integrating with, not necessarily with what the API requires. For example, if in the product UI you have three options for an argument: Low, Medium and High, but the product API takes corresponding numbers (1, 2 and 3), then your integration's command argument should support Low, Medium and High and you should take convert the argument values to numbers in your integration code. The user experience of the integration should be consistent with what the user is already familiar with.
Another important design rule is to avoid having the SOC analyst waste time and focus by switching across multiple consoles to retrieve data from many different places. If they need to provide an input value in a command, there should be a way to get that information from within Cortex XSIAM.
For example, imagine that you are designing a command that modifies an existing firewall policy. For simplicity, assume you have only two arguments: the ID of the policy and the action (allow or deny). The latter argument is obvious: depending on what the user wants to do, they will set the value to allow or deny (you can set predefined values so the user can only choose between these two options). But what about the ID of the policy? It may not be something that they know. They may know the policy name, but you don't want them to switch context and log in to a different console to find the ID that corresponds to the name. In this case, design your integration to include a command that returns a list of all policies and shows their IDs, or allows the user to retrieve the ID from the name, so that the user doesn't have to switch consoles.
Command outputs
Every automation script and integration command returns several types of outputs:
Human readable
Human readable output is shown to the user in the War Room and is typically formatted in a way that is understandable by the SOC analyst. The human readable data is usually a subset of the entire information returned by your command. In most cases, you show the most relevant data that is also present in the user interface of the product you are integrating with. The ordering is important, display the most relevant fields (and the ones the user is most familiar with) in the leftmost columns.
Context data
Outputs are also saved in a structured format (JSON backed) within an incident, so they can be retrieved later and used as inputs of other tasks (either within playbooks or from the CLI).
The context stores the results from every integration command and every automation script that is run. Whether you run an integration command from the CLI or from a playbook task, the output result is stored into the JSON context in the incident or the playground. When you run a command such as
!whois query="cnn.com"the data is returned and the results stored in the context.Additional outputs such as images or files.
When you design your outputs, the data must be properly formatted for both human consumption and machine consumption. The following are best practices for outputs:
Keep human readable information to the reasonable minimum. Remove data that is not relevant to a human analyst and present the remaining data in an orderly manner. We recommend using tableToMarkdown() to automatically format lists into tables. The tableToMarkdown() function also supports arguments that allow you to filter and order columns and improve the formatting of the column headers.
Keep context data organized:
Return data using a prefix, such as
VendorName.Entitytype. For example, if your Pack is calledHelloWorldand you are returning a list of hosts, the prefix of the output should beHelloWorld.Host.Use the CommandResults class to return data to make sure it's properly formatted, and use the
outputs_key_fieldparameter to identify the primary keys.Adhere to the Standard Context.
More information is available about context and outputs.
If you are returning files, it's important to understand the difference between Files and InfoFiles, as you should specify the right return type in your command output:
Filesare potentially malicious files (i.e. attachments from potential phishing emails) that should be treated as such. They are automatically enriched (by checking their reputation against configured threat intel sources) and detonated in sandboxes. For more information, see the File section of the Mandatory context standards topic.InfoFilesare not malicious by definitions. They can be reports, CSVs, and other artifacts that your API returns. They are not automatically enriched and detonated. For more information, see the InfoFile section of the Mandatory context standards topic.