Design best practices - Developer Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM Developer Guide
Product
Cortex XSIAM
Creation date
2023-05-01
Last date published
2024-06-04
Category
Developer Guide
Abstract

Design best practices for building an integration.

The following are design best practices that you should consider when building an integration.

Integration categories

Your integration should be categorized as one of the following:

  • Import events as incidents

  • Threat intel feeds

  • Analysis & SIEM

  • Authentication

  • Data enrichment and threat intelligence

  • Database

  • Endpoint

  • Forensics & malware analysis

  • Messaging

  • Utilities

  • Vulnerability management

We recommend you review common use cases to help categorize your integration.Use cases

Data clarity

The data returned to the analyst should be as clear as possible. For example, you should convert Epoch timestamps, decrypt data if necessary, etc. If you return IDs, return the original asset name, category type, group name, etc. Additionally, make the parameters and command descriptions as descriptive as possible. Users should be able to understand what the command does and any argument/parameter defaults, maximums, minimums, etc. Use the same names as used by your product, when possible. Your product UI should serve as a baseline for your human readable output.

DBotScore

When mapping a score to DBotScore, stay as close as possible to the integrated product scoring thresholds and categorization. These are usually documented or can be found in the UI of the integrated product. DBotScore reputation includes the following scores: 0 – unknown, 1 – good, 2 – suspicious, 3 – bad. Give users a threshold argument to enable customers to override and implement alternate scoring logic. Specify the score thresholds and DBotScore mapping to the integration documentation.

Set generic reputation commands that indicate the entity reputation such as !url, !ip, !file, etc. .

Global context

Global context outputs are important. When an analyst executes commands/playbooks, global context gives them the option to receive information from multiple integrated products. You can also use global context outputs for DBot scoring and global indicators.

Commands

Follow these best practices for commands.

  • Use the following naming convention for commands: PRODUCTNAME-OBJECTNAME-ACTION. This structure makes it easier for the analyst to find the right object in the UI.

  • Command arguments should be snake case and lower case. For example, argument_name.

  • If a command takes more than a few seconds to execute (for example, vulnerability scan, complex query, or file detonation in sandbox), add a polling playbook. If you implement a polling playbook, include a status command as well.

  • When a command supports filtering results by time, use start and end time parameters (if supported by the UI), and a time frame parameter that accepts inputs such as “4 days ago” or “5 minutes ago”.

Backward compatibility

Cortex XSIAMcomponents, such as playbooks, rely on previous inputs. To avoid breaking backward compatibility, keep the old context, add new paths as needed, and update the outputs accordingly. If a command needs major modifications, deprecate the command and create a new one.

Limitations

  • The logo must be under 10kB. Use the company logo, not the product logo.

  • If the result contains more than 50 entries, limit the context size.