Cortex XSIAM Developer Guide

This guide helps you create Cortex XSIAM content. You can create content for your own use, or contribute content to Marketplace that either you support or that is community supported.

Playbooks, alert fields/layouts/rules, indicator fields/types/layouts, classifiers, mappers, widgets, and dashboards should be developed within the Cortex XSIAM UI.

For integrations and scripts, when creating content to use within your instance of Cortex XSIAM or for contribution as a community supported content pack, the UI may be sufficient. For more complex development needs, or if you plan on contributing content as a partner supported content pack or a modification to partner supported content, we recommend using Visual Studio Code, with the Visual Studio Code extension. If you work locally, we recommend installing Demisto SDK to upload, download, and run code on Cortex XSIAM directly from your operating system shell. To develop content for contribution as a partner-supported content pack, or to submit modifications to partner-supported content packs, you must set up a full development environment.

If you have questions or need support, contact us on the #demisto-developers channel on our DFIR Slack community.

Prerequisites and resources

Cortex XSIAM is a powerful platform with a rich set of features and customizations. We recommend following these steps before creating custom content:

1. Read and understand Cortex XSIAM Concepts.
2. Read the FAQs.
3. Review relevant sections of the Cortex XSIAM product documentation.

4. Understand your use case.

   What are you trying to achieve? What is the user story? What is the expected workflow? Are you creating a content pack or creating content for internal use?

5. Development scope

   What content items do you need to develop? Content can include integrations, scripts, playbooks, dashboards, fields, layouts, classifiers, mappers, lists, and data modeling and parsing rules. In some cases, you may just need a playbook to achieve your goals. In other cases, you may need multiple content items.

6. Verify you have an active tenant.
7. If you plan to publish your content to Marketplace for other customers to use, read about the contribution process and the different tiers and support levels (for example, partner vs community support). Learn about best practices and requirements for content pack contributions.
8. Register to the Learning Center and go through the Product Training.
9. Access the Palo Alto Networks DFIR Slack community and join the #demisto-developers channel.
10. If you are integrating with an external API, verify you have API or SDK access to the product or solution you want to integrate with.

11. (Optional) Install the Demisto SDK.

    The Demisto SDK is a command line tool that can be used to upload, download, validate and run code on Cortex XSIAM directly from your command line. The Demisto SDK offers a Python library and CLI designed to aid the development process, to validate entities and to assist in the interaction between your development setup and Cortex XSIAM. You can use the Demisto SDK with the built-in IDE or with a full development environment.

12. (Optional) Install the Video Studio Code extension to develop integrations and scripts.

Development, documentation, and contributions

• Development

  • Integrations and scripts

    Review the structure for integrations and code conventions, as well as features such as data centralization, intelligent stitching, analytics-based detection, alert and incident management, script, generic commands, and reputation score. Write and test your code.

  • Playbooks - learn about playbook design, conventions, and the use of generic playbooks.

    For more information on playbook design and development, see Playbooks.

  • Lists - learn how to download a list from Cortex XSIAM and include it in your content pack.
  • Alerts - learn how to create alert fields, layouts, rules, classifiers, and mappers.

  • Data modeling, parsing, and correlation - learn how to create parsing, data modeling, and correlation rules.

    Enable mapping of events and logs into a single, unified data model. This data model provides a consolidated schema, and a simpler way to interact with your data, regardless of its source or dataset. To familiarize yourself with the data model schema, see Cortex XSIAM Data Model Schema.

  • Indicators - learn how to create indicator fields and layouts. Learn how domains and URLs are extracted, how to create and use relationships, and more.
• Documentation - learn about documentation best practices, as well as documentation requirements for Marketplace contributions.
• Contributions - learn the requirements for contributing content to Marketplace.

Cortex XSIAM provides out-of-the-box content that contain most of the functionality you need. However, it also supports creating custom content, enabling you to develop unique functions to meet any specific need. You can create individual content items (playbooks, integrations, etc.) for your own use or create content packs that can be contributed to Marketplace.

Content packs include one or more content items, and facilitate integrating various data sources by packaging together predefined configurations such as parsers, rules, and dashboards, improving the accuracy and efficiency of security threat identification and analysis. All content contributed to Marketplace must be within a content pack.

Before you begin to create content packs for contribution, you need to understand your goals, and review the design guidelines. Careful attention to the design process ensures that you achieve your desired use case and that the different components of your content pack function correctly together.

During the design process, we recommend the following stages:

• Understand your use case.
• Identify which components you need to achieve your use case, such as playbooks, integrations, incident fields, etc. Determine what content, if any, you can reuse from existing content packs.
• Review documentation best practices.

While you do not need to complete your entire design before you begin coding, we recommend you return regularly to the design stage throughout the development process, to review whether you are achieving your use case, if your components have changed, and to verify you are implementing best practices.

When designing your use case, consider how you want to create alerts, enrich data, and respond to alerts.

• Alert creation

  Alerts can be fetched from external APIs or pushed to Cortex XSIAM using REST APIs or emails. Custom layouts can also be created to allow the SOC analyst to focus on the most relevant information.

• Data enrichment

  Additional data is automatically collected from multiple sources (including directories and databases) to provide the analyst with all the necessary context to make decisions on priority and impact.

• Alert response

  This can range from closing a false positive to complex playbooks including automated or semi-automated remediation steps across the entire IT infrastructure, such as blocking, quarantining, notifying people, collecting more data, forensics analysis, reporting, etc.

When you begin designing a content pack, we recommend you start by thinking about user stories. What would be a successful outcome for the user? How can you improve your incident workflow and decrease the time and resources required for investigation? The following points can help you design your contribution:

• Do you want to create an end-to-end use case that includes all of the phases of alert creation, data enrichment, and incident response?
• Do you want Cortex XSIAM to consume alerts from a new product?
• Do you want to provide enrichment from a data or reputation source that isn't already available in content?
• Do you want to automatically fetch IOCs from a third party platform into Cortex XSIAM?
• Do you want to map a third party product API into Cortex XSIAM, so that actions can be automated?
• Do you want to create playbooks that automate a response workflow across multiple security products?
• Are there time-consuming manual tasks in your products or security department that could be automated?

The following are examples of use cases:

• The SOC team wants to include a new source of alerts in Cortex XSIAM from a security product that is currently not supported by Marketplace. This could be already achieved through a SIEM, but a direct integration makes it easier to consume and provide a better UX to the analysts.
• The SOC team wants Cortex XSIAM to automatically provide reputation information about IOCs from a Threat Intelligence source that is currently not supported by Cortex XSIAM.
• The SOC team wants to integrate to an existing IT solution (i.e. a CMDB, Instant Messaging platform or Database) to automatically exchange data with Cortex XSIAM.
• The SOC team wants to automatically trigger actions on a third party security product that is currently not available in the Marketplace.

You can also view more use cases across a variety of product categories.

If you are a third-party security vendor and want to integrate your product, we encourage you to think creatively about your product's unique capabilities that can be provided through Cortex XSIAM to provide value to joint customers. We recommend not limiting the use case to your existing APIs, during the design phase. In some cases, when creating a content contribution, technology partners decide to implement new APIs in their platforms to improve automation and better integrate with Cortex XSIAM.

Based on your use case, you can determine which content items to create.

You can create individual content items for your own use, or package one or more content items together within a content pack. Contributions are content packs that you create for Marketplace which are submitted to Cortex XSIAM for review and approval. After approval, these content packs are uploaded to Marketplace, and can be installed by other users.

Playbooks

If you have an end-to-end use case in mind, you likely need one or more playbooks. Think about the process that you want to automate and the steps and the decisions during the process. These steps and decisions become the playbook tasks. Check if any or all of these building blocks are already part of Cortex XSIAM by browsing Marketplace.

You can have multiple playbooks in the same content pack, as long as they are related to a similar end-to-end use case. If they are completely separate, consider splitting them in multiple content packs.

Playbooks can use sub-playbooks from the same content pack or other content packs, with dependencies that can be set as mandatory or optional. Select the Skip this branch if this script/playbook is unavailable option in playbook task fields to enable the playbook to continue executing if an instance of the script, playbook, or sub-playbook is not available.

Cortex XSIAM provides a number of generic playbooks that can be used as sub-playbooks.

Integrations

Create an integration if:

• You have a use case in mind that requires communicating with a third-party system or API, but there is no integration available for it in the Cortex XSIAM Marketplace.
• You are a vendor and you want Cortex XSIAM to be able to interact with your product or retrieve indicators from your threat intel feed.

Integrations are the building blocks that enable external communications and form the foundations of playbooks.

While you can include multiple integrations within a single content pack, we recommend in most cases including only one integration per content pack. If you are building two separate integrations to interact with two different third-party products, you should create a separate content pack for each product.

Data Model rules, alert fields, layouts, classifiers, mappers, and playbooks

If you are creating an integration that fetches incidents from a third-party system, in many cases additional items are required within the content pack.

• Data model rules

  You can map your logs into a single, unified data model that provides a consolidated schema and a simpler way to interact with your data, regardless of its source or dataset. Map your data to the data model using data model rules, either by using the default rules that are automatically added when installing content packs from the Marketplace, or by creating user-defined rules.

• Parsing rules

  Define patterns or regular expressions that specify how to identify and extract specific pieces of information from the incoming data. For example, you can create a parsing rule to extract IP addresses, URLs, or file names.

• Correlation rules

  Analyze correlations of multi-events from multiple sources by using the Cortex Query Language (XQL) based engine for creating scheduled rules called Correlation Rules. Alerts can then be triggered based on these correlation rules with a defined time frame and set schedule, including every X minutes, once a day, once a week, or a custom time.

• Alert fields

  Create alert fields for data specific to custom incident types. All of the alert fields should be associated only to the incident type you have created, and their names should be prefixed accordingly to indicate this association.

• Layouts

  As you create alert fields, they can be added to new alert layouts, making the most relevant information visible to your users.

• Classifiers

  Create a classifier that determines how incoming alerts are classified (by alert type) in Cortex XSIAM.

• Mapper

  A mapper determines how the raw data from the incoming alert JSON is mapped to alert fields.

• Playbooks

  Playbooks can be associated with an alert type and run automatically on incoming alerts of that type. A playbook might enrich indicators within a playbook or perform additional triage of an alert. For an example, see the Handle Hello World Alert playbook.

Scripts (automations)

Scripts work with data already within Cortex XSIAM, while integrations, by contrast, can communicate with external APIs. Scripts are often used to transform data, visualize it, trigger playbooks when certain conditions occur, etc. Often, you do not need to plan exactly which scripts you need early during the design process. As you progress with your content development, it can become clear, for example, that your playbook needs a particular script to transform incident data into a useable form.

Dashboards & widgets

If you want to visualize summarized and aggregated data about anything in Cortex XSIAM (for example, incidents, alerts, and indicators), you can create custom dashboards and widgets. Dashboards are collections of widgets that can be customized and included in content packs.

Integrations enable communications with third-party APIs. If you are contributing an integration to Marketplace, you must follow the design best practices. To be accepted in the Cortex XSIAM Marketplace, integrations must function correctly, be properly documented, and work well with other related content.

When designing an integration, consider the following questions:

• Which product/API are you integrating with?
• Which product category does it belong to? See the list of approved product categories.
• Which version(s) of the product will you support?
• How does the authentication work?
• Will your integration fetch alerts? If so, what are the names of the entities in the source product (for example alerts, events, messages, warnings, logs) that will be mapped to alerts in Cortex XSIAM? What is the lifecycle of the entities, are they static or are they updated over time?
• What is the maximum number of new alerts this product can generate in a busy production environment?
• Are you calling APIs that can take longer than 5 to 10 seconds to respond?
• Does the product provide feeds of IOCs?
• Does the product provide any reputation on Indicators of Compromise (IOCs)?

Additional Considerations

• Understand and follow our code conventions to simplify implementation and the review process.
  • Python
  • PowerShell
• Integrations run in Docker containers. Cortex XSIAM provides generic images with recent Python and PowerShell versions and a small set of libraries. To use additional libraries that are not part of the default images, view our dockerfiles repository in GitHub to see if an existing images meets your needs. If not, you can create your own Docker image and contribute it. The Docker image to use must be specified in the integration YAML file.
• You can build feed integrations that collect batches of indicators from threat intel feeds. For more information, see Feed Integrations.
• To store integration-specific data, such as tokens that have a specific duration (i.e. JWTs for authentication), you can use the integration cache functionality.

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.

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.

Cortex XSIAM offers several tools for development including an IDE in the UI, a Visual Studio Code extension, and the Demisto SDK Python library.

When creating complex integrations and scripts, we recommend using a full development environment. Options include:

• Local development environment
• GitHub Codespace environment
• Containerized development environment

Content developed in the UI

The following content items should be developed from within the Cortex XSIAM UI:

• Playbooks
• Alert fields, layouts, and rules
• Indicator fields, types and layouts
• Classifiers and Mappers
• Widgets
• Dashboards

Once the resource is developed in the Cortex XSIAM UI, you can download it using demisto-sdk download -i "$NAME_OF_RESOURCE" or export it from the UI.

Content developed in Visual Studio Code

For integrations and scripts, when creating content to use within your instance of Cortex XSIAM or for contribution as a community supported content pack, the UI may be sufficient. For more complex development needs, or if you plan on contributing content as a partner supported content pack or a modification to partner supported content, we recommend Visual Studio Code. The Visual Studio Code extension should be installed locally, and can be used with a regular local development environment or GitHub Codespace. It is included by default with the containerized development environment. We also recommend installing Demisto SDK to upload, download, and run code on Cortex XSIAM directly from your operating system shell. Demisto SDK is included by default with the containerized development environment.

Note

To develop content for contribution as a partner-supported content pack, or to submit modifications to partner-supported content packs, you are required to set up a full development environment.

Use the Cortex XSIAM built-in IDE to create and edit automation scripts. Open the script editor from Incident Response → Automation → Scripts.

The Cortex XSIAM IDE differs from other development environments. For example, it has no interpreter, whereas Visual Studio Code does.

Note

For more complex development needs, we recommend instead using the Visual Studio Code extension. It simplifies third-party integration and script development by enabling users to author Python content for Cortex XSIAM directly in Visual Studio Code. This is also the most efficient way to develop Python Unit Tests.

Script Helper for Cortex XSIAM script development

Script Helper provides commonly used functions for Cortex XSIAM automation script development.

To access the script helper, go to Cortex XSIAM under Incident Response → Automation → Scripts → Script Helper.

A list of the common server functions appears.

Script Settings

Clicking the Settings button opens the Script Settings dialog box, which contains configurations for Basic, Arguments, Permissions, Advanced, and Depends on Commands script settings.

For more information about the script settings, see Scripts.

Keyboard Shortcuts

The following are some useful keyboard shortcuts supported in the IDE.

Select

Go to

Find/replace

Fold

Other

You can write code directly in the UI, but to contribute a full integration, you need a full development environment external to Cortex XSIAM. An external development environment enables linting your code, running unit tests with pytest, creating documentation, submitting your changes via git and more. There are three options for your external development environment, a traditional local environment described below, a GitHub Codespace environment, or a containerized environment.

Setting up the local development environment involves the following steps:

Verify prerequisites

Cortex XSIAM

• An active Cortex XSIAM tenant.
• Review Contribution requirements.

GitHub

Go to GitHub and sign in or sign up for an account.

Docker

Make sure Docker is installed on your system and is working correctly by running the hello-world container:

sb@dddd:~/demisto$ docker run --rm hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.

[... output omitted for brevity ...]

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

sb@dddd:~/demisto$

Note

If you are using Windows with WSL2, you can still use Docker Desktop from WSL. See here for details.

Fork the GitHub repo

1. Log in to GitHub, navigate to the Content Repo, and click Fork.

2. Once the fork is complete, copy the URL.

   This is the fork where you will commit your code and, once ready, create the Pull Request to submit your contribution back to the Cortex XSIAM content repository. Do not work on the master or main branch.

   

Clone the GitHub fork locally

In the shell, create a folder (for example, ~/demisto) and clone your fork of the content repository using git clone [your_fork_url], where [your_fork_url] is the URL you copied from GitHub after forking.

sb@dddd:~$ mkdir demisto
sb@dddd:~$ cd demisto
sb@dddd:~/demisto$ git clone https://github.com/[omitted]/content.git
Cloning into 'content'...
remote: Enumerating objects: 108, done.
remote: Counting objects: 100% (108/108), done.
remote: Compressing objects: 100% (90/90), done.
remote: Total 101143 (delta 50), reused 53 (delta 18), pack-reused 101035
Receiving objects: 100% (101143/101143), 110.65 MiB | 11.04 MiB/s, done.
Resolving deltas: 100% (73634/73634), done.
Checking out files: 100% (4522/4522), done.
sb@dddd:~/demisto$

Note

You must clone your fork of the repository, as you will need to be able to write into it. Do not clone demisto/content, because you won't be able to push commits.

Set up environments

Set up a remote environment

Follow these steps to set up a fully configured remote environment with VS Code Dev Containers.

Verify prerequisites

VS Code

1. Download and install VS Code.
2. Install the Remote Development pack.

If you are not familiar with VS Code, follow the VS Code getting started guide.

Docker

Follow the instructions here to install Docker to your operating system.

• Windows: Docker Desktop 2.0+ on Windows 10 Pro/Enterprise. Windows 10 Home (2004+) requires Docker Desktop 2.3+ and the WSL 2 back-end.
• macOS: Docker Desktop 2.0+.
• Linux: Docker CE/EE 18.06+ and Docker Compose 1.21+

Install and enable WSL and Docker

For Windows users, we recommend using Windows Subsystem for Linux (WSL) for better performance.

1. Install WSL.
2. Open WSL in VS Code.
3. Enable Docker support.

4. Verify WSL 2 is installed by running:

   wsl --list --verbose
   

   Verify the installed distribution is running WSL 2.

   To change versions, use the command:

   wsl --set-version <distro name> 2
   

   Replace <distro name> with the name of the Linux distribution that you want to update. For example, wsl --set-version Ubuntu 2 sets your Ubuntu distribution to use WSL 2.

Clone the repository

You can clone the terminal and work directly with VS Code. To work with Github in VS Code, follow the instructions here.

Open the repository in VS Code

If you already cloned the repository with VS Code, go directly to open the dev container.

1. In VS Code, go to File+Open Folder.
2. Select your GitHub repository.

Open the Dev Container

1. Click the green button.

   

2. Click Reopen in Container.
3. It may take a few minutes until the Dev container is ready.

Troubleshooting

Docker performance issues

• For Windows, use WSL2.
• Update Docker.
• Disable Autosave in VS Code.

Since Docker is not native for Mac or Windows, there may be performance issues.

Errors opening the dev container

• Update Docker.

• Clean up Docker.

    docker system prune -a --volumes
  

Set up a local environment

Verify your operating system folder structure

If you are using Windows with WSL and your code resides in a shared folder on the Windows tree (/mnt/c/code/demisto), verify the folder is set to be case sensitive.

Install pyenv and Python

You need Python 3 installed on your system. We recommend using pyenv.

1. Verfiy pyenv in installed and the eval "$(pyenv init -)" expression is placed in your shell configuration (~/.bashrc or ~/.zshrc).

   sb@dddd:~/demisto$ eval "$(pyenv init -)"
   sb@dddd:~/demisto$ pyenv -v
   pyenv 1.2.15
   sb@dddd:~/demisto$~/demisto$
   

   See more more details about pyenv installation. Either Homebrew for MacOS or the automatic installer on Linux/WSL work.

2. If the required version of Python is missing, you need to install it. Because pyenv compiles CPython, you may need some libraries. See more troubleshooting info.

   For example, install Python 3.10.5.

   sb@dddd:~/demisto$ pyenv install 3.10.5
   Downloading Python-3.10.5.tar.xz...
   -> https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tar.xz
   Installing Python-3.10.5...
   Installed Python-3.10.5 to /home/sb/.pyenv/versions/3.10.5
   
   sb@dddd:~/demisto$ pyenv versions
     3.10.5
   sb@dddd:~/demisto$
   

Install Poetry

1. Install Poetry.

2. Once you set up your development environment, you can activate Poetry with the poetry shell command. Include (.venv) in front of the prompt. Note that the shell command is available in a plugin.

   sb@dddd:~/demisto/content$ poetry shell
   (.venv) sb@dddd:~/demisto/content$
   

   Note

   You can leave the Poetry virtual environment using the deactivate command:

   (.venv) sb@dddd:~/demisto/content$ deactivate
   sb@dddd:~/demisto/content$
   

Install the nvm package manager

1. Install the nvm package manager.
2. Run nvm install node.

Install pipx

Pipx is a package that enables you to install and run the Python application globally in an isolated Python environment.

To install Pipx, run the following commands:

pip install --user pipx
pipx ensurepath

Install demisto-sdk

Demisto SDK is a tool that assists in the contribution process. It helps you to generate a content pack, maintain your files, and validate them before committing to the branch. Install Demisto SDK using the pipx command pipx install demisto-sdk --force. To verify you have the latest version of the SDK, run: demisto-sdk --version.

Run the bootstrap script

Before running the bootstrap script that creates the virtual environment, set up pyenv to work correctly in the content folder you just cloned.

Initially, no local python interpreter has been set via pyenv.

sb@dddd:~/demisto$ cd content
sb@dddd:~/demisto/content$ pyenv local
pyenv: no local version configured for this directory

1. Set pyenv to use the latest version Python 3 you previously installed and verify that everything is set correctly.

   sb@dddd:~/demisto/content$ pyenv local 3.10.5
   
   sb@dddd:~/demisto/content$ pyenv local
   3.10.5
   
   sb@dddd:~/demisto/content$ which python3
   /home/sb/.pyenv/shims/python3
   
   sb@dddd:~/demisto/content$ python3 -V
   Ptyhon 3.10.5
   

2. Run the bootstrap script.

   The bootstrap script sets up a pre-commit hook that validates your modified files before committing. It also sets up a Python virtual environment for development with the package requirements for Python3.

   Note

   If you are using WSL and you see errors about "python.exe" getting called, disable it in the App Execution Alias (see more details).

   1. Run the script from the root directory of the source tree: .hooks/bootstrap.

      sb@dddd:~/demisto/content$ .hooks/bootstrap
      Installing 'pre-commit' hooks
      =======================
      Configure poetry to install virtual environment in the project repo (will be available in (.venv)
      Check if poetry files are valid
      All set!
      Installing dependencies...
      Detected local env.
      Installing dependencies from lock file
      
      No dependencies to install or update
      ==========================
      Done setting up virtualenv with poetry
      Activate the venv by running: poetry shell
      Deactivate by running: deactivate
      =======================
      Running: npm install ...
      
      up to date, audited 230 packages in 1s
      

   2. After the bootstrap script completes, install an extra plugin to get poetry shell to work by running poetry self add poetry-plugin-shell.
   3. After the plugin script completes, activate the newly created virtual environment by running poetry shell.

Run linters and unit tests

Cortex XSIAM content ships with a HelloWorld integration that provides basic functionality and is useful to understand how to create integrations.

It's located in the Packs/HelloWorld/Integrations/HelloWorld folder. demisto-sdk runs the linting and unit testing to verify the dev environment is working (including Python and Docker).

1. Verify you are running inside the Poetry virtual environment.

   sb@dddd:~/demisto/content$ poetry shell
   (.venv) sb@dddd:~/demisto/content$
   

2. Run the demisto-sdk pre-commit command on the Packs/HelloWorld/Integrations/HelloWorld folder using the -i option, or if you want to run against all the committed files in your branch you can use demisto-sdk pre-commit -g. It will run both the linters and pytest (unit testing).

   Note

   The tests run within a Docker container, so if the tests pass, it means that your development environment is up and running correctly.

   (venv) sb@dddd:~/demisto/content$ demisto-sdk pre-commit -i Packs/HelloWorld/Integrations/HelloWorld
   Running pre-commit using template /Users/sfainberg/dev/demisto/content/.pre-commit-config_template.yaml
   Running pre-commit with Python 3.11 on:
   Packs/HelloWorld/Integrations/HelloWorld/HelloWorld.py
   Packs/HelloWorld/Integrations/HelloWorld/HelloWorld.yml
   Packs/HelloWorld/Integrations/HelloWorld/HelloWorld_description.md
   Packs/HelloWorld/Integrations/HelloWorld/HelloWorld_image.png
   Packs/HelloWorld/Integrations/HelloWorld/HelloWorld_test.py
   Packs/HelloWorld/Integrations/HelloWorld/README.md
   Packs/HelloWorld/Integrations/HelloWorld/command_examples
   Packs/HelloWorld/Integrations/HelloWorld/test_data/get_alert.json
   Packs/HelloWorld/Integrations/HelloWorld/test_data/incident_note_list_command.json
   Packs/HelloWorld/Integrations/HelloWorld/test_data/ip_reputation.json
   DockerHook - Unable to find image docker.io/devtestdemisto/python3:3.11.10.115186-12dd7198e064c21c217cc72c87ddadd5. Creating image based on docker.io/demisto/python3:3.11.10.115186 - Could take 2-3 minutes at first
   check json...............................................................Passed
   check yaml...............................................................Passed
   check python ast.........................................................Passed
   check for merge conflicts................................................Passed
   debug statements (python)................................................Passed
   python tests naming......................................................Passed
   check for added large files..............................................Passed
   check for case conflicts.................................................Passed
   poetry-check.........................................(no files to check)Skipped
   pycln....................................................................Passed
   ruff-py3.11..............................................................Passed
   autopep8.................................................................Passed
   mypy-py3.11..............................................................Passed
   xsoar-lint...............................................................Passed
   pylint-in-docker-demisto/python3:3.11.10.115186..........................Passed
   pytest-in-docker-demisto/python3:3.11.10.115186..........................Passed
   validate-deleted-files...................................................Passed
   validate-content-paths...................................................Passed
   validate-conf-json...................................(no files to check)Skipped
   validate.................................................................Passed
   secrets..................................................................Passed
   merge-pytest-reports.....................................................Passed
   coverage-pytest-analyze..................................................Passed
   

Create a branch

The Git flow requires creating a branch with your new code that you will later use to submit a Pull Request.

To create a branch, use the git checkout -b [branch_name] command, where the [branch_name] corresponds to your integration.

(venv) sb@dddd:~/demisto/content$ git checkout -b my_integration_name
Switched to a new branch 'my_integration_name'

Create your integration directory

Create a directory under Packs/<Your pack name>, named after your product where you will put all your content files later, and add it to the staged changes in Git. Use PascalCase in the directory name (for example, MyIntegration). See Content Pack Structure for more information.

You can create a pack and an integration directory using the demisto-sdk init command. The following is an example of creating a pack called MyNewPack, with an integration called MyIntegration, with the metadata file created automatically:

➜  content-docs2 git:(add-pack-and-sdk-docs) ✗ demisto-sdk init --pack 
Please input the name of the initialized pack: MyNewPack
Successfully created the pack test in: MyIntegration

Do you want to fill pack's metadata file? Y/N y

Display name of the pack: MyNewPack

Description of the pack: A description for my newly created pack.

Support type of the pack: 
[1] demisto
[2] partner
[3] developer
[4] community

Enter option: 2

Server min version: 5.0.0

Author of the pack: Partner name 

The url of support, should represent your GitHub account (optional): https://github.com/<PartnerGitAccount>

The email in which you can be contacted in: partner@partner.com

Pack category options: 
[1] Analytics & SIEM
[2] Utilities
[3] Messaging
[4] Endpoint
[5] Network Security
[6] Vulnerability Management
[7] Case Management
[8] Forensics & Malware Analysis
[9] IT Services
[10] Data Enrichment & Threat Intelligence
[11] Authentication
[12] Database
[13] Deception
[14] Email Gateway

Enter option: 1

Tags of the pack, comma separated values: 
Created pack metadata at path : MyNewPack/metadata.json

Do you want to create an integration in the pack? Y/N y
Please input the name of the initialized integration: test
Do you want to use the directory name as an ID for the integration? Y/N y
Finished creating integration: MyNewPack/Integrations/test.

Commit and push

The last step is to commit your changes and push them to the origin to verify that the pre-commit checks pass.

You can also run the hooks locally using Demisto SDK by running the following commands. See this README for more information about Demisto SDK commands and formats.

• demisto-sdk format - Auto-corrects formatting for the validation to pass.
• demisto-sdk validate -g - Validates the integrity of the YAML files, and verifies they follow the pre-set roles.
• demisto-sdk pre-commit -i <The path to your changed/newly added content entity> - Runs lint and pytest on the changed Python files.

1. Run git commit -m '[some commit message]', which automatically runs the pre-validation checks.

   (venv) sb@dddd:~/demisto/content$ git commit -m 'Initial commit of MyIntegration'
   Validating files...
   Starting validating files structure
   Using git
   Running validation on branch my_integration_name
   Validates only committed files
   Starting validation against origin/master
   The files are valid
   Starting secrets detection
   Finished validating secrets, no secrets were found.
   
   Skipping running dev tasks (flake8, mypy, pylint, pytest). If you want to run this as part of the precommit hook
   set CONTENT_PRECOMMIT_RUN_DEV_TASKS=1. You can add the following line to ~/.zshrc:
   echo "export CONTENT_PRECOMMIT_RUN_DEV_TASKS=1" >> ~/.zshrc
   
   Or if you want to manually run dev tasks: ./Tests/scripts/pkg_dev_test_tasks.py -d <integration/script dir>
   Example: ./Tests/scripts/pkg_dev_test_tasks.py -d Scripts/ParseEmailFiles
   
   On branch my_integration_name
   Untracked files:
           .python-version
   
   nothing added to commit but untracked files present
   

   Note

   • Ignore the .python-version file warning, that is generated by pyenv and is not added to the repository.
   • Since there are no files yet in the directory you created (for example, Integrations/MyIntegration), it will not show up in your branch after the commit. However, you can verify that all the components are in place.

2. Push to your branch with the command git push origin [branch_name]. You will be prompted for your GitHub credentials.

   (venv) sb@dddd:~/demisto/content$ git push origin my_integration_name
   Username for 'https://github.com': [omitted]
   Password for 'https://[omitted]@github.com':
   Total 0 (delta 0), reused 0 (delta 0)
   remote:
   remote: Create a pull request for 'my_integration_name' on GitHub by visiting:
   remote:      https://github.com/[omitted]/content/pull/new/my_integration_name
   remote:
   To https://github.com/[omitted]/content
    * [new branch]          my_integration_name -> my_integration_name
   (venv) sb@dddd:~/demisto/content$
   

3. Go back to GitHub and under your fork you should be able to see that there is a new branch with the name you provided (for example, my_integration_name).

   

   The development environment for Cortex XSIAM is complete, with a fully configured virtual environment where you can run different validation and utility scripts. You can now start writing your code.

This topic provides step-by-step instructions for setting up a personal Codespace for developing Cortex XSIAM content.

What are GitHub Codespaces?

GitHub Codespaces are cloud-based development environments provided by GitHub that allow you to set up remote environments with preinstalled and preconfigured tools and dependencies using a dev container.

Your Codespace environment is hosted on GitHub's servers (attached to your GitHub account), and allows you to access your Codespace from any computer.

Cost and limitations

GitHub offers a free quota for Codespaces (which is higher for GitHub Pro users) that you can utilize for developing Cortex XSIAM content.

The quota is calculated based on the number of hours your Codespace is actively running. You can see the free quota plan and options for additional paid usage after you reach your quot, in the GitHub documentation.

You will receive an automated email notification when you have used 75%, 90%, and 100% of your free quota. You can find information about your Codespaces quota usage in the GitHub settings under Billing and plans. For more information, see the GitHub article Viewing your GitHub Codespaces usage.

Note

Codespaces generated from the content repository (or a fork of it) are configured to have four cores by default.

Create a new Codespace

1. Log in to your GitHub account. If you do not have a GitHub account, you must create one before you can create a Codespace.
2. Enter the content repository.
3. Fork the repository to your account.
   1. Click Fork at the top right.
   2. Select your account as the owner, and leave the repository name as is.
   3. Keep the Copy the master branch only option selected.

   4. Create fork.

      

4. After a few seconds, you are redirected to your forked repository page.
5. Create a new branch on your fork, and give it a meaningful name.

6. Click Code, go to the Codespaces tab, and Create Codespace on \branch name>.

   

   If the message This Codespace is requesting additional permissions appears, Continue without authorizing.

7. Click New Codespace.

   This may take a few minutes to complete.

Configure an IDE

Browser-based Visual Studio Code

By default, GitHub provides a browser-based Visual Studio Code editor that's automatically configured, authenticated, and connected to your Codespace, using your GitHub account.

To open the editor, enter the main forked repository page, click Code, go to the Codespaces tab, and click the newly created Codespace (should have a random name).

It can take a few minutes for the Codespace to be fully initialized. This delay only occurs the first time you open a Codespace.

Once the initialization is completed and your Codespace is ready, you are redirected to the IDE, where you can start your development.

Visual Studio Code (local)

To connect to your Codespace from a local Visual Studio Code editor and use the Visual Studio Extension, you need to install the official GitHub Codespaces extension.

For a complete installation and configuration tutorial, refer to the Using GitHub Codespaces in your local development environment article by GitHub. You can skip the Creating a Codespace in VS Code section, as we've already created a Codespace.

JetBrains IDEs (PyCharm, IntelliJ IDEA, etc.) (local)

To connect to your Codespace from a JetBrains IDE, you will need to install and configure JetBrains Gateway.

For a complete installation and configuration tutorial, refer to the official Using GitHub Codespaces in your JetBrains IDE article by GitHub.

Development

After your IDE is connected to your Codespace, you can start developing your content. The environment comes pre-installed with all the required tools and dependencies for developing Cortex XSIAM content. Configuring SSH keys or any other credentials is not required, as the Codespace is already authenticated using your GitHub account.

Additional Resources

For additional documentation about GitHub Codespaces, see the official GitHub Codespaces documentation.

You can set up a fully functional development environment in a Docker container. The containerized development environment includes all the necessary tools and dependencies needed to develop content in the demisto/content repository.

Requirements

The following must be installed on the host machine as described in System Requirements.

• Docker
• Visual Studio Code
• Dev Containers extension

Recommended hots requirements are specified in devcontainer.json.

• 4 CPUs
• 8GB of memory
• 32GB free disk space

You also need a forked/cloned content repository on the host machine.

Installation

Install Docker, Visual Studio Code, and the Dev Containers extension, following the installation instructions on the Visual Studio Code website.

Open the repository in Visual Studio Code

1. In Visual Studio Code, go to File → Open Folder.
2. Select the cloned/forked repository.
3. Create a new branch to use for your development.

Open the dev container in Visual Studio Code

1. In Visual Studio Code, click the green button.

   

2. Click Reopen in Container. Alternatively, open the command prompt (CMD+SHIFT+P) and search for Reopen in Container.

   Note

   It may take a few minutes until the dev container is ready for use.

Usage

Once the dev container is ready, a new Visual Studio Code window opens and the content repository is available.

The environment contains demisto-sdk, zsh, git, pyenv, poetry, preinstalled system and Python dependencies, and recommended extensions, including the Cortex XSOAR Visual Studio Code Extension.

Troubleshooting

If there are errors when opening the dev container, try the following:

• Update Docker
• Run the following command to clean up Docker: docker system prune -a --volumes

The Demisto SDK is a Python library and CLI designed to aid the development process, both to validate entities being developed and to assist in the interaction between your development setup and Cortex XSIAM.

The Cortex XSOAR extension for Visual Studio Code (compatible with both Cortex XSOAR and Cortex XSIAM) enables you to design and author scripts and integrations for Cortex XSIAM directly from VS Code. When writing code, the plugin provides you with auto-completion of Cortex XSIAM and Python functions. The extension also provides an easy-to-use set of demisto-sdk commands to format your packs, lint, and validate. The extension provides an easy virtual environment setup for Cortex XSIAM integrations and scripts.

Note

The content repository from GitHub must be cloned or forked. Do not change the default folder name, which is content. The Visual Studio Code extension must be run from inside the content repository folder. If you run the extension from a different folder, the command 'xsoar.updateDSDK error appears.

Prerequisites

• Python 3.9 and up
• VS Code

• Docker

  See the Visual Studio Code instructions for Docker installation.

Install the Visual Studio Code extension

Install the Visual Studio Code extension directly from the Visual Studio Code marketplace or use this link. If you are using a Windows machine, click CTRL+SHIFT+P and choose Connect to WSL.

Configurations

Cortex XSIAM recommends keeping the xsoar.autoFindProblems.readProblems configuration set to false, which is the default setting, for improved performance. When this configuration is set to true, it automatically runs demisto-sdk validate when saving your file.

Commands

All of the commands in the extension start with XSOAR. For example:

• XSOAR: Demisto-SDK Validate/Update Release Notes...: Runs the demisto-sdk commands.
• XSOAR: Configure XSOAR unit tests: Configures the integration unit tests.
• XSOAR: Configure XSOAR connection: Configures environment variables for demisto-sdk.

Environment setup

Remote development (Any OS)

To develop in a fully configured remote development environment, see instructions for a traditional development environment or a GitHub Codespace. You can also use a containerized development environment, which includes the Visual Studio Code extension by default.

Local development (Linux, MacOS, WSL2)

The VS Code extension supports setting up your development environment automatically. Run the command XSOAR: install local development environment from VS Code Command Pallete or by right-clicking the file.

If you want to install the dependencies manually, follow the instructions in this guide until the Bootstrap step.

Set up integrations and scripts environment

Each integration or script in Cortex XSIAM runs on a different environment and has different dependencies. This feature configures the integration or script and allows you to debug it and run unit tests. In addition, you can open the integration environment in a new workspace with a virtual environment, for auto-completion.

Usage

1. Navigate to the integration or script.
2. Right-click the integration/script and select Setup integration/script environment.
3. A dialog box appears allowing you to choose to the use the current workspace or to open a new one with a virtual environment. Note that using the current workspace is faster, but you may not have auto-completion for some integrations. Opening a new workspace takes longer, but you have auto-completion for all integrations. Both options allow you to debug your integration or script, run unit test, and identify problems from within the IDE.

Debugging

1. Setup integrations and scripts environment.
2. Read the Debugging using your IDE section.
3. Go to Run and Debug (⇧⌘D), and verify Docker: debug (<integration>) is selected.
4. Click on the green arrow or the F5 key to begin debugging.

Note

If during the installation one or more Python packages fails to install, the installation proceeds and creates the virtual environment with the packages that were installed.

Troubleshooting

Setup integration/script environment fails

• Verify Docker is running.
• Verify the Allow the default Docker socket to be used (requires password) option is enabled in Docker advanced settings.
• If Docker is running, follow instructions to prune unused Docker objects and/or sign in to Docker to avoid the Docker pull rate limit.

Which IDE should I use?

When it comes to an external IDE, you have multiple options. .

Cortex XSIAM offers a free Visual Studio Code extension that simplifies/automates tasks such as:

• Running unit tests
• Creating a blank integration or automation script
• Uploading/downloading your integration code to/from Cortex XSIAM

However, if you want to use a different IDE (for example Sublime, vi, emacs), some tasks must be performed manually. To automate them, you can use the Demisto SDK.

You can also write code directly in the Cortex XSIAM, but is not recommended if you want to contribute supported content. Check here for details.

Note

IDEs are used only for writing integrations and scripts, everything else (for example playbooks, dashboards, and layouts) should be developed in the Cortex XSIAM UI.

Once the resource is developed in the Cortex XSIAM UI, you can download it using demisto-sdk download -i "$NAME_OF_RESOURCE" or export it from the UI.

Which software development tools should I use?

While the basics of writing code and changing configuration options can be done in the Cortex XSIAM UI, for complex solutions and supported contributions you'll probably need a combination of both the Cortex XSIAM UI and other tools. See Content development environments for more information.

We recommend using Visual Studio Code with the Cortex XSOAR extension when you want to contribute content to the Marketplace. The Cortex XSOAR extension works with both Cortex XSOAR and Cortex XSIAM.

We recommend using the Cortex XSIAM UI when:

• Creating Playbooks.
• Creating non-code entities (everything but integrations and scripts), such as:
  • Alert fields, types and layouts
  • Indicator fields, types and layouts
  • Classifiers and mappers
  • Widgets
  • Dashboards
• Working on the properties of your integration/script (parameters, commands, arguments, and outputs) in the YAML file - this can also be done using Visual Studio Code extension.
• Testing the user experience for what you developed.

What programming languages do you support for integrations and scripts?

• Python

  Python is the preferred development language, since it provides a wider set of capabilities and tools. Cortex XSIAM supports Python 3, and new contributions must be developed in Python 3.7 or later.

• PowerShell

  Cortex XSIAM supports PowerShell integrations and scripts.

Which operating systems are supported for development?

The recommended OS for development is either macOS or Linux, as Bash and Docker are used in some validation/testing flows.

For Windows, you can either work with a Linux VM or use Windows Subsystem for Linux.

What license applies to the Cortex XSIAM content repository?

The Cortex XSIAM content repository has an MIT License.

Why is my CLA pending after I signed the agreement?

The CLA should be signed by all branch committers. The CLA bot will let you know the committers who have not yet signed the agreement by marking them with a red X.

If the missing user appears under one of your commits (can be checked by visiting the Commits tab in the PR), it probably means that one of your commits was done with this user. Try the following:

1. If you have the credentials for the missing user, try to log in and sign the CLA, then click the recheck button at the bottom of the CLA message.
2. Try to link your commits: Add the email address of the missing user to your GitHub email settings, then click the recheck button at the bottom of the CLA message.
3. If the missing user is not a real user or named Root, you need to open a new branch:
   1. In your local environment, manually copy the code you edited (usually you can copy the entire pack) to another location.
   2. Check out the master branch.
   3. Create a new branch.
   4. Paste the code from before into your new branch.
   5. Commit and push your new branch.
   6. Open a new Pull Request for the new branch.

4. If the license/CLA status check remains on Pending even though all contributors have accepted the CLA, you can recheck the CLA status by visiting the following link (replace [PRID] with your PR ID):

   https://cla-assistant.io/check/demisto/content?pullRequest=[PRID]

Important

Don't forget to close the old PR and delete the old branch.

You can find information about troubleshooting commits in the GitHub docs site Troubleshooting Guide.

Integrations and scripts enable seamless connections with other security tools, automate repetitive tasks, and provide customization for your organization's unique requirements. By leveraging these capabilities, cybersecurity teams can respond effectively to security events, reduce response time, and enhance overall security posture.

Integrations and scripts in Cortex XSIAM are stored in YAML files that include all the required information (metadata, code, images, etc.). All these files together are referred to as a Unified YAML file.

To better handle the files in the content repository, Python/Powershell scripts and integrations are stored in a directory structure, where the YAML files only contain the metadata and the code and artifacts live in separate files. This is required for running linting and unit testing of the code.

When an integration or script is exported from Cortex XSIAM using demisto-sdk download, the Unified YAML is automatically split into its components. When other components (such as playbooks, alert fields, and layouts) are downloaded, they are exported as is and automatically added to their respective folders.

When an integration or script is imported into Cortex XSIAM using demisto-sdk upload, the integration/script directory files are automatically assembled in the Unified YAML file that is uploaded.

Content developers usually work with the directory structure and not the unified file.

Each integration is stored in the Integrations directory with a unique name, and includes the following file types:

 .
├── <INTEGRATION-NAME>.py              // Integration / automation script Python code.
├── <INTEGRATION-NAME>_test.py         // Python unit test code.
├── <INTEGRATION-NAME>.yml             // Configuration YAML file.
├── <INTEGRATION-NAME>_image.png       // Integration PNG logo (for integrations only).
├── <INTEGRATION-NAME>_description.md  // Detailed instructions markdown file (for integrations only)
├── README.md                          // Integration / automation script documentation.

For example, the Cortex XDR integration is stored in Integrations/CortexXDRIR and contains the following files:

.Integrations   
│
└─── .CortexXDRIR
│    ├── CortexXDRIR.py
│    ├── CortexXDRIR_test.py
│    ├── CortexXDRIR.yml
│    ├── CortexXDRIR_image.png
│    ├── CortexXDRIR_description.md
│    ├── README.md

All the metadata of your integration is included in the YAML file. It is a key value set for your integration. When pushing content for public release, your YAML file must follow certain structural requirements to work properly. Scripts also have a metadata YAML file that follows a similar structure.

Cortex XSIAM integration YAML common fields

The commonfields section contains information the Cortex XSIAM server uses to identify your integration.

commonfields:
  id: New Integration
  version: -1

This section contains the following information.

Basic integration metadata

This section contains integration metadata.

name: MaxMind GeoIP2
display: MaxMind GeoIP2
category: Data Enrichment & Threat Intelligence
image: data:image/png;base64,**Base64 of Image Here**
description: Enriches IP addresses
detaileddescription: 'The MaxMind GeoIP2 integration allows you to query the MaxMind
  API service and retrieve a JSON of all details. '

It includes the following parameters:

Integration settings configuration

The configuration section specifies the integration settings configuration requirements that are necessary for the integration to operate.

configuration:
- display: API Key
  name: apikey
  defaultvalue: ""
  type: 0
  required: true
- display: Use system proxy
  name: proxy
  defaultvalue: ""
  type: 8
  required: false

It includes the following parameters.

Hide integration settings parameters

To hide integration parameters from the UI in all Marketplaces, set the optional hidden field to true.

To hide the parameter in specific content Marketplace versions, provide a list of marketplace version names.

• xsoar - Cortex XSOAR 6 and 8
• xsoar_on_prem - Cortex XSOAR 6
• xsoar_saas - Cortex XSOAR 8 Cloud and On-prem
• marketplacev2 - Cortex XSIARM
• xpanse - Cortex XPANSE

Integration configuration sections

An integration's configuration display is divided into the following sections to help users easily find parameters.

Connect parameters

Parameters required to connect to the product

• Name
• Server URL / URL address
• Classifier / Incident Type / Mapper section
• Username
• Password
• API key
• Other mandatory parameters

Advanced Connect parameters

Additional connect parameters

• Trust any certificate (not secure)
• Use system proxy settings
• Log level
• Run on single engine
• Any additional filters or non-mandatory parameters

Collect parameters

Parameters required to collect information from the product

• Fetch events / Do not fetch radio buttons or Fetch/Do not fetch indicators
• First fetch timestamp
• Number of events to fetch per fetch
• Do not use by default
• Indicator reputation
• Source reliability
• Traffic light protocol color

Advanced Collect parameters

Additional collect parameters

• Events fetch interval
• Indicator expiration method
• Feed fetch interval
• Bypass exclusion list
• Create relationships
• Any additional filters or non-mandatory parameters

Optimize parameters

This section contains parameters that do not belong to the Connect or Collect sections, such as Advanced Thresholds and Advanced Queries.

Add configuration sections to an integration YAML file

To add sections to your integrations:

1. Add the sectionOrder key to the YAML's root. This key should contain a list of sections available. Currently, the only supported section types are Connect, Collect, and Optimize.
2. Add the section key to each parameter in the configuration, with one of the sections listed above.
3. If the parameter should only be shown in the advanced settings, add the advanced:true key and value to it.

category: Analytics & SIEM
sectionOrder:
- Connect
- Collect
commonfields:
  id: GitLab Event Collector
  version: -1
configuration:
- display: Server URL
  name: url
  required: true
  type: 0
  section: Connect
- displaypassword: API Key
  additionalinfo: The API Key to use for connection.
  name: api_key
  required: true
  hiddenusername: true
  type: 9
  section: Connect
- display: Groups IDs
  name: group_ids
  required: false
  type: 0
  section: Collect
- display: First fetch timestamp (<number> <time unit>, for example, 12 hours, 7 days, 3 months, 1 year)
  name: after
  required: true
  defaultvalue: 1 day
  type: 0
  section: Collect
- display: Trust any certificate (not secure)
  name: insecure
  required: false
  type: 8
  section: Connect
  advanced: true
- display: Use system proxy settings
  name: proxy
  type: 8
  required: false
  section: Connect
  advanced: true

Configuration sections example

In the following example, you can see the advanced parameters remain hidden until the user expands the Advanced Settings section.

Integration script configuration

The script section is where the code resides.

script:
  script: |
    import requests
    import collections

    def explain_yaml():
        if user.understands is False:
            re_read_documentation()

  type: python
  subtype: python3
  dockerimage: demisto/python3:3.7.5.3066

It includes the following parameters.

Integration command configuration

The command section tells Cortex XSIAM what arguments are required for your command as well as what the outputs are.

  commands:
  - name: command-name
    arguments:
    - name: command-argument
      required: true
      default: false
      isArray: false
      secret: true
      description: This is a description for the argument
    outputs:
    - contextPath: Example.Sample.Name
      description: The name of the sample
      type: string
    - contextPath: Example.Sample.ID
      description: The ID for the sample
      type: string
    description: Sample description for the command-name function
  runonce: false

It includes the following parameters.

Command fields

Command argument fields

Command output fields

Integration version compatibility and tests

The last section of the YAML file provides Cortex XSIAM with information regarding what version is supported and tests.

fromversion: 6.5.0
tests:
  - Sample Integration Test

It includes the following parameters.

War Room entry types

Integration parameter types are used for configuring integration instances. When adding a parameter to an integration in Cortex XSIAM, you assign it a type. The parameter type affects the parameter behavior and interaction with the user. See Configuration in the Integration metadata YAML file for more information about how to set the parameter type.

Boolean integration parameter type

This parameter type creates a checkbox in the integration instance settings configuration in the UI. When the checkbox is checked, the value in the integration code is True. If the checkbox is not checked, the value is False.

The type number is 8.

Access: demisto.params().get('proxy')

Short text integration parameter type

This parameter type is used for short input parameters, such as server URLs, ports or queries. It creates a small text box in the integration instance settings configuration in the UI.

The type number is 0.

Access: demisto.params().get('url')

Long text integration parameter type

This parameter type is used for long text inputs, such as certificates. It creates a large text box in the integration instance settings configuration in the UI.

The type number is 12.

Access: demisto.params().get('cert')

Short encrypted integration parameter type

This parameter type is used for encrypted inputs, such as API tokens. This should not be used for username/password credentials. It creates a small text box for encrypted text, which is also stored encrypted in the database.

The type number is 4.

Access: demisto.params().get('token')

Long encrypted integration parameter type

This type of parameter is used for long encrypted inputs, such as certificates. It creates a text area with encrypted text. The text is also stored encrypted in the database.

The type number is: 14.

Access: demisto.params().get('cert')

Authentication integration parameter type

This parameter type is used for username/password credentials, with plain text username and an encrypted password. It supports retrieving credentials from the Cortex XSIAM credentials store (see the Cortex XSIAM support portal for more about the credentials store).

The type number is 9.

Access:

• Username: demisto.params().get('credentials', {}).get('identifier')
• Password: demisto.params().get('credentials', {}).get('password')

Single-select integration parameter type

This parameter type enables selecting a single input from a list of allowed inputs.

The type number is 15.

Access: demisto.params().get('log')

Multi-select integration parameter type

This parameter type enables selecting multiple inputs from a list of allowed inputs.

The type number is 16.

Access: demisto.params().get('sort')

Maintain integration parameter compatibility

Once a parameter is set in an integration instance settings configuration, it is saved to the Cortex XSIAM database. Before changing an existing parameter, consider the existing values to ensure backward compatibility. For example, when adding a parameter with a default value to an existing integration, add the default value in the code as well as the YAML file, as it is not added to existing instances.

The integration description file provides the supported integration use cases, and helps Cortex XSIAM users to easily configure an integration instance.

Tip

• Give as much information as you think the user needs to succeed, including permission levels, credentials, and keys.
• If there are permissions required on the integration level, list them.
• If commands have separate permissions, mention that, but document the required permission on the command level.
• Images can be added to integration description files.

Common integration description file use cases

• How to get credentials
• How to get API Key/secret
• How to get Application ID

Integration description file location

The description file should be placed with the rest of the integration's files.

For example, if the pack name is HelloWorld and the integration name is also HelloWorld, the description file path is:

~/.../content/Packs/HelloWorld/Integrations/HelloWorld/HelloWorld_description.md

Integration description file content

The description file contains details on how to configure an integration instance, together with the relevant details needed from the product that are important for configuration. The file content can include troubleshooting tips and advanced details for different configuration cases.

Note

This file should not be confused with the integration README file.

Integration description file example

This is the content of the HelloWorld_description.md file:

## Hello World
- This section explains how to configure the instance of HelloWorld in Cortex XSIAM.
- You can use the following API Key: `43ea9b2d-4998-43a6-ae91-aba62a26868c`

View integration description file content in Cortex XSIAM

The content of the description file is displayed in the Help tab next to the integration instance settings configurations:

Support level header YAML metadata key

The supportlevelheader key can be set to one of the following values to set the support level header in the content description:

• xsoar - The description specifies that Palo Alto Networks supports this integration.
• partner - The description specifies that this integration is partner supported and list the partner's contact information.
• community - The description specifies that this integration is community supported or lists the pack's author.

Set the support level header YAML metadata key

To set the key, open the YAML file for the integration in the same folder where the description file is located and add the supportlevelheader key with of the supported values listed above.

If the key is not set in the integration YAML, the support level header is set to the support key in the pack_metadata.json file.

Before choosing a logo for your integration, review the following requirements.

• Size: Up to 10KB
• Dimensions: 120x50 pixels
• Background: Transparent (no background color, no borders)
• Color: Black and white or color (no light colors, no reversed logo with white on black background)
• Format: PNG

Standardized code conventions ensure uniformity across all Cortex XSIAM integrations.

New integrations and scripts should follow these conventions. When working on small fixes and modifications to existing code, follow the conventions used in the existing code.

For example, see the HelloWorld integration and the Templates directory.

All new integrations and scripts should be written in Python 3.

Follow these Python code conventions for consistency and best practices.

Python integration and script code conventions

Python imports

Define imports and disable insecure warning at the top of the file.

import demistomock as demisto
from CommonServerPython import *
from CommonServerUserPython import *
''' IMPORTS '''

import json
import urllib3

# Disable insecure warnings
urllib3.disable_warnings()

Constants

Define constants in the file below the imports. Do not define global variables in the constants section.

''' CONSTANTS '''
DATE_FORMAT = "%Y-%m-%dT%H:%M:%SZ"

Important

Do NOT name constants as follows:

apiVersion = "v1"
url = demisto.params().get("url")

Python main function

Define the main function as follows:

1. Create the main function and extract all the integration parameters using demisto.params() in it.
2. Implement the _command function for each integration command, for example say_hello_command(client, demisto.args()).
3. Wrap the commands with try/except in the main to properly handle exceptions. The return_error() function receives error messages and returns error entries back into Cortex XSIAM. It also prints the full error to the Cortex XSIAM logs.
4. For logging, use the demisto.debug("write some log here") function.
5. In the main function, initialize the client instance and pass that client to _command functions.

def main():
    params = demisto.params()

    client = Client(params.get('insecure'),
                    params.get('proxy'))

    command = demisto.command()
    demisto.info(f'Command being called is {command}')
    # Switch case
    try:
        if demisto.command() == 'fetch-events':
            events, last_run = fetch_events_command(client)
            # we submit the indicators in batches
            send_events_to_xsiam(events=events, vendor='MyVendor', product='MyProduct')
        else:
            results = get_events_command(client)
            return_results(results)
    except Exception as e:
        raise Exception(f'Error in {SOURCE_NAME} Integration [{e}]')

Integration Client class

Follow these best practices for defining the Client class.

• The Client class should inherit from BaseClient, which is defined in CommonServerPython.
• The Client class should contain the _http_request function.
• The Client class should implement the third party service API.
• The Client class should contain all the necessary parameters to establish connection and authentication with the third party API.

class Client(BaseClient):
    """
    Client will implement the service API, should not contain Cortex XSIAM logic.
    Should do requests and return data
    """

    def get_ip_reputation(self, ip: str) -> Dict[str, Any]:
        """Gets the IP reputation using the '/ip' API endpoint

        :type ip: ``str``
        :param ip: IP address to get the reputation for

        :return: dict containing the IP reputation as returned from the API
        :rtype: ``Dict[str, Any]``
        """

        return self._http_request(
            method='GET',
            url_suffix=f'/ip',
            params={
                'ip': ip
            }
        )

    def get_alert(self, alert_id: str) -> Dict[str, Any]:
        """Gets a specific HelloWorld alert by id

        :type alert_id: ``str``
        :param alert_id: id of the alert to return

        :return: dict containing the alert as returned from the API
        :rtype: ``Dict[str, Any]``
        """

        return self._http_request(
            method='GET',
            url_suffix=f'/get_alert_details',
            params={
                'alert_id': alert_id
            }
        )

Client instance using an API key

api_key = demisto.params().get('apikey')

# get the service API url
base_url = urljoin(demisto.params()['url'], '/api/v1')

# if your Client class inherits from BaseClient, SSL verification is
# handled out of the box by it, just pass ``verify_certificate`` to
# the Client constructor
verify_certificate = not demisto.params().get('insecure', False)

headers = {
    'Authorization': f'Bearer {api_key}'
}

client = Client(
    base_url=base_url,
    verify=verify_certificate,
    headers=headers,
    proxy=proxy
)

Client instance using basic authentication

username = demisto.params().get('credentials', {}).get('identifier')
password = demisto.params().get('credentials', {}).get('password')

# get the service API url
base_url = urljoin(demisto.params()['url'], '/api/v1')

# if your Client class inherits from BaseClient, SSL verification is
# handled out of the box by it, just pass ``verify_certificate`` to
# the Client constructor
verify_certificate = not demisto.params().get('insecure', False)

client = Client(
    base_url=base_url,
    verify=verify_certificate,
    auth=(username, password),
    proxy=proxy
)

HTTP call retries

sleep can cause performance issues so do not use it in the code. Instead, use the retry mechanism implemented in the BaseClient with the _http_request function retries and backoff_factor arguments.

Integration command functions

Follow these best practices for defining the command functions.

• Each integration command should have a corresponding _command function.
• Each _command function should use Client class functions.
• Each _command function should be unit testable. This means you should avoid using global functions such as demisto.results(), return_error(), or return_results().
• The _command function will receive the Client instance and the args (demisto.args() dictionary).
• The _command function will return an instance of the CommandResults class.
• To return results to the War Room, in the Main use return_results(say_hello_command(client, demisto.args()).

def say_hello_command(client, args):
    """
    Returns Hello {somename}

    Args:
        client: HelloWorld client
        args: all command arguments

    Returns:
        Hello {someone}

        readable_output: This will be presented in Warroom - should be in markdown syntax - human readable
        outputs: Dictionary/JSON - saved in incident context in order to be used as input for other tasks in the
                 playbook
        raw_response: Used for debugging/troubleshooting purposes - will be shown only if the command executed with
                      raw-response=true
    """
    name = args.get('name')

    result = client.say_hello(name)

    # readable output will be in markdown format - https://www.markdownguide.org/basic-syntax/
    readable_output = f'## {result}'
    outputs = {
        'name': name,
        'hello': result
    }
    
    results = CommandResults(
        outputs_prefix='HelloWorld.Result',
        outputs_key_field='name',
        outputs=outputs,
        
        readable_output=readable_output,
        raw_response=result
    )

    return results


def main():
    """
    SOME CODE HERE...
    """
    try:
        client = Client(
            base_url=server_url, 
            verify=verify_certificate, 
            auth=(username, password),
            proxy=proxy)
        
        """
        SOME CODE HERE...
        """
        if demisto.command() == 'helloworld-say-hello':
            return_results(say_hello_command(client, demisto.args()))

    # Log exceptions
    except Exception as e:
        return_error(f'Failed to execute {demisto.command()} command. Error: {str(e)}')

IOC reputation commands

There are two implementation requirements for reputation commands (!file, !email, !domain, !url, and !ip) that are enforced by checks in the Demisto SDK.

• The reputation command's argument of the same name must have default set to True.
• The reputation command's argument of the same name must have isArray set to True.

For more details on these two command argument properties, see Integration metadata YAML file.

Integration test-module command

The test-module executes when users click the Test button in the integration instance settings page.

If the test module returns the string "ok" then the test will be green (success). Any other string will be red.

if demisto.command() == 'test-module':
    # This is the call made when pressing the integration Test button.
    result = test_module(client)
    return_results(result)

def test_module(client):
    """
    Returning 'ok' indicates that the integration works like it suppose to. Connection to the service is successful.

    Args:
        client: HelloWorld client

    Returns:
        'ok' if test passed, anything else will fail the test
    """

    result = client.say_hello('DBot')
    if 'Hello DBot' == result:
        return 'ok'
    else:
        return 'Test failed because ......'

Fetch-events integration command

The fetch-events function initiates a fetch events request to specific external product endpoint(s) using the relevant chosen parameters, and sends the fetched events to the Cortex XSIAM dataset. If the integration instance setting is configured to Fetch events, then this command is executed at the specified Events Fetch Interval. By default, it runs every minute to retrieve and import events into Cortex XSIAM.

Follow these best practices for defining the fetch-events function.

• Must be unit testable.
• Should receive the last_run param instead of executing the demisto.getLastRun() function.
• Should return next_run back to Main, instead of executing demisto.setLastRun() inside the fetch-events function.
• Should return incidents back to main instead of executing demisto.incidents() inside the fetch-events function.

def get_events(client, alert_status, args):
    limit = args.get('limit', 50)
    from_date = args.get('from_date')
    events = client.search_events(
        prev_id=0,
        alert_status=alert_status,
        limit=limit,
        from_date=from_date,
    )
    hr = tableToMarkdown(name='Test Event', t=events)
    return events, CommandResults(readable_output=hr)

Event collector parsing rules

When developing an event collector, set the Parsing Rules within the collector code. The most common parsing rule is the _time system property which indicates the event time from the remote system. For example, if we use the following events as an example:

 {
    "id": "1234",
    "message": "New user added 'root2'",
    "type": "audit",
    "op": "add",
    "result": "success",
    "host_info": {
      "host": "prod-01",
      "os": "Windows"
    },
    "created": "1676764803"
  }

We see that the created event property is a str representation of a timestamp (without milliseconds). However, The _time system property expects the result to be an str in format %Y-%m-%dT%H:%M:%S.000Z. So we can can transform it using the timestamp_to_datestring function from CommonServerPython.

from datetime import datetime
from CommonServerPython import *

#  ...
  events: List[Dict[str, Any]] = get_events()

  for event in events:
    event["_time"] = timestamp_to_datestring(float(event.get("created")) * 1000)

# ...

To verify that the parsing rule has been applied and is working as expected, run an XQL search to compare the _time and created fields:

dataset = "MyVendor_MyProduct_raw" | 
fields
  _time,
  created

Python exceptions and errors

Follow these best practices for defining exceptions and errors.

• Wrap your command block in a "Try-Catch" to avoid unexpected issues.
• Raise exceptions in the code where needed, but in the Main catch them and use the return_error function. This enables acceptable error messages in the War Room instead of stack trace.
• If the return_error second argument is error, you can pass an Exception object.

• You can use demisto.error("some error message") to log your error.

  def main():
      try:
          if demisto.command() == 'test-module':
              test_get_session()
              return_results('ok')
      
          if demisto.command() == 'atd-login':
              return_results(get_session_command(client, demisto.args()))
      
      except Exception as e:
          return_error(f'Failed to execute {demisto.command()} command. Error: {str(e)}')
  

Integration command unit tests

Every integration command must be covered with a unit test.

Python variable naming

When naming variables, use Snake case, not Pascal case or camel case.

Integration command outputs

See Context and outputs.

Follow Context Standards when naming indicator outputs

Link integration command context

Linking context together prevents a command from overwriting existing data or from creating duplicate entries in the context.

Example to link context:

ec = ({
    'URLScan(val.URL && val.URL == obj.URL)': cont_array,
    'URL': url_array,
    'IP': ip_array,
    'Domain': dom_array
})

In this example, val.URL && val.URL == obj.URL links the results retrieved from this integration with results already in the context where the value of the URL is the same. For more information about linking syntax and Cortex XSIAM see Transform Language (DT).

Integration logging

You can pass information to the logs to assist future debugging.

To post to the logs:

demisto.debug('DEBUG level - This is some information we want in the logs')
demisto.info('INFO level - This is some information we want in the logs')
demisto.error('ERROR level - This is some information we want in the logs')

You can also use the @logger decorator in Cortex XSIAM. When the decorator is placed at the top of each function, the logger prints the function name as well as all the argument values to the LOG.

@logger
def get_ip(ip):
    ip_data = http_request('POST', '/v1/api/ip' + ip)
    return ip_data

Important

Do not print sensitive data to the log. When an integration is ready to be used as part of a public release (meaning you are done debugging it), always remove print statements that are not absolutely necessary.

Date and time formats

Cortex XSIAM does not use epoch time for customer facing results (for example context and human readable). If the API you are working with requires the time format to be in epoch, then convert the date string into epoch as needed. Where possible, use the human readable format of the date %Y-%m-%dT%H:%M:%S.

time_epoch = 499137720
formatted_time = timestamp_to_datestring(time_epoch, "%Y-%m-%dT%H:%M:%S")
print(formatted_time)
>>> '1985-10-26T01:22:00'

Note

If the response returned is in epoch, best practice is to convert it to %Y-%m-%dT%H:%M:%S.

Pagination in integration commands

When working on a command that supports pagination (usually has API parameters like page and/or page size) with a maximal page size enforced by the API, best practice is to create a command that supports two different use cases with the following three integer arguments:

• page
• page size
• limit

Pagination use cases

• Manual Pagination: The user wants to control the pagination by using the page and page size arguments, usually as part of a wrapper script for the command. The command passes the page and page size values on to the API request. If the limit argument is also provided, it is redundant and should be ignored.
• Automatic Pagination: Useful when the user prefers to work with the total number of results returned from the playbook task rather than implementing a wrapper script that works with pages. In this case, the limit argument aggregates results by iterating over the necessary pages from the first page until collecting all the needed results. This implies a pagination loop mechanism is implemented behind the scenes. For example, if the limit value received is 250 and the maximal page size enforced by the API is 100, the command performs 3 API calls (pages 1,2, and 3) to collect the 250 requested results. Note that when a potentially large number of results may be returned and the user wants to perform filters and/or transformers on them, we still recommend creating a wrapper script for the command for better performance.

Pagination recommendations

• Page Tokens - If an API supports page tokens, instead of the more common 'limit' and 'offset'/'skip' as query parameters:
  • The arguments that are implemented are: limit, page_size , and next_token.

  • The retrieved next_token should be displayed in human readable output and in the context. It is a single node in the context and overwritten with each command run.

    {
      "IntegrationName":
      {
          "Object1NextToken": "TOKEN_VALUE",
          "Object2NextToken": "TOKEN_VALUE",
          "Objects1": [],
          "Objects2": []
      }
    }
    

• Standard argument defaults: limit is a default of '50' in the YAML. page_size should be defaulted in the code to '50', if only page was provided.
• There should be no maximum value for the limit argument. This means that users should be able to retrieve as many records as they need in a single command execution.
• When an integrated API doesn't support pagination parameters at all - then only limit will be applied, and implemented internally in the code. An additional argument will be added to allow the user to retrieve all results by overriding the default limit: all_result=true.
• If the API supports only 'limit' and 'offset'/'skip' as query parameters, then all 3 standard Cortex XSIAMpagination arguments should be implemented.

Integration credentials

When working on integrations that require user credentials (such as username/password and API token/key) best practice is to use the credentials parameter type.

Username and password credentials

• In the UI:

  

• In the YAML file:

  - display: Username
    name: credentials
    type: 9
    required: true
  

• In the code:

  params = demisto.params()
  username = params.get('credentials', {}).get('identifier')
  password = params.get('credentials', {}).get('password')
  

• In demistomock.py:

  return {
          "base_url": "...",
          "credentials": {"identifier": "<username>",
                          "password": "<password>"},
          ...
      }
  

API token or key credentials

• In the UI:

  

• In the YAML file:

  - displaypassword: API Token
    name: credentials
    type: 9
    required: false
    hiddenusername: true
  

Using the credentials parameter type is recommended (even when working with API token/key) because it enables using the Cortex XSIAM credentials vault feature when configuring the integration for the first time.

Cortex XSIAM CommonServerPython helper functions

Check the script helper for common predefined functions to facilitate script development. The following are some examples.

fileResult

Returns a file to the War Room by using the following syntax:

filename = "sample.txt",
file_content = "hello sample"

return_results(fileResult(filename, file_content))

You can specify the file type, but it defaults to "None" when not provided.

create_indicator_result_with_dbotscore_unknown

Used when the API response to an indicator is not found and returns a verdict with an unknown score (0).

A generic response is returned to the War Room and to the context path by using the following syntax:

indicator = "www.google.com",
indicator_type = DBotScoreType.URL
reliability = DBotScoreReliability.C

return_results(create_indicator_result_with_dbotscore_unknown(indicator, indicator_type, reliability))

The War Room result shows:

The Context Path shows:

If the integration has a reliability it should be noted, but it defaults to None when not provided.

Note

• If the indicator type is CustomIndicator, you need to provide the context_prefix argument.
• If the indicator type is Cryptocurrency, you need to provide the address_type argument.

tableToMarkdown

Transforms your JSON, dict, or other table into a Markdown table.

name = 'Sample Table'
t = {'first':'Foo', 'second': 'bar', 'third': 'baz', 'fourth': ''}
headers = ['Input', 'Output']
tableToMarkdown(name, t, headers=headers, removeNull=True)

This sample code snippet creates this table:

In the War Room, tables appear as follows:

Add table headers

Use headerTransform to convert existing keys into formatted headers.

t = {'header_1': 'a1', 'header_2': 'b1', 'header_3': 'c1'}
tableToMarkdown('headerTransform Example', t, headerTransform=underscoreToCamelCase)
|Header1|Header2|Header3|
|---|---|---|
| a1 | b1 | c1 |
#
You may also use ```removeNull``` to remove empty columns in the table. Default is False.
```python
headers = ['header_1', 'header_2']
data = {
    'header_1': 'foo',
}
tableToMarkdown('removeNull Example', data, removeNull=True, headers=headers)
|header_1|
|---|
| foo |

You may also use ```metadata``` to add text above the table as a secondary title.
#
Use the ```url_keys``` argument to specify a list of keys whose value in the MD table should be a clickable url. This list may contain keys of inner dicts\list of dicts in the data given to the tableToMarkdown function.

For example, for the following data with some of the keys nested:

d = { "id": "23", "url1": " https://url1.com", "result": { "files": [ { "filename": "Screen.jpg", "url2": "https://url2.com" } ] }, "links": { "url3": "https://url2.com" } }

and using ` url_keys=('url1', 'url2', 'url3')

` ```python tableToMarkdown('Data Table', d, headers=('id', 'url1', 'result', 'links'), headerTransform=string_to_table_header, url_keys=('url1', 'url2', 'url3')) `

The resulting table is:

Format date fields

Use the date_fields argument (list) of date fields to format date values to human-readable output.

data = [
    {
        "docker_image": "demisto/python3",
        "create_time": '1631521313466'
    }
]
tableToMarkdown('tableToMarkdown date_fields example', data, headers=["docker_image", "create_time"],
                date_fields=['create_time'])
|---|---|
| demisto/python3 | 2021-09-13 08:21:53 |

#
Use the ```json_transform_mapping``` argument (Dict[str, JsonTransformer]), to map between a header key to the corresponding JsonTransformer.
```python
data_with_list = {
  "Machine Action Id": "5b38733b-ed80-47be-b892-f2ffb52593fd",
  "MachineId": "f70f9fe6b29cd9511652434919c6530618f06606",
  "Hostname": "desktop-s2455r9",
  "Status": "Succeeded",
  "Creation time": "2022-02-17T08:20:02.6180466Z",
  "Commands": [
    {
      "startTime": null,
      "endTime": "2022-02-17T08:22:33.823Z",
      "commandStatus": "Completed",
      "errors": ["error1", "error2", "error3"],
      "command": {
        "type": "GetFile",
        "params": [
          {
            "key": "Path",
            "value": "test.txt"
          }
        ]
      }
    },
    {
      "startTime": null,
      "endTime": "2022-02-17T08:22:33.823Z",
      "commandStatus": "Completed",
      "errors": [],
      "command": {
        "type": "GetFile",
        "params": [
          {
            "key": "Path",
            "value": "test222.txt"
          }
        ]
      }
    }
  ]
}
table = tableToMarkdown("tableToMarkdown test", data_with_list,
            json_transform_mapping={'Commands': JsonTransformer(keys=('commandStatus', 'command'))})

For example, this code snippet generates the following table:

Transform JSON data into a table

Use the is_auto_json_transform argument (bool), to auto-transform a complex JSON.

nested_data_example = {
  "name": "Active Directory Query",
  "changelog": {
    "1.0.4": {
      "path": "",
      "releaseNotes": "\n#### Integrations\n##### Active Directory Query v2\nFixed an issue where the ***ad-get-user*** command caused performance issues because the *limit* argument was not defined.\n",
      "displayName": "1.0.4 - R124496",
      "released": "2020-09-23T17:43:26Z"
    }
  },
  "nested": {
    "item1": {
      "a": 1,
      "b": 2,
      "c": 3,
      "d": 4
    }
  }
}
table = tableToMarkdown("tableToMarkdown test", nested_data_example,
                    headers=['name', 'changelog', 'nested'],
                    is_auto_json_transform=True)

For example, this code snippet generates the following table:

demisto.command()

demisto.command() ties a function to a command in Cortex XSIAM, for example:

    if demisto.command() == 'ip':
        ip_search_command()

demisto.params()

demisto.params() returns a dictionary of parameters for a given integration to grab global variables in an integration, for example:

    APIKEY = demisto.params().get('apikey')
    ACCOUNT_ID = demisto.params().get('account')
    MODE = demisto.params().get('mode')
    INSECURE = demisto.params().get('insecure')

demisto.args()

demisto.args() returns a dictionary of arguments for a given command to get non-global variables, for example:

    url = demisto.args().get('url')

This argument can be seen in the integration settings as shown below:

After the command is executed, the arguments are displayed in the War Room as part of the command, for example:

IndicatorsTimeline

IndicatorTimeline is an optional object, applicable only for commands that operate on indicators. It is a dictionary (or list of dictionaries) in the following format:

{

'Value': '127.0.0.1',

'Message': 'System marked the indicator 127.0.0.1 as Benign',

'Category': 'Benign'

}

When IndicatorTimeline data is returned in an entry, the timeline section of the indicator whose value was noted in the timeline data will be updated and is viewable in the indicator's view page in Cortex XSIAM.

Choose a category for timeline data

Any Cortex XSIAM integration command or script that returns timeline data may include the Category value. If not given, when returning timeline data from a Cortex XSIAM integration or script, the value will be Integration Update or Automation Update accordingly.

Include timeline data in War Room entries

A timeline object should be included when a command operates on an indicator. For example, if the command returns a DBotScore or entities as described in context standards documentation to the entry context. A common case is reputation commands, such as !ip, !url, and !file. When implementing these commands in integrations, timeline data should be included in the returned entry.

For example:

results = [
    CommandResults(
        outputs_prefix='VirusTotal.IP',
        outputs_key_field='Address',
        outputs={
            'Address': '8.8.8.8',
            'ASN': 12345
        }
    ), 
    CommandResults(
        outputs_prefix='VirusTotal.IP',
        outputs_key_field='Address',
        outputs={
            'Address': '1.1.1.1',
            'ASN': 67890
        }
    )]
return_results(results)

timeline = IndicatorsTimeline(
      indicators=[args.get('ips')],
      message='Important to note'
)

timeline = IndicatorsTimeline(
      indicators=[args.get('ips')],
      category='Some category',
      message='IP was blocked in Checkpoint'
)

CommandResults

This object returns outputs. It represents an entry in the War Room. A string representation of an object must be parsed into an object before being passed into the field.

CommandResults example

results = CommandResults(
    outputs_prefix='VirusTotal.IP',
    outputs_key_field='Address',
    outputs={
        'Address': '8.8.8.8',
        'ASN': 12345
    },
    indicators_timeline = timeline
)
return_results(results)

For more information on how to return results, see Context and outputs.

return_results

return_results() calls demisto.results(). It accept either a list or single item of the CommandResults object or any object that demisto.results can accept. Use return_results to return the CommandResults object or a basic string.

For example:

results = CommandResults(
    outputs_prefix='VirusTotal.IP',
    outputs_key_field='Address',
    outputs={
        'Address': '8.8.8.8',
        'ASN': 12345
    }
)
return_results(results)

results = CommandResults(
    outputs_prefix='VirusTotal.IP',
    outputs_key_field='Address',
    outputs={
        'Address': '8.8.8.8',
        'ASN': 12345
    },
    indicators_timeline = timeline
)
return_results(results)

return_results('Hello World')

return_error

Returns an error entry to the War Room and calls sys.exit(), meaning the script will stop.

return_error(message="error has occurred: API Key is incorrect", error=ex)

It produces an error in the War Room, for example:

CommandRunner

CommandRunner is a class for executing multiple commands, which returns all valid results together with a human readable summary table of successful commands and commands that return errors.

To use this functionality, create a list of commands using the CommandRunner.Command, and then call CommandRunner.run_commands_with_summary(commands).

The following are CommandRunner.Command arguments.

For example, the following code snippet returns all the results of all commands, including a human readable summary table.

commands = [CommandRunner.Command('command1', {'arg': 'val'},
            CommandRunner.Command('command2', [{'arg1': 'val2'}, {'arg2': 'val2'}])),
            CommandRunner.Command(['command3', 'command4'], [{'arg1': 'val2'}, {'arg2': 'val2'}]),
            CommandRunner.Command('command5', {}, instance='some_instance', brand='some_brand')]

return_results(CommandRunner.run_commands_with_summary(commands))

AutoExtract

As part of CommandResults() there is an argument called ignore_auto_extract, which prevents the built-in indicator extraction feature from enriching IPs, URLs, files, and other indicators from the result.

By default, ignore_auto_extract is set to False.

For example:

results = CommandResults(
    outputs_prefix='VirusTotal.IP',
    outputs_key_field='Address',
    outputs={
        'Address': '8.8.8.8',
        'ASN': 12345
    },
    indicators_timeline = timeline,
    ignore_auto_extract = True
)
return_results(results)

PowerShell integrations and scripts are executed using PowerShell Core. PowerShell Core v6.2 and higher is supported.

PowerShell integration and script development

PowerShell Docker images

Similar to Python, PowerShell integrations and scripts run in a Docker container. All of the Docker images that support PowerShell are named with a prefix of either demisto/powershell or demisto/pwsh. If you need to create a new image follow the instructions at demisto/dockerfiles project: https://github.com/demisto/dockerfiles.

PowerShell integration directory structure

Similar to Python, PowerShell integrations and scripts should follow the same directory structure as Python integrations and scripts, with one difference: unit test files must be named: <IntegrationFileName>.Tests.ps1, following the Pester unit testing naming convention. You can use demisto-sdk split to convert an exported PowerShell integration or script to the correct directory structure. For more information, see the Demisto SDK.

PowerShell linting with PSScriptAnalyzer

PSScriptAnalyzer is used for linting and static code analysis of PowerShell integrations and scripts. If you receive a false positive from the Analyzer, you can suppress the rule by decorating the function/script with SuppressMessageAttribute. Specify a Justification in the attribute as to why the suppression is necessary. An example usage of suppression can be seen in CommonServerPowerShell.ps1. For more information about PSScriptAnalyzer suppression, see the PSScriptAnalyzer documentation .

PowerShell integration unit testing

The Python unit testing guidelines also apply for PowerShell. Unit tests should avoid performing communication with external APIs and should instead use mocking when possible. Testing actual interaction with external APIs should be performed via Test Playbooks. For running unit tests we use Pester.

Import CommonServerPowerShell.ps1

Your code must import CommonServerPowerShell.ps1 by adding the following to the beginning of the file:

. $PSScriptRoot\CommonServerPowerShell.ps1

When the integration or script code is unified by demisto-sdk for deployment to the instance the import line is automatically removed.

Use Main in integration and script code

When writing unit tests you import the integration or script file from the *.Tests.ps1 file. Therefore, the file must be written so that it will not execute when it is imported. This can be done with a simple Main function which is called depending on how the file was executed. Adding the following code ensures the script is not run when imported by the unit tests:

# Execute Main when not in Tests
if ($MyInvocation.ScriptName -notlike "*.Tests.ps1") {
    Main
}

Write PowerShell unit tests

All unit tests should be written in a separate PowerShell file named <IntegrationFileName>.Tests.ps1. The unit test file should import the integration or script code file by adding the following line at the beginning of the file:

. $PSScriptRoot\<IntegrationFileName>.ps1

Group related unit tests using the Describe block. Use Context for grouping tests that use the same mock logic. Write your tests using the It command. Example unit tests can be seen for the VerifyJSON script. For more details, see the Pester documentation.

Mock PowerShell functions

Pester supports mocking PowerShell functions. You can mock any function defined in CommonServerPowerShell.ps1 and functions included in standard PowerShell and imported modules. Pester doesn't support mocking object methods. This includes methods of the $demisto object. You can, however, modify the $demisto object properties in a test. For example, you can set the ContextArgs property to control the return of $demisto.Args() method. Example code:

$demisto.ContextArgs = @{arg1 = 'val1' }

In addition, you can mock functions called by the $demisto object. For example, you can mock DemistoServerLog which is called by the $demisto object methods: Info, Debug, Error. Example of mocking can be seen for the VerifyJSON script script. See more information about mocking with Pester.

Run PowerShell linting and tests

Run with Docker and Demisto SDK

The build runs the unit tests within the Docker image that the integration/script runs with. We recommend using this method to run linting and test as it uses the same environment (Docker container) with all modules and operating system dependencies that are used by the integration/script. To run both linting and testing run: demisto-sdk pre-commit -i <path to code directory>.

For example: demisto-sdk pre-commit -i Packs/Legacy/Scripts/VerifyJSON

Note

You can skip PSScriptAnalyzer or unit testing using the command line parameters --no-pwsh-analyze and --no-pwsh-test.

Run from the PowerShell command line

As a prerequisite, verify you have installed Pester, PSScriptAnalyzer and all dependent modules.

Run demisto-sdk pre-commit -i ... to copy CommonServerPowerShell.ps1 and demistomock.ps1 to the integration/script directory. Enter the pwsh console and go to the integration/script directory.

To run unit tests use Pester: Invoke-Pester.

To run PSScriptAnalyzer: Invoke-ScriptAnalyzer -Path <code file>

Check the command help for information on how to specify which tests to run.

Sample output:

VS Code for PowerShell development

We recommend using VS Code as your PowerShell editor. The PowerShell Extension developed by Microsoft comes with built-in support for PSScriptAnalyzer and Pester unit testing (including debugging).

Sample output of PSScriptAnalyzer in VS Code alerting about an unused variable:

Sample debug session using VS Code:

When naming integrations, commands, arguments and outputs, use the following conventions:

Cortex XSIAM naming conventions

• Integration parameters

  Use brief and clear names with snake_case. Example: min_severity

• Command names

  Use kebab-case with the structure !vendor-action-object. Example: !helloworld-get-alert

• Command arguments

  Use brief and clear names with snake_case. Example: alert_id.

• Command outputs

  Use PascalCase with the structure Vendor.Object.data for the Vendor and Object block. Example: HelloWorld.Alert.owner.name

  After the Vendor and Object blocks, use the same format as your product's API, but do not include any spaces or dots in the key names, as dots are interpreted as object separators. For example, Cortex XSIAM correctly parses:

  ```json
  {
    "HelloWorld": {
      "Alert": {
        "owner": {
            "name": "Francesco",
            "email": "francesco@cortex.local"
        }
      }
    }
  }
  ```
  as:
  ```
  HelloWorld.Alert.owner.name: "Francesco"
  HelloWorld.Alert.owner.email: "francesco@cortex.local"
  ```
  

  Cortex XSIAM does NOT correctly parse:

  ```json
      {
    "HelloWorld": {
      "Alert": {
        "owner.name": "Francesco",
        "owner.email": "francesco@cortexl.local"
      }
    }
  }
  ```
  

Each integration has parameters that are configured by the customers when they configure an instance on their Cortex XSIAM system. Integration parameters should be named using snake_case.

Cortex XSIAM integration parameter guidance

Supported integration parameter types

• Short text (type 0)
• Encrypted (type 4)
• Boolean Checkbox (type 8)
• Credentials (type 9)
• Long text (type 12)
• Single select (type 15)
• Multi-select (type 16)

Connection and authentication parameters

These parameters determine how Cortex XSIAM connects to the third-party API.

• url

  The URL Cortex XSIAM should connect to. Always expose this parameter even in SaaS applications, as SaaS applications can have variations as well (tenant name or federal cloud, for example).

• api_key

  In most cases, credentials are needed to authenticate to the API you want to interact with. Many times this is in the form of an API key, a secure and unique identifier that is stored in Cortex XSIAM and used somewhere in your code (i.e. to populate HTTP headers) to craft the requests. Sometimes APIs use different authentication parameters: credentials, tokens, client_id and client_secret combination, and so on. Capture all the required parameters that allow a machine-to-machine authentication between Cortex XSIAM and your API.

Note

If you are using authentication mechanisms based on short-lived access tokens such as JSON Web Tokens (JWT) and long-lived refresh tokens, read more about the Integration cache.

• proxy

  Boolean to determine whether to use the system proxy setting. You don't need to handle proxy settings in your code, but you should set environment variables accordingly based on this Boolean.

• insecure

  Boolean to determine whether to avoid verifying SSL certificates.

Event collector integration parameters

If your integration fetches events, you should define what type of entities in the third-party product you are connecting to and are retrieving. Every product has its own nomenclature: they might be called Alerts, Incidents, etc. For the purposes of this topic, we assume they are called Alerts in the third-party product, and they are mapped 1:1 to Cortex XSIAM alerts.

Many products are very verbose, and have the potential to generate many alerts of different types, with different levels of severity. Each alert could have a status (i.e. open or resolved) as well as attributes. SOC analysts might be interested only in a subset of the incoming Alerts. When they configure your integration in Cortex XSIAM, they expect to find parameters that allow them to filter and determine which alerts should generate incidents and which alerts should be discarded.

Common filters for fetching incidents include:

• Maximum number of alerts per fetch

  The parameter name must be max_fetch. It is a good practice to limit the number of incidents you retrieve every time you fetch, in order to avoid overloading Cortex XSIAM by running many playbooks at the same time. Customers should be allowed to set this value as an integration parameter. Recommended default is 10 to 20, with a maximum of 50.

• Severity

  Many SOCs prefer to retrieve only incidents with specific severities, from third-party systems, and to avoid importing lower severity ones incidents. The integration settings should allow customers to choose the severity of the incidents they want to retrieve. This can be done either using a multi-select, or a single-select where they specify the lowest severity level they want to retrieve.

• Type

  Third-party products typically generate different types of alerts/events/issues/incidents. Often SOCs are interested only in a specific subset of types they want to handle automatically through Cortex XSIAM. This integration setting allows end users to specify which types of alerts they want to fetch from the third-party platform. If the types are of finite and known cardinality, we recommend using a multi-select. If the types are not known up front or may change over time, we recommend using a comma-separated text input, with a link in the details to your product documentation where an up-to-date list of those types is available.

• First fetch

  The parameter name must be first_fetch. When customers configure the integration for the first time, they usually want to retrieve incidents that happened in the past. This common setting is used to specify how far back in time they want to retrieve incidents the first time the integration runs. You can check the HelloWorld integration implementation code for more details.

If the API you are integrating with also supports a query interface using free-form text (i.e. a specific query language implemented in the product), you can also add another parameter (usually called query) that gives users more freedom to generate alerts in Cortex XSIAM based on a specific query. This gives more flexibility to the users and supports more advanced use cases for your integration. The convention is that the query parameter overrides other parameters such as severity and type, as we assume that only advanced users use the query option.

There are additional required parameters for integrations that fetch incidents. You don't need to handle them in your code, but they must be correctly defined in your integration YAML file. You can view the updated list.

Additional integration parameters

Your product is unique, and so are the parameters you might need to add to the integration. Besides connectivity and fetch parameters, you can add more parameters as you see fit. In general, add parameters whenever you want the users to specify settings that are common across several integration commands.

An example is a Threat Intel reputation threshold. In this scenario, you are creating an integration that asks for reputation about network assets (IP addresses, URLs and domains), using different commands (!ip, !url and !domain). Your API returns a score value between 0 and 100 to determine whether the asset is malicious. The higher the score, the higher the chance the asset is bad. Cortex XSIAM reports whether an indicator is good or bad using the concept of DBotScore with a discrete set of values: 0 means unknown, 1 good, 2 suspicious and 3 bad. To map the score that your API returns (0-100) to a DBotScore, you typically define a threshold above which the asset is considered malicious. The value of the threshold is usually a number that you provide as a default (60, for example) but the end user should be able to override the default. Threshold value should be common across all of the different reputation commands (!ip, !url and !domain) of your integration. For this reason, adding threshold as an additional integration parameter is a good practice. Users can set the threshold once and don't have to specify it manually every time to invoke a reputation command. You can still add an optional argument to each command to override the integration parameter if needed.

The context is a map (dictionary) / JSON object that is created for each incident and is used to store structured results from integration commands and automation scripts. Context keys are strings and the values can be strings, numbers, objects, and arrays/lists.

The main use of the context is to pass data between playbook tasks. One task stores its output in the context and another task reads that output from the context and uses it.

For example, the ThreatStream integration includes the threatstream-analysis-report command, which returns the report of a file or URL that was submitted to the sandbox.

Cortex XSIAM integration context and outputs

REST API response example

{
    "Category": "File",
    "Duration": 68,
    "Network": [
        {
            "UdpDestination": "8.8.8.8",
            "UdpPort": 53,
            "UdpSource": "192.168.2.4"
        },
        {
            "UdpDestination": "192.168.2.4",
            "UdpPort": 65324,
            "UdpSource": "8.8.8.8"
        },
        {
            "UdpDestination": "192.168.2.4",
            "UdpPort": 54896,
            "UdpSource": "8.8.8.8"
        }
    ],
    "ReportID": "413336",
    "Started": "2019-05-30 14:05:25",
    "Verdict": "Benign"
}

Integration YAML command outputs

In the integration YAML file, the command outputs are defined BrandName.Object.PropertyName.

For each output entry, there are three fields:

• Context Path - Dot notation representation of the path to access the context.
• Description - Short description of what this context entry represents.
• Type - The type of value that is located at the path. Enables Cortex XSIAM to format the data correctly.

YAML output definitions

outputs:
- contextPath: ThreatStream.Analysis.ReportID
  description: The ID of the report submitted to the sandbox.
  type: String
- contextPath: ThreatStream.Analysis.Category
  description: The report category.
  type: String
- contextPath: ThreatStream.Analysis.Started
  description: Detonation start time.
  type: String
- contextPath: ThreatStream.Analysis.Duration
  description: Duration of the detonation (in seconds).
  type: Number
- contextPath: ThreatStream.Analysis.Network.UdpSource
  description: The source of UDP.
  type: String
- contextPath: ThreatStream.Analysis.Network.UdpDestination
  description: The destination of UDP.
  type: String
- contextPath: ThreatStream.Analysis.Network.UdpPort
  description: The port of the UDP.
  type: String
- contextPath: ThreatStream.Analysis.Verdict
  description: The verdict of the sandbox detonation.
  type: String

Return command outputs in code

report_id = '413336'

response_from_api = {
    "Category": "File",
    "Duration": 68,
    "Network": [
        {
            "UdpDestination": "8.8.8.8",
            "UdpPort": 53,
            "UdpSource": "192.168.2.4"
        },
        {
            "UdpDestination": "192.168.2.4",
            "UdpPort": 65324,
            "UdpSource": "8.8.8.8"
        },
        {
            "UdpDestination": "192.168.2.4",
            "UdpPort": 54896,
            "UdpSource": "8.8.8.8"
        }
    ],
    "ReportID": "413336",
    "Started": "2019-05-30 14:05:25",
    "Verdict": "Benign"
} # assume that we get this response from the service

command_results = CommandResults(
    outputs_prefix='ThreatStream.Analysis',
    outputs_key_field='ReportID',
    outputs=response_from_api
)
return_results(command_result)

Note

• The code must match the context path outputs specified in the YAML file.
• You can output the API response as is to the context as a raw value, under the brand name key. You do not need to modify the API response and map it to human-readable keys.
• Avoid using dot and space characters in the context path keys.

Integration context output use cases

Important

When setting integration_name with the vendor value, it must match the name of the integration as defined in the YAML file.

Return integration command data

alerts = [
    {
        'id': 100,
        'name': 'alert1'
    },
    {
        'id': 200,
        'name': 'alert2'
    }
]

results = CommandResults(
    outputs_prefix='PrismaCompute.Alert',
    outputs_key_field='id',
    outputs=alerts
)
return_results(results)

YAML output definition

outputs:
- contextPath: PrismaCompute.Alert.id
  description: 'The alert id'
  type: Number
- contextPath: PrismaCompute.Alert.name
  description: 'The alert name'
  type: String

Markdown command output

Results

Incident context data

{
  "PrismaCompute": {
    "Alert": [
      {
        "id": 100,
        "name": "alert1"
      },
      {
        "id": 200,
        "name": "alert2"
      }
    ]
  } 
}

Return results with custom Markdown

alerts = [
    {
        'id': 100,
        'name': 'alert1'
    },
    {
        'id': 200,
        'name': 'alert2'
    }
]

markdown = '### This is the Header\n'
markdown += tableToMarkdown('Table Title', alerts, headers=['id', 'name'])

results = CommandResults(
    readable_output=markdown,
    outputs_prefix='PrismaCompute.Alert',
    outputs_key_field='id',
    outputs=alerts
)
return_results(results)

Custom Markdown results

This it the Header

Table Title

Return data with multiple unique identifier fields

Note

Key fields are used to determine whether the data is updated or added as new.

alerts = [
    {
        'id': 100,
        'name': 'alert1'
    },
    {
        'id': 200,
        'name': 'alert2'
    }
]

results = CommandResults(
    outputs_prefix='PrismaCompute.Alert',
    outputs_key_field=['id', 'name'],
    outputs=alerts
)
return_results(results)

Return a potentially malicious file

Note

Potentially malicious file - e.g. email attachment

file_entry = fileResult(filename='file.txt', data='file content')
return_results(file_entry)

YAML definition

outputs:
- contextPath: File.Size
  description: The size of the file.
  type: Number
- contextPath: File.SHA1
  description: The SHA1 hash of the file.
  type: String
- contextPath: File.SHA256
  description: The SHA256 hash of the file.
  type: String
- contextPath: File.Name
  description: The name of the file.
  type: String
- contextPath: File.SSDeep
  description: The SSDeep hash of the file.
  type: String
- contextPath: File.EntryID
  description: The entry ID of the file.
  type: String
- contextPath: File.Info
  description: File information.
  type: String
- contextPath: File.Type
  description: The file type.
  type: String
- contextPath: File.MD5
  description: The MD5 hash of the file.
  type: String
- contextPath: File.Extension
  description: The file extension.
  type: String

Return an informational file

Note

Non-malicious files - e.g. reports

file_entry = fileResult(filename='file.txt', data='file content', file_type=EntryType.ENTRY_INFO_FILE)
return_results(file_entry)

YAML Definition

outputs:
- contextPath: InfoFile.Name
  description: FileName
  type: string
- contextPath: InfoFile.EntryID
  description: The EntryID of the report
  type: string
- contextPath: InfoFile.Size
  description: File Size
  type: number
- contextPath: InfoFile.Type
  description: File type e.g. "PE"
  type: string
- contextPath: InfoFile.Info
  description: Basic information of the file
  type: string

Return IP reputation results

For an integration usage example of how the code implements the indicator reputation command, see AutofocusV2 integration.

ip_reputation_from_autofocus = {
    'indicator': '5.5.5.5',
    'asn': '12345',
    'confidence': 95
}

if ip_reputation_from_autofocus['confidence'] >= 90:
    score = Common.DBotScore.BAD
elif ip_reputation_from_autofocus['confidence'] >= 50:
    score = Common.DBotScore.SUSPICIOUS
else:
    score = Common.DBotScore.GOOD

dbot_score = Common.DBotScore(
    indicator='5.5.5.5',
    indicator_type=DBotScoreType.IP,
    integration_name='Autofocus',
    score=score
)

ip = Common.IP(
    ip='5.5.5.5',
    asn=ip_reputation_from_autofocus['asn'],
    dbot_score=dbot_score
)

results = CommandResults(
    outputs_prefix='Autofocus.IP',
    outputs_key_field='indicator',
    outputs=ip_reputation_from_autofocus,
    indicator=ip
)

return_results(results)

Context data - as stored in the incident context data:

{
    "Autofocus": {
        "IP": [
            {
                "indicator": "5.5.5.5", 
                "confidence": 95, 
                "asn": "12345"
            }
        ]
    }
    "IP": [
        {
            "ASN": "12345", 
            "Address": "5.5.5.5"
        }
    ], 
    "DBotScore": [
        {
            "Vendor": "Autofocus", 
            "Indicator": "5.5.5.5", 
            "Score": 2, 
            "Type": "ip"
        }
    ]
}

YAML definition:

outputs:
- contextPath: Autofocus.IP.indicator
  description: IP address
  type: String
- contextPath: Autofocus.IP.condidence
  description: Indicator condidence between 0-99
  type: Number
- contextPath: Autofocus.IP.asn
  description: ASSN description
  type: String

# This is standard context output - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#ip
- contextPath: IP.Address
  description: IP address
  type: String
- contextPath: IP.ASN
  description: 'The autonomous system name for the IP address, for example: AS8948.'
  type: String

# Reputation commands usually should return DBotScore object - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#dbot-score
- contextPath: DBotScore.Indicator
  description: The indicator that was tested.
  type: String
- contextPath: DBotScore.Type
  description: The indicator type.
  type: String
- contextPath: DBotScore.Vendor
  description: The vendor used to calculate the score.
  type: String
- contextPath: DBotScore.Score
  description: The actual score.
  type: Number

Markdown

Results

Return domain reputation results

For an integration usage example of how the code implements the indicator reputation command, see AutofocusV2 integration.

domain_raw = get_domain_from_autofocus('google.com')

if domain_raw.get('score') > 90:
    score = Common.DBotScore.BAD
elif domain_raw.get('score') > 60:
    score = Common.DBotScore.SUSPICIOUS
else:
    score = Common.DBotScore.GOOD

dbot_score = Common.DBotScore(
    indicator='google.com',
    indicator_type=DBotScoreType.DOMAIN,
    integration_name='Autofocus v2',
    score=score
)

domain = Common.Domain(
    domain='google.com',
    dns=domain_raw.get('dnssec'),
    creation_date=domain_raw.get('creation_date'),
    positive_detections=domain_raw.get('positive_detections'),
    detection_engines=domain_raw.get('detection_engines'),
    sub_domains=domain_raw.get('sub_domains'),
    domain_status=domain_raw.get('status'),
    name_servers=domain_raw.get('name_servers'),
    registrar_name=domain_raw.get('registrar'),
    expiration_date=domain_raw.get('expiration_date'),
    dbot_score=dbot_score
)

results = CommandResults(
    outputs_prefix='Autofocus.Domain',
    outputs_key_field='domain',
    outputs=domain_raw,
    indicator=domain
)

return_results(results)

YAML definition

# Reputation commands usually should return DBotScore object - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#dbot-score
- contextPath: DBotScore.Indicator
  description: The indicator that was tested.
  type: String
- contextPath: DBotScore.Type
  description: The indicator type.
  type: String
- contextPath: DBotScore.Vendor
  description: The vendor used to calculate the score.
  type: String
- contextPath: DBotScore.Score
  description: The actual score.
  type: Number

# This is standard context output - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#ip
- contextPath: Domain.Name
  description: 'The domain name, for example: "google.com".'
  type: String
- contextPath: Domain.CreationDate
  description: The date that the domain was created.
  type: Date
- contextPath: Domain.DNS
  description: A list of IP objects resolved by DNS.
  type: String
- contextPath: Domain.WHOIS.NameServers
  description: Name servers of the domain.
  type: String
- contextPath: Domain.WHOIS.Registrar.AbuseEmail
  description: The email address of the contact for reporting abuse.
  type: Unknown
- contextPath: Domain.WHOIS.Registrar.AbusePhone
  description: The phone number of contact for reporting abuse.
  type: Unknown
- contextPath: Domain.WHOIS.Registrar.Name
  description: 'The name of the registrar, for example: "GoDaddy".'
  type: String
- contextPath: Domain.WHOIS.ExpirationDate
  description: The expiration date of the domain.
  type: Date
- contextPath: Domain.WHOIS.DomainStatus
  description: The status of the domain.
  type: Unknown


- contextPath: AutofocusV2.Domain.address
  description: Domain admin address.
  type: String
- contextPath: AutofocusV2.Domain.city
  description: Domain admin city.
  type: String
- contextPath: AutofocusV2.Domain.country
  description: Domain admin country.
  type: String
- contextPath: AutofocusV2.Domain.creation_date
  description: Domain creation date.
  type: Date
- contextPath: AutofocusV2.Domain.dnssec
  description: DNSSEC status.
  type: String
- contextPath: AutofocusV2.Domain.domain
  description: The domain name.
  type: String
- contextPath: AutofocusV2.Domain.domain_name
  description: Domain name options.
  type: String
- contextPath: AutofocusV2.Domain.emails
  description: Contact emails.
  type: String
- contextPath: AutofocusV2.Domain.expiration_date
  description: Expiration date.
  type: Date
- contextPath: AutofocusV2.Domain.name
  description: Domain admin name.
  type: String
- contextPath: AutofocusV2.Domain.name_servers
  description: Name server.
  type: String
- contextPath: AutofocusV2.Domain.org
  description: Domain organization.
  type: String
- contextPath: AutofocusV2.Domain.referral_url
  description: Referral URL.
  type: Unknown
- contextPath: AutofocusV2.Domain.registrar
  description: Domain registrar.
  type: String
- contextPath: AutofocusV2.Domain.score
  description: Reputation score from HelloWorld for this domain (0 to 100, where higher
    is worse).
  type: Number
- contextPath: AutofocusV2.Domain.state
  description: Domain admin state.
  type: String
- contextPath: AutofocusV2.Domain.status
  description: Domain status.
  type: String
- contextPath: AutofocusV2.Domain.updated_date
  description: Updated date.
  type: Date
- contextPath: AutofocusV2.Domain.whois_server
  description: WHOIS server.
  type: String
- contextPath: AutofocusV2.Domain.zipcode
  description: Domain admin zipcode.
  type: Unknown

Context data - as stored in the incident context data:

{
    "Domain": {
        "CreationDate": [
            "1997-09-15 04:00:00", 
            "1997-09-15 00:00:00"
        ], 
        "Name": "google.com", 
        "DNS": "unsigned", 
        "WHOIS": {
            "NameServers": [
                "NS1.GOOGLE.COM", 
                "NS2.GOOGLE.COM", 
                "NS3.GOOGLE.COM", 
                "NS4.GOOGLE.COM", 
                "ns2.google.com", 
                "ns4.google.com", 
                "ns3.google.com", 
                "ns1.google.com"
            ], 
            "Registrar": {
                "AbuseEmail": null, 
                "AbusePhone": null, 
                "Name": "MarkMonitor, Inc."
            }, 
            "ExpirationDate": [
                "2028-09-14 04:00:00", 
                "2028-09-13 00:00:00"
            ], 
            "DomainStatus": [
                "clientDeleteProhibited https://icann.org/epp#clientDeleteProhibited", 
                "clientTransferProhibited https://icann.org/epp#clientTransferProhibited", 
                "clientUpdateProhibited https://icann.org/epp#clientUpdateProhibited", 
                "serverDeleteProhibited https://icann.org/epp#serverDeleteProhibited", 
                "serverTransferProhibited https://icann.org/epp#serverTransferProhibited", 
                "serverUpdateProhibited https://icann.org/epp#serverUpdateProhibited", 
                "clientUpdateProhibited (https://www.icann.org/epp#clientUpdateProhibited)", 
                "clientTransferProhibited (https://www.icann.org/epp#clientTransferProhibited)", 
                "clientDeleteProhibited (https://www.icann.org/epp#clientDeleteProhibited)", 
                "serverUpdateProhibited (https://www.icann.org/epp#serverUpdateProhibited)", 
                "serverTransferProhibited (https://www.icann.org/epp#serverTransferProhibited)", 
                "serverDeleteProhibited (https://www.icann.org/epp#serverDeleteProhibited)"
            ]
        }
    }, 
    "DBotScore": {
        "Vendor": "Autofocus v2", 
        "Indicator": "google.com", 
        "Score": 2, 
        "Type": "domain"
    }, 
    "Autofocus": {
        "Domain": {
            "updated_date": [
                "2019-09-09 15:39:04", 
                "2019-09-09 08:39:04"
            ], 
            "status": [
                "clientDeleteProhibited https://icann.org/epp#clientDeleteProhibited", 
                "clientTransferProhibited https://icann.org/epp#clientTransferProhibited", 
                "clientUpdateProhibited https://icann.org/epp#clientUpdateProhibited", 
                "serverDeleteProhibited https://icann.org/epp#serverDeleteProhibited", 
                "serverTransferProhibited https://icann.org/epp#serverTransferProhibited", 
                "serverUpdateProhibited https://icann.org/epp#serverUpdateProhibited", 
                "clientUpdateProhibited (https://www.icann.org/epp#clientUpdateProhibited)", 
                "clientTransferProhibited (https://www.icann.org/epp#clientTransferProhibited)", 
                "clientDeleteProhibited (https://www.icann.org/epp#clientDeleteProhibited)", 
                "serverUpdateProhibited (https://www.icann.org/epp#serverUpdateProhibited)", 
                "serverTransferProhibited (https://www.icann.org/epp#serverTransferProhibited)", 
                "serverDeleteProhibited (https://www.icann.org/epp#serverDeleteProhibited)"
            ], 
            "domain": "google.com", 
            "name": null, 
            "dnssec": "unsigned", 
            "city": null, 
            "expiration_date": [
                "2028-09-14 04:00:00", 
                "2028-09-13 00:00:00"
            ], 
            "domain_name": [
                "GOOGLE.COM", 
                "google.com"
            ], 
            "creation_date": [
                "1997-09-15 04:00:00", 
                "1997-09-15 00:00:00"
            ], 
            "whois_server": "whois.markmonitor.com", 
            "state": "CA", 
            "registrar": "MarkMonitor, Inc.", 
            "referral_url": null, 
            "address": null, 
            "name_servers": [
                "NS1.GOOGLE.COM", 
                "NS2.GOOGLE.COM", 
                "NS3.GOOGLE.COM", 
                "NS4.GOOGLE.COM", 
                "ns2.google.com", 
                "ns4.google.com", 
                "ns3.google.com", 
                "ns1.google.com"
            ], 
            "org": "Google LLC", 
            "country": "US", 
            "emails": [
                "abusecomplaints@markmonitor.com", 
                "whoisrequest@markmonitor.com"
            ], 
            "zipcode": null, 
            "score": 76
        }
        
        
    }
}

Return URL reputation results

For an integration usage example of how the code implements the indicator reputation command, see AutofocusV2 integration.

url_arg = 'https://www.ynetto.co.il'
url_raw_response = {
    'url': 'https://www.ynetto.co.il',
    'verdict': 'Malicious',
    'detection_engines': 10,
    'positive_engines': 10
}

score = Common.DBotScore.GOOD
if url_raw_response.get('verdict') == 'Malicious':
    score = Common.DBotScore.BAD

dbot_score = Common.DBotScore(
    indicator=url_arg,
    indicator_type=DBotScoreType.URL,
    integration_name='Virus Total',
    score=score
)

url = Common.URL(
    url=url_arg,
    detection_engines=url_raw_response.get('detection_engines'),
    positive_detections=url_raw_response.get('positive_engines'),
    dbot_score=dbot_score
)

results = CommandResults(
    outputs_prefix='VirusTotal.URL',
    outputs_key_field='url',
    outputs=url_raw_response,
    indicator=url
)

return_results(results)

YAML definition

# Reputation commands usually should return DBotScore object - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#dbot-score
outputs:
- contextPath: DBotScore.Indicator
  description: The indicator that was tested.
  type: String
- contextPath: DBotScore.Type
  description: The indicator type.
  type: String
- contextPath: DBotScore.Vendor
  description: The vendor used to calculate the score.
  type: String
- contextPath: DBotScore.Score
  description: The actual score.
  type: Number

# Reputation commands usually should return DBotScore object - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#url
- contextPath: URL.Data
  description: The URL
  type: String
- contextPath: URL.DetectionEngines
  description: The total number of engines that checked the indicator.
  type: String
- contextPath: URL.PositiveDetections
  description: The number of engines that positively detected the indicator as malicious.
  type: String
- contextPath: URL.Malicious.Vendor
  description: The vendor reporting the URL as malicious.
  type: String
- contextPath: URL.Malicious.Description
  description: A description of the malicious URL.
  type: String

- contextPath: VirusTotal.URL.url
  description: The URL
  type: String
- contextPath: VirusTotal.URL.verdict
  description: Verdict can be Malicious or Benign
  type: String
- contextPath: VirusTotal.URL.detection_engines
  description: Number of engines
  type: Number
- contextPath: VirusTotal.URL.positive_engines
  description: Number of positive engines
  type: Number

Context data - as stored in the incident context data:

{
    "URL": {
        "Data": "https://www.ynetto.co.il",
        "DetectionEngines": 10,
        "PositiveDetections": 10,
        "Malicious": {
            "Vendor": "Virus Total",
            "Description": null
        }
    },
    "DBotScore": {
        "Indicator": "https://www.ynetto.co.il",
        "Type": "url",
        "Vendor": "Virus Total",
        "Score": 3
    },
    "VirusTotal": {
        "URL": {
            "url": "https://www.ynetto.co.il",
            "verdict": "Malicious",
            "detection_engines": 10,
            "positive_engines": 10
        }
    }
}

Return file hash reputation results

For an integration usage example of how the code implements the indicator reputation command, see AutoFocus v2 integration or Crowd Strike Malquery.

md5 = '9498ff82a64ff445398c8426ed63ea5b'
hash_reputation_response = {
    "md5": "9498ff82a64ff445398c8426ed63ea5b",
    "permalink": "https://www.virustotal.com/file/8b2e701e91101955c73865589a4c72999aeabc11043f712e05fdb1c17c4ab19a/analysis/1587134153/",
    "positives": 58,
    "resource": "9498FF82A64FF445398C8426ED63EA5B",
    "response_code": 1,
    "scan_date": "2020-04-17 14:35:53",
    "scan_id": "8b2e701e91101955c73865589a4c72999aeabc11043f712e05fdb1c17c4ab19a-1587134153",
    "sha1": "36f9ca40b3ce96fcee1cf1d4a7222935536fd25b",
    "sha256": "8b2e701e91101955c73865589a4c72999aeabc11043f712e05fdb1c17c4ab19a",
    "total": 70,
    "verbose_msg": "Scan finished, information embedded"
}

score = Common.DBotScore.GOOD
if hash_reputation_response.get('positives') > 20:
    score = Common.DBotScore.BAD
if hash_reputation_response.get('positives') > 3:
    score = Common.DBotScore.SUSPICIOUS


dbot_score = Common.DBotScore(
    indicator=md5,
    indicator_type=DBotScoreType.FILE,
    integration_name='Virus Total',
    score=score,
    malicious_description=hash_reputation_response.get('verbose_msg')
)

file = Common.File(
    md5=md5,
    sha1=hash_reputation_response.get('sha1'),
    sha256=hash_reputation_response.get('sha256'),
    dbot_score=dbot_score
)

results = CommandResults(
    outputs_prefix='VirusTotal.File',
    outputs_key_field='md5',
    outputs=hash_reputation_response,
    indicator=file
)

return_results(results)

YAML definition

outputs:
# Reputation commands usually should return DBotScore object - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#file
- contextPath: File.Name
  description: The full file name (including file extension).
  type: String
- contextPath: File.MD5
  description: The MD5 hash of the file.
  type: String
- contextPath: File.SHA1
  description: The SHA1 hash of the file.
  type: String
- contextPath: File.SHA256
  description: The SHA256 hash of the file.
  type: String
- contextPath: File.Malicious.Vendor
  description: The vendor that reported the file as malicious.
  type: String
- contextPath: File.Malicious.Description
  description: A description explaining why the file was determined to be malicious.
  type: String
  
# Reputation commands usually should return DBotScore object - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#dbot-score
- contextPath: DBotScore.Indicator
  description: The indicator that was tested.
  type: String
- contextPath: DBotScore.Type
  description: The indicator type.
  type: String
- contextPath: DBotScore.Vendor
  description: The vendor used to calculate the score.
  type: String
- contextPath: DBotScore.Score
  description: The actual score.
  type: Number
  
- contextPath: VirusTotal.File.md5
  description: The MD5 hash of the file.
  type: String
- contextPath: VirusTotal.File.permalink
  description: Link to the file report
  type: String
- contextPath: VirusTotal.File.positives
  description: Number of positive engines
  type: Number
- contextPath: VirusTotal.File.resource
  description: The resource
  type: String
- contextPath: VirusTotal.File.response_code
  description: Response code, it is a number between 1-10
  type: Number
- contextPath: VirusTotal.File.scan_date
  description: Scan date of a format 2010-05-15 03:38:44
  type: Date
- contextPath: VirusTotal.File.scan_id
  description: Scan ID
  type: String
- contextPath: VirusTotal.File.sha1
  description: The SHA1 hash of the file.
  type: String
- contextPath: VirusTotal.File.sha256
  description: The SHA256 hash of the file.
  type: String
- contextPath: VirusTotal.File.total
  description: Total number of engines
  type: Number
- contextPath: VirusTotal.File.verbose_msg
  description: Verbose message about the hash
  type: String

Context data - as stored in the incident context data:

{
    "File": {
        "MD5": "9498ff82a64ff445398c8426ed63ea5b",
        "SHA1": "36f9ca40b3ce96fcee1cf1d4a7222935536fd25b",
        "SHA256": "8b2e701e91101955c73865589a4c72999aeabc11043f712e05fdb1c17c4ab19a"
    },
    "DBotScore": {
        "Indicator": "9498ff82a64ff445398c8426ed63ea5b",
        "Type": "file",
        "Vendor": "Virus Total",
        "Score": 2
    },
    "VirusTotal": {
        "File": {
            "md5": "9498ff82a64ff445398c8426ed63ea5b",
            "permalink": "https://www.virustotal.com/file/8b2e701e91101955c73865589a4c72999aeabc11043f712e05fdb1c17c4ab19a/analysis/1587134153/",
            "positives": 58,
            "resource": "9498FF82A64FF445398C8426ED63EA5B",
            "response_code": 1,
            "scan_date": "2020-04-17 14:35:53",
            "scan_id": "8b2e701e91101955c73865589a4c72999aeabc11043f712e05fdb1c17c4ab19a-1587134153",
            "sha1": "36f9ca40b3ce96fcee1cf1d4a7222935536fd25b",
            "sha256": "8b2e701e91101955c73865589a4c72999aeabc11043f712e05fdb1c17c4ab19a",
            "total": 70,
            "verbose_msg": "Scan finished, information embedded"
        }
    }
}

Return CVE reputation results

For an integration usage example of how the code implements the indicator reputation command, see CVE Search v2.

cve_arg = 'CVE-2015-1653'

cve_raw_response = {
    "Modified": "2018-10-12T22:08:00",
    "Published": "2015-04-14T20:59:00",
    "assigner": "cve@mitre.org",
    "cvss": 4.3,
    "cvss-time": "2018-10-12T22:08:00",
    "cwe": "CWE-79",
    "id": "CVE-2015-1653",
    "references": [
        "http://www.securitytracker.com/id/1032111",
        "https://docs.microsoft.com/en-us/security-updates/securitybulletins/2015/ms15-036"
    ],
    "summary": "Cross-site scripting (XSS) vulnerability in Microsoft ",
}

cve = Common.CVE(
    id=cve_arg,
    cvss=cve_raw_response.get('cvss'),
    description=cve_raw_response.get('summary'),
    published=cve_raw_response.get('Published'),
    modified=cve_raw_response.get('Modified')
)

results = CommandResults(
    outputs_prefix='CVEMitre.CVE',
    outputs_key_field='id',
    outputs=cve_raw_response,
    indicator=cve
)

return_results(results)

YAML definition

outputs:
- contextPath: CVE.ID
  description: 'The ID of the CVE, for example: CVE-2015-1653'
  type: String
- contextPath: CVE.CVSS
  description: 'The CVSS of the CVE, for example: 10.0'
  type: String
- contextPath: CVE.Published
  description: The timestamp of when the CVE was published.
  type: Date
- contextPath: CVE.Modified
  description: The timestamp of when the CVE was last modified.
  type: Date
- contextPath: CVE.Description
  description: A description of the CVE.
  type: String

Context data - as stored in the incident context data:

{
    "CVE": {
        "ID": "CVE-2015-1653",
        "CVSS": 4.3,
        "Published": "2015-04-14T20:59:00",
        "Modified": "2018-10-12T22:08:00",
        "Description": "Cross-site scripting (XSS) vulnerability in Microsoft "
    },
    "CVEMitre": {
        "CVE": {
            "Modified": "2018-10-12T22:08:00",
            "Published": "2015-04-14T20:59:00",
            "assigner": "cve@mitre.org",
            "cvss": 4.3,
            "cvss-time": "2018-10-12T22:08:00",
            "cwe": "CWE-79",
            "id": "CVE-2015-1653",
            "references": [
                "http://www.securitytracker.com/id/1032111",
                "https://docs.microsoft.com/en-us/security-updates/securitybulletins/2015/ms15-036"
            ],
            "summary": "Cross-site scripting (XSS) vulnerability in Microsoft "
        }
    }
}

Return custom indicator results

For more information, see CustomIndicatorDemo. For a usage example of the CustomIndicator helper class, see CustomIndicatorDemo;.

score = Common.DBotScore.GOOD
 indicator_value = 'custom_value'
 dbot_score = Common.DBotScore(
     indicator=indicator_value,
     indicator_type=DBotScoreType.CUSTOM,
     integration_name='DummyIntegration',
     score=score
 )
 data = {
     'param1': 'value1',
     'param2': 'value2',
 }
 custom_indicator = Common.CustomIndicator(
     indicator_type='MyCustomIndicator',
     dbot_score=dbot_score,
     value=indicator_value,
     data=data,
     context_prefix='custom',
 )
 return CommandResults(
     readable_output='custom_value',
     outputs=result,
     outputs_prefix='Demo.Result',
     outputs_key_field='test_key_field',
     indicator=custom_indicator
 )

Context data - as stored in the incident context data:

{
    "DBotScore":
    [
        {
            "Indicator": "custom_value",
            "Score": 1,
            "Type": "MyCustomIndicator",
            "Vendor": "CustomIndicatorDemo"
        }
    ],
    "Demo.Result":
    {
        "dummy": "test"
    },
    "custom":
    [
        {
            "value": "custom_value",
            "param1": "value1",
            "param2": "value2"
        }
    ]
}

YAML definition

   outputs:
    - contextPath: Demo.Result.dummy
      description: The command's output
      type: String
    - contextPath: custom.param1
      description: custom data field of the indicator
      type: String
    - contextPath: custom.param2
      description: custom data field of the indicator
      type: String
    - contextPath: custom.value
      description: value of the indicator
      type: String
    - contextPath: DBotScore.Indicator
      description: The indicator value
      type: String
    - contextPath: DBotScore.Type
      description: The indicator type.
      type: String
    - contextPath: DBotScore.Vendor
      description: The vendor used to calculate the score.
      type: String
    - contextPath: DBotScore.Score
      description: The actual score.
      type: Number

Return multiple indicator results

For an integration usage example of how the code implements the indicator reputation command, see MispV3. In case you need to return multiple indicators (i.e. IPs) in the same call, you should return a list of CommandResults, as shown in the following example.

ip_reputations_from_autofocus = [
    {
      'indicator': '5.5.5.5',
      'asn': '12345',
      'confidence': 95
    },
    {
      'indicator': '4.4.4.4',
      'asn': '54321',
      'confidence': 73
    }
]

command_results_list: List[CommandResults] = []

for ip_reputation in ip_reputations_from_autofocus:
    if ip_reputation['confidence'] >= 90:
        score = Common.DBotScore.BAD
    elif ip_reputation['confidence'] >= 50:
        score = Common.DBotScore.SUSPICIOUS
    else:
        score = Common.DBotScore.GOOD

    dbot_score = Common.DBotScore(
        indicator=ip_reputation['indicator'],
        indicator_type=DBotScoreType.IP,
        integration_name='Autofocus',
        score=score
    )

    ip = Common.IP(
        ip=ip_reputation['indicator'],
        asn=ip_reputation['asn'],
        dbot_score=dbot_score
    )

    command_results_list.append(CommandResults(
        outputs_prefix='Autofocus.IP',
        outputs_key_field='indicator',
        outputs=ip_reputation,
        indicator=ip
    ))

return_results(command_results_list)

Context data - as stored in the incident context data:

{
    "Autofocus": {
        "IP": [
            {
                "indicator": "5.5.5.5", 
                "confidence": 95, 
                "asn": "12345"
            },
            {
                "indicator": "4.4.4.4", 
                "confidence": 73, 
                "asn": "54321"
            }
        ]
    },
    "IP": [
        {
            "ASN": "12345", 
            "Address": "5.5.5.5"
        },
        {
            "ASN": "54321", 
            "Address": "4.4.4.4"
        }
    ], 
    "DBotScore": [
        {
            "Vendor": "Autofocus", 
            "Indicator": "5.5.5.5", 
            "Score": 2, 
            "Type": "ip"
        },
        {
            "Vendor": "Autofocus", 
            "Indicator": "4.4.4.4", 
            "Score": 1, 
            "Type": "ip"
        }
    ]
}

YAML definition

outputs:
- contextPath: Autofocus.IP.indicator
  description: IP address
  type: String
- contextPath: Autofocus.IP.condidence
  description: Indicator condidence between 0-99
  type: Number
- contextPath: Autofocus.IP.asn
  description: ASSN description
  type: String

# This is standard context output - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#ip
- contextPath: IP.Address
  description: IP address
  type: String
- contextPath: IP.ASN
  description: 'The autonomous system name for the IP address, for example: AS8948.'
  type: String

# Reputation commands usually should return DBotScore object - https://xsoar.pan.dev/docs/integrations/context-standards-mandatory#dbot-score
- contextPath: DBotScore.Indicator
  description: The indicator that was tested.
  type: String
- contextPath: DBotScore.Type
  description: The indicator type.
  type: String
- contextPath: DBotScore.Vendor
  description: The vendor used to calculate the score.
  type: String
- contextPath: DBotScore.Score
  description: The actual score.
  type: Number

Markdown

Results

DT (Cortex XSOAR Transform Language)

In the above example, we observe the entry context using (val.ReportID == obj.ReportID). This works to tie together related entry context objects. In this instance, we are using the value of the ReportID key as the unique identifier to search through the existing context and link related objects. This prevents data from being overwritten as well as further enriches an existing entry with more information. Learn more about linking context.

Cortex XSIAM organizes incident data in a tree of objects called the incident context. Any integration commands or scripts that run add data into the context at a predefined location. This also applies to commands that run within playbook execution.

The context stores the results from every integration command and every automation script that runs. It is a JSON storage for each incident. 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. For example, a command like !whois query="cnn.com" returns the data and store the results into the context.

When building new integrations the entry context should be returned according to this standard in addition to the vendor specific context.

The structure should be:

  {
  "Object": {
    ...
  },
  "Vendor": {
    "Object": {
      ...
    }
  }

}

Some standard objects are mandatory and enforced in the code, and some are recommended.

Mandatory Cortex XSIAM context standards

There are standard context schema used for the system indicators and the DBot Score object. You do not need to manually output this in your code, instead, use the builtin classes as described in context use cases.

File

The following is the format for a File. File here refers to the file indicator or a binary file that could potentially be malicious, and might be checked for reputation or sent to a sandbox.

"File": {
        "Name": "STRING, The full file name (including file extension).",
        "EntryID": "STRING, The ID for locating the file in the War Room.",
        "Size": "INT, The size of the file in bytes.",
        "MD5": "STRING, The MD5 hash of the file.",
        "SHA1": "STRING, The SHA1 hash of the file.",
        "SHA256": "STRING, The SHA256 hash of the file.",
        "SHA512": "STRING The SHA512 hash of the file.",
        "SSDeep": "STRING, The ssdeep hash of the file (same as displayed in file entries).",
        "Extension": "STRING, The file extension, for example: 'xls'.",
        "Type": "STRING, The file type, as determined by libmagic (same as displayed in file entries).",
        "Hostname": "STRING, The name of the host where the file was found. Should match Path.",
        "Path": "STRING, The path where the file is located.",
        "Company": "STRING, The name of the company that released a binary.",
        "ProductName": "STRING, The name of the product to which this file belongs.",
        "DigitalSignature": {
            "Publisher": "STRING, The publisher of the digital signature for the file."
        },
        "Actor": "STRING, The actor reference.",
        "Tags": "STRING, Tags of the file.",
        "Signature": {
            "Authentihash": "STRING, The authentication hash.",
            "Copyright": "STRING, Copyright information.",
            "Description": "STRING, A description of the signature.",
            "FileVersion": "STRING, The file version.",
            "InternalName": "STRING, The internal name of the file.",
            "OriginalName": "STRING, The original name of the file."            
        },
        "Malicious": {
             "Vendor": "STRING, The vendor that reported the file as malicious.",
             "Description": "STRING, A description explaining why the file was determined to be malicious."
        },
        "EntityA": "STRING, The source of the relationship.",
        "EntityB": "STRING, The destination of the relationship.",
        "Relationship": "STRING, The name of the relationship.",
        "EntityAType": "STRING, The type of the source of the relationship.",
        "EntityBType": "STRING, The type of the destination of the relationship.",
        "FeedRelatedIndicators": {
             "value": "STRING, Indicators that are associated with the file.",
             "type": "STRING, The type of the indicators that are associated with the file",
             "description": "STRING, The description of the indicators that are associated with the file."
        },
        "MalwareFamily": "STRING, The malware family associated with the file.",
        "Campaign": "STRING, The campaign associated with the file.",
        "TrafficLightProtocol": "STRING, The Traffic Light Protocol (TLP) color that is suitable for the file.",
        "CommunityNotes": {
            "note": "STRING, Notes on the file that were given by the community.",
            "timestamp": "DATE, The time in which the note was published."
        },
        "Publications": {
            "source": "STRING, The source in which the article was published.",
            "title": "STRING, The name of the article.",
            "link": "STRING, A link to the original article.",
            "timestamp": "DATE, The time in which the article was published."
        },
        "Behavior": {
            "details": "STRING, The technical details which are relevant to the behavior.",
            "title": "STRING, The behavior associated with the file."
        },
        "ThreatTypes": {
            "threatcategory": "STRING, The threat category associated to this indicator by the source vendor. For example, Phishing, Control, TOR, etc.",
            "threatcategoryconfidence": "STRING, Threat Category Confidence is the confidence level provided by the vendor for the threat type category For example a confidence of 90 for threat type category 'malware' means that the vendor rates that this is 90% confidence of being a malware."
        },
        "Imphash": "STRING, The Imphash hash of the file.",
        "Quarantined": "BOOL, Is the file quarantined or not.",
        "Organization": "STRING, The organization of the file.",
        "AssociatedFileNames": "STRING, File names that are known as associated to the file."
}

In YAML

outputs:
- contextPath: File.Name
  description: The full file name (including file extension).
  type: String
- contextPath: File.EntryID
  description: The ID for locating the file in the War Room.
  type: String
- contextPath: File.Size
  description: The size of the file in bytes.
  type: Number
- contextPath: File.MD5
  description: The MD5 hash of the file.
  type: String
- contextPath: File.SHA1
  description: The SHA1 hash of the file.
  type: String
- contextPath: File.SHA256
  description: The SHA1 hash of the file.
  type: String
- contextPath: File.SHA512
  description: The SHA512 hash of the file.
  type: String
- contextPath: File.SSDeep
  description: The ssdeep hash of the file (same as displayed in file entries).
  type: String
- contextPath: File.Extension
  description: "The file extension, for example: 'xls'."
  type: String
- contextPath: File.Type
  description: The file type, as determined by libmagic (same as displayed in file entries).
  type: String
- contextPath: File.Hostname
  description: The name of the host where the file was found. Should match Path.
  type: String
- contextPath: File.Path
  description: The path where the file is located.
  type: String
- contextPath: File.Company
  description: The name of the company that released a binary.
  type: String
- contextPath: File.ProductName
  description: The name of the product to which this file belongs.
  type: String
- contextPath: File.DigitalSignature.Publisher
  description: The publisher of the digital signature for the file.
  type: String
- contextPath: File.Actor
  description: The actor reference.
  type: String
- contextPath: File.Tags
  description: (List) Tags of the file.
  type: Unknown
- contextPath: File.FeedRelatedIndicators.value
  description: Indicators that are associated with the file.
  type: String
- contextPath: File.FeedRelatedIndicators.type
  description: The type of the indicators that are associated with the file.
  type: String
- contextPath: File.FeedRelatedIndicators.description
  description: The description of the indicators that are associated with the file.
  type: String
- contextPath: File.MalwareFamily
  description: The malware family associated with the file.
  type: String
- contextPath: File.Signature.Authentihash
  description: The authentication hash.
  type: String
- contextPath: File.Signature.Copyright
  description: Copyright information.
  type: String
- contextPath: File.Signature.Description
  description: A description of the signature.
  type: String
- contextPath: File.Signature.FileVersion
  description: The file version.
  type: String
- contextPath: File.Signature.InternalName
  description: The internal name of the file.
  type: String
- contextPath: File.Signature.OriginalName
  description: The original name of the file.
  type: String
- contextPath: File.Malicious.Vendor
  description: The vendor that reported the file as malicious.
  type: String
- contextPath: File.Malicious.Description
  description: A description explaining why the file was determined to be malicious.
  type: String
- contextPath: File.Relationships.EntityA
  description: The source of the relationship.
  type: string
- contextPath: File.Relationships.EntityB
  description: The destination of the relationship.
  type: string
- contextPath: File.Relationships.Relationship
  description: The name of the relationship.
  type: string
- contextPath: File.Relationships.EntityAType
  description: The type of the source of the relationship.
  type: string
- contextPath: File.Relationships.EntityBType
  description: The type of the destination of the relationship.
  type: string
- contextPath: File.Campaign
  description: The campaign associated with the file.
  type: String
- contextPath: File.TrafficLightProtocol
  description: The Traffic Light Protocol (TLP) color that is suitable for the file.
  type: String
- contextPath: File.CommunityNotes.note
  description: Notes on the file that were given by the community.
  type: String
- contextPath: File.CommunityNotes.timestamp
  description: The time in which the note was published.
  type: Date
- contextPath: File.Publications.source
  description: The source in which the article was published.
  type: String
- contextPath: File.Publications.title
  description: The name of the article.
  type: String
- contextPath: File.Publications.link
  description: A link to the original article.
  type: String
- contextPath: File.Publications.timestamp
  description: The time in which the article was published.
  type: Date
- contextPath: File.Behavior.details
  description: The technical details which are relevant to the behavior.
  type: String
- contextPath: File.Behavior.title
  description: The behavior associated with the file.
  type: String
- contextPath: File.ThreatTypes.threatcategory
  description: The threat category associated to this indicator by the source vendor. For example, Phishing, Control, TOR, etc.
  type: String
- contextPath: File.ThreatTypes.threatcategoryconfidence
  description: Threat Category Confidence is the confidence level provided by the vendor for the threat type category For example a confidence of 90 for threat type category 'malware' means that the vendor rates that this is 90% confidence of being a malware.
  type: String
- contextPath: File.Imphash
  description: The Imphash hash of the file.
  type: String
- contextPath: File.Quarantined
  description: Is the file quarantined or not.
  type: Bool
- contextPath: File.Organization
  description: The organization of the file.
  type: String
- contextPath: File.AssociatedFileNames
  description: File names that are known as associated to the file.
  type: String

IP

The following is the format for an IP entity:

"IP": {
    "Address": "STRING, IP address",
    "EntityA": "STRING, The source of the relationship.",
    "EntityB": "STRING, The destination of the relationship.",
    "Relationship": "STRING, The name of the relationship.",
    "EntityAType": "STRING, The type of the source of the relationship.",
    "EntityBType": "STRING, The type of the destination of the relationship.",
    "ASN": "STRING, The autonomous system name for the IP address, for example: 'AS8948'.",
    "Hostname": "STRING, The hostname that is mapped to this IP address.",
    "Geo":{
        "Location": "STRING, The geolocation where the IP address is located, in the format: latitude:longitude.",
        "Country": "STRING, The country in which the IP address is located.",
        "Description": "STRING, Additional information about the location."
    },
    "DetectionEngines": "NUMBER, The total number of engines that checked the indicator.",
    "PositiveDetections": "NUMBEr, The number of engines that positively detected the indicator as malicious.",
    "Malicious":{
        "Vendor": "STRING, The vendor reporting the IP address as malicious.",
        "Description": "STRING, A description explaining why the IP address was reported as malicious."
    },
    "Tags": "STRING, Tags of the IP.",
    "FeedRelatedIndicators": {
         "value": "STRING, Indicators that are associated with the IP.",
         "type": "STRING, The type of the indicators that are associated with the IP",
         "description": "STRING, The description of the indicators that are associated with the IP."
    },
    "MalwareFamily": "STRING, The malware family associated with the IP.",
    "Organization": {
         "Name": "STRING, The organization of the IP.",
         "Type": "STRING, The organization type of the IP."
    },
    "ASOwner": "STRING, The autonomous system owner of the IP.",
    "Region": "STRING, The region in which the IP is located.",
    "Port": "STRING, Ports that are associated with the IP.",
    "Internal": "BOOL, Whether or not the IP is internal or external.",
    "UpdatedDate": "DATE, The date that the IP was last updated.",
    "Registrar": {
        "Abuse":{
            "Name": "STRING, The name of the contact for reporting abuse.",
            "Address": "STRING, The address of the contact for reporting abuse.",
            "Country": "STRING, The country of the contact for reporting abuse.",
            "Network": "STRING, The network of the contact for reporting abuse.",
            "Phone": "STRING, The phone number of the contact for reporting abuse.",
            "Email": "STRING, The email address of the contact for reporting abuse.",
    }},
    "Campaign": "STRING, The campaign associated with the IP.",
    "TrafficLightProtocol": "STRING, The Traffic Light Protocol (TLP) color that is suitable for the IP.",
    "CommunityNotes": {
        "note": "STRING, Notes on the IP that were given by the community.",
        "timestamp": "DATE, The time in which the note was published."
    },
    "Publications": {
        "source": "STRING, The source in which the article was published.",
        "title": "STRING, The name of the article.",
        "link": "STRING, A link to the original article.",
        "timestamp": "DATE, The time in which the article was published."
    },
    "ThreatTypes": {
        "threatcategory": "STRING, The threat category associated to this indicator by the source vendor. For example, Phishing, Control, TOR, etc.",
        "threatcategoryconfidence": "STRING, Threat Category Confidence is the confidence level provided by the vendor for the threat type category For example a confidence of 90 for threat type category 'malware' means that the vendor rates that this is 90% confidence of being a malware."
    }
}

In YAML

outputs:
- contextPath: IP.Address
  description: IP address
  type: String
- contextPath: IP.Relationships.EntityA
  description: The source of the relationship.
  type: string
- contextPath: IP.Relationships.EntityB
  description: The destination of the relationship.
  type: string
- contextPath: IP.Relationships.Relationship
  description: The name of the relationship.
  type: string
- contextPath: IP.Relationships.EntityAType
  description: The type of the source of the relationship.
  type: string
- contextPath: IP.Relationships.EntityBType
  description: The type of the destination of the relationship.
  type: string
- contextPath: IP.ASN
  description: 'The autonomous system name for the IP address, for example: "AS8948".'
  type: String
- contextPath: IP.Hostname
  description: The hostname that is mapped to this IP address.
  type: String
- contextPath: IP.Geo.Location
  description: 'The geolocation where the IP address is located, in the format: latitude:longitude.'
  type: String
- contextPath: IP.Geo.Country
  description: The country in which the IP address is located.
  type: String
- contextPath: IP.Geo.Description
  description: Additional information about the location.
  type: String
- contextPath: IP.DetectionEngines
  description: The total number of engines that checked the indicator.
  type: Number
- contextPath: IP.PositiveDetections
  description: The number of engines that positively detected the indicator as malicious.
  type: Number
- contextPath: IP.Malicious.Vendor
  description: The vendor reporting the IP address as malicious.
  type: String
- contextPath: IP.Malicious.Description
  description: A description explaining why the IP address was reported as malicious.
  type: String
- contextPath: IP.Tags
  description: (List) Tags of the IP.
  type: Unknown
- contextPath: IP.FeedRelatedIndicators.value
  description: Indicators that are associated with the IP.
  type: String
- contextPath: IP.FeedRelatedIndicators.type
  description: The type of the indicators that are associated with the IP.
  type: String
- contextPath: IP.FeedRelatedIndicators.description
  description: The description of the indicators that are associated with the IP.
  type: String
- contextPath: IP.MalwareFamily
  description: The malware family associated with the IP.
  type: String
- contextPath: IP.Organization.Name
  description: The organization of the IP.
  type: String
- contextPath: IP.Organization.Type
  description: The organization type of the IP.
  type: String
- contextPath: IP.ASOwner
  description: The autonomous system owner of the IP.
  type: String
- contextPath: IP.Region
  description: The region in which the IP is located.
  type: String
- contextPath: IP.Port
  description: Ports that are associated with the IP.
  type: String
- contextPath: IP.Internal
  description: Whether or not the IP is internal or external.
  type: Bool
- contextPath: IP.UpdatedDate
  description: The date that the IP was last updated.
  type: Date
- contextPath: IP.Registrar.Abuse.Name
  description: The name of the contact for reporting abuse.
  type: String
- contextPath: IP.Registrar.Abuse.Address
  description: The address of the contact for reporting abuse.
  type: String
- contextPath: IP.Registrar.Abuse.Country
  description: The country of the contact for reporting abuse.
  type: String
- contextPath: IP.Registrar.Abuse.Network
  description: The network of the contact for reporting abuse.
  type: String
- contextPath: IP.Registrar.Abuse.Phone
  description: The phone number of the contact for reporting abuse.
  type: String
- contextPath: IP.Registrar.Abuse.Email
  description: The email address of the contact for reporting abuse.
  type: String
- contextPath: IP.Campaign
  description: The campaign associated with the IP.
  type: String
- contextPath: IP.TrafficLightProtocol
  description: The Traffic Light Protocol (TLP) color that is suitable for the IP.
  type: String
- contextPath: IP.CommunityNotes.note
  description: Notes on the IP that were given by the community.
  type: String
- contextPath: IP.CommunityNotes.timestamp
  description: The time in which the note was published.
  type: Date
- contextPath: IP.Publications.source
  description: The source in which the article was published.
  type: String
- contextPath: IP.Publications.title
  description: The name of the article.
  type: String
- contextPath: IP.Publications.link
  description: A link to the original article.
  type: String
- contextPath: IP.Publications.timestamp
  description: The time in which the article was published.
  type: Date
- contextPath: IP.ThreatTypes.threatcategory
  description: The threat category associated to this indicator by the source vendor. For example, Phishing, Control, TOR, etc.
  type: String
- contextPath: IP.ThreatTypes.threatcategoryconfidence
  description: Threat Category Confidence is the confidence level provided by the vendor for the threat type category For example a confidence of 90 for threat type category 'malware' means that the vendor rates that this is 90% confidence of being a malware.
  type: String

Endpoint

The following is the format for an Endpoint:

"Endpoint": {
    "Hostname": "STRING, The endpoint's hostname.",
    "EntityA": "STRING, The source of the relationship.",
    "EntityB": "STRING, The destination of the relationship.",
    "Relationship": "STRING, The name of the relationship.",
    "EntityAType": "STRING, The type of the source of the relationship.",
    "EntityBType": "STRING, The type of the destination of the relationship.",
    "ID": "STRING, The endpoint's ID.",
    "IPAddress": "STRING, The endpoint's IP address OR LIST, one or more IP addresses.",
    "Domain": "STRING, The endpoint's domain.",
    "MACAddress": "STRING, The endpoint's MAC address.",
    "DHCPServer": "STRING, The DHCP server of the endpoint.",
    "OS": "STRING, The endpoint's operation system.",
    "OSVersion": "STRING, The endpoint's operation system version.",
    "BIOSVersion": "STRING, The endpoint's BIOS version.",
    "Model": "STRING, The model of the machine or device.",
    "Memory": "INT, Memory on this endpoint.",
    "Processors": "INT, The number of processors.",
    "Processor": "STRING, The model of the processor.",
    "IsIsolated": "STRING, The endpoint's isolation status.",
    "Status": "STRING, The endpoint's status.",
    "Vendor": "STRING, The integration name of the endpoint vendor.",

}

In YAML

    outputs:
    - contextPath: Endpoint.Hostname
      description: The endpoint's hostname.
      type: String
    - contextPath: Endpoint.Relationships.EntityA
      description: The source of the relationship.
      type: string
    - contextPath: Endpoint.Relationships.EntityB
      description: The destination of the relationship.
      type: string
    - contextPath: Endpoint.Relationships.Relationship
      description: The name of the relationship.
      type: string
    - contextPath: Endpoint.Relationships.EntityAType
      description: The type of the source of the relationship.
      type: string
    - contextPath: Endpoint.Relationships.EntityBType
      description: The type of the destination of the relationship.
      type: string
    - contextPath: Endpoint.OS
      description: The endpoint's operation system.
      type: String
    - contextPath: Endpoint.IPAddress
      description: The endpoint's IP address.
      type: String
    - contextPath: Endpoint.ID
      description: The endpoint's ID.
      type: String
    - contextPath: Endpoint.Status
      description: The endpoint's status.
      type: String
    - contextPath: Endpoint.IsIsolated
      description: The endpoint's isolation status.
      type: String
    - contextPath: Endpoint.MACAddress
      description: The endpoint's MAC address.
      type: String
    - contextPath: Endpoint.Vendor
      description: The integration name of the endpoint vendor.
      type: String
    - contextPath: Endpoint.Domain
      description: The endpoint's domain.
      type: String
    - contextPath: Endpoint.DHCPServer
      description: The DHCP server of the endpoint.
      type: String
    - contextPath: Endpoint.OSVersion
      description: The endpoint's operation system version.
      type: String
    - contextPath: Endpoint.BIOSVersion
      description: The endpoint's BIOS version.
      type: String
    - contextPath: Endpoint.Model
      description: The model of the machine or device.
      type: String
    - contextPath: Endpoint.Memory
      description: Memory on this endpoint.
      type: Int
    - contextPath: Endpoint.Processors
      description: The number of processors.
      type: Int
    - contextPath: Endpoint.Processor
      description: The model of the processor.
      type: String

Email Object

The following is the format for an Email Object:

"Email": {
    "To": "STRING, The recipient of the email.",
    "From": "STRING, The sender of the email.",
    "CC": "STRING, Email addresses CC'ed to the email.",
    "BCC": "STRING, Email addresses BCC'ed to the email.",
    "EntityA": "STRING, The source of the relationship.",
    "EntityB": "STRING, The destination of the relationship.",
    "Relationship": "STRING, The name of the relationship.",
    "EntityAType": "STRING, The type of the source of the relationship.",
    "EntityBType": "STRING, The type of the destination of the relationship.",
    "Format": "STRING, The format of the email.",
    "Body/HTML": "STRING, The HTML version of the email.",
    "Body/Text": "STRING, The plain-text version of the email.",
    "Subject": "STRING, The subject of the email.",
    "Headers": "STRING, The headers of the email."
}

In YAML

outputs:
- contextPath: Email.To
  description: The recipient of the email.
  type: String
- contextPath: Email.From
  description: The sender of the email.
  type: String
- contextPath: Email.CC
  description: Email addresses CC'ed to the email.
  type: String
- contextPath: Email.BCC
  description: Email addresses BCC'ed to the email.
  type: String
- contextPath: Email.Format
  description: The format of the email.
  type: String
- contextPath: Email.Relationships.EntityA
  description: The source of the relationship.
  type: string
- contextPath: Email.Relationships.EntityB
  description: The destination of the relationship.
  type: string
- contextPath: Email.Relationships.Relationship
  description: The name of the relationship.
  type: string
- contextPath: Email.Relationships.EntityAType
  description: The type of the source of the relationship.
  type: string
- contextPath: Email.Relationships.EntityBType
  description: The type of the destination of the relationship.
  type: string
- contextPath: Email.Body/HTML
  description: The HTML version of the email.
  type: String
- contextPath: Email.Body/Text
  description: The plain-text version of the email.
  type: String
- contextPath: Email.Subject
  description: The subject of the email.
  type: String
- contextPath: Email.Headers
  description: The headers of the email.
  type: String
- contextPath: Email.Attachment
  description: List<String> Entry IDs of email attachments
  type: Unknown

Domain

The following is the format for a Domain. Please note that for WHOIS, the entity is a dictionary nested for the key "WHOIS".

"Domain": {
    "Name": "STRING, The domain name, for example: 'google.com'.",
    "EntityA": "STRING, The source of the relationship.",
    "EntityB": "STRING, The destination of the relationship.",
    "Relationship": "STRING, The name of the relationship.",
    "EntityAType": "STRING, The type of the source of the relationship.", 
    "EntityBType": "STRING, The type of the destination of the relationship.",
    "DNS": "STRING, A list of IP objects resolved by DNS.",
    "DetectionEngines": "NUMBER, The total number of engines that checked the indicator.",
    "PositiveDetections": "NUMBER, The number of engines that positively detected the indicator as malicious.",
    "CreationDate": "DATE, The date that the domain was created.",
    "UpdatedDate": "DATE, The date that the domain was last updated.",
    "ExpirationDate": "DATE, The expiration date of the domain.",
    "DomainStatus": "STRING, The status of the domain.",
    "NameServers": "STRING, Name servers of the domain.",
    "Organization": "STRING, The organization of the domain.",
    "Subdomains": "STRING, Subdomains of the domain.",
    "Admin": {
        "Country": "STRING, The country of the domain administrator.",
        "Email": "STRING, The email address of the domain administrator.",
        "Name": "STRING, The name of the domain administrator.",
        "Phone": "STRING, The phone number of the domain administrator."
    },
    "Registrant": {
        "Country": "STRING, The country of the registrant.",
        "Email": "STRING, The email address of the registrant.",
        "Name": "STRING, The name of the registrant.",
        "Phone": "STRING, The phone number for receiving abuse reports."
    },
    "Tags": "STRING, Tags of the domain.",
    "FeedRelatedIndicators": {
         "value": "STRING, Indicators that are associated with the domain.",
         "type": "STRING, The type of the indicators that are associated with the domin",
         "description": "STRING, The description of the indicators that are associated with the domain."
    },
    "MalwareFamily": "STRING, The malware family associated with the domain.",
    "WHOIS": {
        "DomainStatus": "STRING, The status of the domain.",
        "NameServers": "STRING, A list of name servers, for example: 'ns1.bla.com, ns2.bla.com'.",
        "CreationDate": "DATE, The date that the domain was created.",
        "UpdatedDate": "DATE, The date that the domain was last updated.",
        "ExpirationDate": "DATE, The date that the domain expires.",
        "Registrant": {
            "Name": "STRING, The name of the registrant.",
            "Email": "STRING, The email address of the registrant.",
            "Phone": "STRING, The phone number of the registrant."
        },
        "Registrar": {
            "Name": "STRING, The name of the registrar, for example: 'GoDaddy'.",
            "AbuseEmail": "STRING, The email address of the contact for reporting abuse.",
            "AbusePhone": "STRING, The phone number of contact for reporting abuse."
        },
        "Admin": {
            "Name": "STRING, The name of the domain administrator.",
            "Email": "STRING, The email address of the domain administrator.",
            "Phone": "STRING, The phone number of the domain administrator."
        }
    },
    "WHOIS/History": "List of Whois objects",
    "Malicious":{
        "Vendor": "STRING, The vendor reporting the domain as malicious.",
        "Description": "STRING, A description explaining why the domain was reported as malicious."
    },
   "DomainIDNName": "STRING, The internationalized domain name (IDN) of the domain.",
   "Port": "STRING, Ports that are associated with the domain.",
   "Internal": "BOOL, Whether or not the domain is internal or external.",
   "Category": "STRING, The category associated with the indicator.",
   "Campaign": "STRING, The campaign associated with the domain.",
   "TrafficLightProtocol": "STRING, The Traffic Light Protocol (TLP) color that is suitable for the domain.",
   "ThreatTypes": {
        "threatcategory": "STRING, The threat category associated to this indicator by the source vendor. For example, Phishing, Control, TOR, etc.",
        "threatcategoryconfidence": "STRING, Threat Category Confidence is the confidence level provided by the vendor for the threat type category For example a confidence of 90 for threat type category 'malware' means that the vendor rates that this is 90% confidence of being a malware."
   },
   "Geo":{
        "Location": "STRING, The geolocation where the domain address is located, in the format: latitude:longitude.",
        "Country": "STRING, The country in which the domain address is located.",
        "Description": "STRING, Additional information about the location."
   },
   "Tech": {
       "Country": "STRING, The country of the domain technical contact.",
       "Name": "STRING, The name of the domain technical contact.",
       "Organization": "STRING, The organization of the domain technical contact.",
       "Email": "STRING, The email address of the domain technical contact."
   },
   "CommunityNotes": {
        "note": "STRING, Notes on the domain that were given by the community.",
        "timestamp": "DATE, The time in which the note was published."
   },
   "Publications": {
        "source": "STRING, The source in which the article was published.",
        "title": "STRING, The name of the article.",
        "link": "STRING, A link to the original article.",
        "timestamp": "DATE, The time in which the article was published."
   },
   "Billing": "STRING, The billing address of the domain.",
   
}

In YAML

outputs:
- contextPath: Domain.Name
  description: 'The domain name, for example: "google.com".'
  type: String
- contextPath: Domain.Relationships.EntityA
  description: The source of the relationship.
  type: string
- contextPath: Domain.Relationships.EntityB
  description: The destination of the relationship.
  type: string
- contextPath: Domain.Relationships.Relationship
  description: The name of the relationship.
  type: string
- contextPath: Domain.Relationships.EntityAType
  description: The type of the source of the relationship.
  type: string
- contextPath: Domain.Relationships.EntityBType
  description: The type of the destination of the relationship.
  type: string
- contextPath: Domain.DNS
  description: A list of IP objects resolved by DNS.
  type: String
- contextPath: Domain.DetectionEngines
  description: The total number of engines that checked the indicator.
  type: Number
- contextPath: Domain.PositiveDetections
  description: The number of engines that positively detected the indicator as malicious.
  type: Number
- contextPath: Domain.CreationDate
  description: The date that the domain was created.
  type: Date
- contextPath: Domain.UpdatedDate
  description: The date that the domain was last updated.
  type: String
- contextPath: Domain.ExpirationDate
  description: The expiration date of the domain.
  type: Date
- contextPath: Domain.DomainStatus
  description: The status of the domain.
  type: Datte
- contextPath: Domain.NameServers
  description: (List<String>) Name servers of the domain.  
  type: Unknown
- contextPath: Domain.Organization
  description: The organization of the domain.
  type: String
- contextPath: Domain.Subdomains
  description: (List<String>) Subdomains of the domain.
  type: Unknown
- contextPath: Domain.Admin.Country
  description: The country of the domain administrator.
  type: String
- contextPath: Domain.Admin.Email
  description: The email address of the domain administrator.
  type: String
- contextPath: Domain.Admin.Name
  description: The name of the domain administrator.
  type: String
- contextPath: Domain.Admin.Phone
  description: The phone number of the domain administrator.
  type: String
- contextPath: Domain.Registrant.Country
  description: The country of the registrant.
  type: String
- contextPath: Domain.Registrant.Email
  description: The email address of the registrant.
  type: String
- contextPath: Domain.Registrant.Name
  description: The name of the registrant.
  type: String
- contextPath: Domain.Registrant.Phone
  description: The phone number for receiving abuse reports.
  type: String
- contextPath: Domain.Tags
  description: (List) Tags of the domain.
  type: Unknown
- contextPath: Domain.FeedRelatedIndicators.value
  description: Indicators that are associated with the domain.
  type: String
- contextPath: Domain.FeedRelatedIndicators.type
  description: The type of the indicators that are associated with the domain.
  type: String
- contextPath: Domain.FeedRelatedIndicators.description
  description: The description of the indicators that are associated with the domain.
  type: String
- contextPath: Domain.MalwareFamily
  description: The malware family associated with the domain.
  type: String
- contextPath: Domain.WHOIS.DomainStatus
  description: The status of the domain.
  type: String
- contextPath: Domain.WHOIS.NameServers
  description: (List<String>) Name servers of the domain.
  type: String
- contextPath: Domain.WHOIS.CreationDate
  description: The date that the domain was created.
  type: Date
- contextPath: Domain.WHOIS.UpdatedDate
  description: The date that the domain was last updated.
  type: Date
- contextPath: Domain.WHOIS.ExpirationDate
  description: The expiration date of the domain.
  type: Date
- contextPath: Domain.WHOIS.Registrant.Name
  description: The name of the registrant.
  type: String
- contextPath: Domain.WHOIS.Registrant.Email
  description: The email address of the registrant.
  type: String
- contextPath: Domain.WHOIS.Registrant.Phone
  description: The phone number of the registrant.
  type: String
- contextPath: Domain.WHOIS.Registrar.Name
  description: 'The name of the registrar, for example: 'GoDaddy"'
  type: String
- contextPath: Domain.WHOIS.Registrar.AbuseEmail
  description: The email address of the contact for reporting abuse.
  type: String
- contextPath: Domain.WHOIS.Registrar.AbusePhone
  description: The phone number of contact for reporting abuse.
  type: String
- contextPath: Domain.WHOIS.Admin.Name
  description: The name of the domain administrator.
  type: String
- contextPath: Domain.WHOIS.Admin.Email
  description: The email address of the domain administrator.
  type: String
- contextPath: Domain.WHOIS.Admin.Phone
  description: The phone number of the domain administrator.
  type: String
- contextPath: Domain.WHOIS/History
  description: List of Whois objects
  type: String
- contextPath: Domain.Malicious.Vendor
  description: The vendor reporting the domain as malicious.
  type: String
- contextPath: Domain.Malicious.Description
  description: A description explaining why the domain was reported as malicious.
  type: String
- contextPath: Domain.DomainIDNName
  description: The internationalized domain name (IDN) of the domain.
  type: String
- contextPath: Domain.Port
  description: Ports that are associated with the domain.
  type: String
- contextPath: Domain.Internal
  description: Whether or not the domain is internal or external.
  type: Bool
- contextPath: Domain.Category
  description: The category associated with the indicator.
  type: String
- contextPath: Domain.Campaign
  description: The campaign associated with the domain.
  type: String
- contextPath: Domain.TrafficLightProtocol
  description: The Traffic Light Protocol (TLP) color that is suitable for the domain.
  type: String
- contextPath: Domain.ThreatTypes.threatcategory
  description: The threat category associated to this indicator by the source vendor. For example, Phishing, Control, TOR, etc.
  type: String
- contextPath: Domain.ThreatTypes.threatcategoryconfidence
  description: Threat Category Confidence is the confidence level provided by the vendor for the threat type category For example a confidence of 90 for threat type category 'malware' means that the vendor rates that this is 90% confidence of being a malware.
  type: String
- contextPath: Domain.Geo.Location
  description: 'The geolocation where the domain address is located, in the format: latitude:longitude.'
  type: String
- contextPath: Domain.Geo.Country
  description: The country in which the domain address is located.
  type: String
- contextPath: Domain.Geo.Description
  description: Additional information about the location.
  type: String
- contextPath: Domain.Tech.Country
  description: The country of the domain technical contact.
  type: String
- contextPath: Domain.Tech.Name
  description: The name of the domain technical contact.
  type: String
- contextPath: Domain.Tech.Organization
  description: The organization of the domain technical contact.
  type: String
- contextPath: Domain.Tech.Email
  description: The email address of the domain technical contact.
  type: String
- contextPath: Domain.CommunityNotes.note
  description: Notes on the domain that were given by the community.
  type: String
- contextPath: Domain.CommunityNotes.timestamp
  description: The time in which the note was published.
  type: Date
- contextPath: Domain.Publications.source
  description: The source in which the article was published.
  type: String
- contextPath: Domain.Publications.title
  description: The name of the article.
  type: String
- contextPath: Domain.Publications.link
  description: A link to the original article.
  type: String
- contextPath: Domain.Publications.timestamp
  description: The time in which the article was published.
  type: Date
- contextPath: Domain.Billing
  description: The billing address of the domain.
  type: String

URL

The following is the format for a URL entity:

"URL": {
    "Data": "STRING, The URL",
    "EntityA": "STRING, The source of the relationship.",
    "EntityB": "STRING, The destination of the relationship.",
    "Relationship": "STRING, The name of the relationship.",
    "EntityAType": "STRING, The type of the source of the relationship.",
    "EntityBType": "STRING, The type of the destination of the relationship.",
    "Malicious": {
        "Vendor": "STRING, The vendor reporting the URL as malicious.",
        "Description": "STRING, A description of the malicious URL."
    },
    "DetectionEngines": "NUMBER, The total number of engines that checked the indicator.",
    "PositiveDetections": "NUMBER, The number of engines that positively detected the indicator as malicious.",
    "Category": "STRING, The category associated with the indicator.",
    "Tags": "STRING, Tags of the URL.",
    "FeedRelatedIndicators": {
         "value": "STRING, Indicators that are associated with the URL.",
         "type": "STRING, The type of the indicators that are associated with the URL",
         "description": "STRING, The description of the indicators that are associated with the URL."
    },
    "MalwareFamily": "STRING, The malware family associated with the URL.",
    "Port": "STRING, Ports that are associated with the URL.",
    "Internal": "STRING, Whether or not the URL is internal or external.",
    "Campaign": "STRING, The campaign associated with the URL.",
    "TrafficLightProtocol": "STRING, The Traffic Light Protocol (TLP) color that is suitable for the URL.",
    "ThreatTypes": {
        "threatcategory": "STRING, The threat category associated to this indicator by the source vendor. For example, Phishing, Control, TOR, etc.",
        "threatcategoryconfidence": "STRING, Threat Category Confidence is the confidence level provided by the vendor for the threat type category For example a confidence of 90 for threat type category 'malware' means that the vendor rates that this is 90% confidence of being a malware."
    },
    "ASN": "STRING, The autonomous system name for the URL, for example: 'AS8948'.",
    "ASOwner": "STRING, The autonomous system owner of the URL.",
    "Geo": {
      "Country": "STRING, The country in which the URL is located."
    },
    "Organization": "STRING, The organization of the URL.",
    "CommunityNotes": {
        "note": "STRING, Notes on the URL that were given by the community.",
        "timestamp": "DATE, The time in which the note was published."
    },
    "Publications": {
        "source": "STRING, The source in which the article was published.",
        "title": "STRING, The name of the article.",
        "link": "STRING, A link to the original article.",
        "timestamp": "DATE, The time in which the article was published."
    }
}

In YAML

outputs:
- contextPath: URL.Data
  description: The URL
  type: String
- contextPath: URL.Relationships.EntityA
  description: The source of the relationship.
  type: string
- contextPath: URL.Relationships.EntityB
  description: The destination of the relationship.
  type: string
- contextPath: URL.Relationships.Relationship
  description: The name of the relationship.
  type: string
- contextPath: URL.Relationships.EntityAType
  description: The type of the source of the relationship.
  type: string
- contextPath: URL.Relationships.EntityBType
  description: The type of the destination of the relationship.
  type: string
- contextPath: URL.DetectionEngines
  description: The total number of engines that checked the indicator.
  type: String
- contextPath: URL.PositiveDetections
  description: The number of engines that positively detected the indicator as malicious.
  type: String
- contextPath: URL.Category
  description: The category associated with the indicator.
  type: String
- contextPath: URL.Malicious.Vendor
  description: The vendor reporting the URL as malicious.
  type: String
- contextPath: URL.Malicious.Description
  description: A description of the malicious URL.
  type: String
- contextPath: URL.Tags
  description: (List) Tags of the URL.
  type: Unknown
- contextPath: URL.FeedRelatedIndicators.value
  description: Indicators that are associated with the URL.
  type: String
- contextPath: URL.FeedRelatedIndicators.type
  description: The type of the indicators that are associated with the URL.
  type: String
- contextPath: URL.FeedRelatedIndicators.description
  description: The description of the indicators that are associated with the URL.
  type: String
- contextPath: URL.MalwareFamily
  description: The malware family associated with the URL.
  type: String
- contextPath: URL.Port
  description: Ports that are associated with the URL.
  type: String
- contextPath: URL.Internal
  description: Whether or not the URL is internal or external.
  type: Bool
- contextPath: URL.Campaign
  description: The campaign associated with the URL.
  type: String
- contextPath: URL.TrafficLightProtocol
  description: The Traffic Light Protocol (TLP) color that is suitable for the URL.
  type: String
- contextPath: URL.ThreatTypes.threatcategory
  description: The threat category associated to this indicator by the source vendor. For example, Phishing, Control, TOR, etc.
  type: String
- contextPath: URL.ThreatTypes.threatcategoryconfidence
  description: Threat Category Confidence is the confidence level provided by the vendor for the threat type category For example a confidence of 90 for threat type category 'malware' means that the vendor rates that this is 90% confidence of being a malware.
  type: String
- contextPath: URL.ASN
  description: "The autonomous system name for the URL, for example: 'AS8948'."
  type: String
- contextPath: URL.ASOwner
  description:The autonomous system owner of the URL.
  type: String
- contextPath: URL.GeoCountry
  description: The country in which the URL is located.
  type: String
- contextPath: URL.Organization
  description:The organization of the URL.
  type: String
- contextPath: URL.CommunityNotes.note
  description: Notes on the URL that were given by the community.
  type: String
- contextPath: URL.CommunityNotes.timestamp
  description: The time in which the note was published.
  type: Date
- contextPath: URL.Publications.source
  description: The source in which the article was published.
  type: String
- contextPath: URL.Publications.title
  description: The name of the article.
  type: String
- contextPath: URL.Publications.link
  description: A link to the original article.
  type: String
- contextPath: URL.Publications.timestamp
  description: The time in which the article was published.
  type: Date

CVE

The following is the format for a CVE:

"CVE": {
    "ID": "STRING, The ID of the CVE, for example: CVE-2015-1653",
    "EntityA": "STRING, The source of the relationship.",
    "EntityB": "STRING, The destination of the relationship.",
    "Relationship": "STRING, The name of the relationship.",
    "EntityAType": "STRING, The type of the source of the relationship.",
    "EntityBType": "STRING, The type of the destination of the relationship.",
    "CVSS": "STRING, The CVSS of the CVE, for example: 10.0",
    "Published": "DATE, The timestamp of when the CVE was published.",
    "Modified": "DATE, The timestamp of when the CVE was last modified.",
    "Description": "STRING, A description of the CVE."
}

In YAML

outputs:
- contextPath: CVE.ID
  description: 'The ID of the CVE, for example: CVE-2015-1653'
  type: String
- contextPath: CVE.Relationships.EntityA
  description: The source of the relationship.
  type: string
- contextPath: CVE.Relationships.EntityB
  description: The destination of the relationship.
  type: string
- contextPath: CVE.Relationships.Relationship
  description: The name of the relationship.
  type: string
- contextPath: CVE.Relationships.EntityAType
  description: The type of the source of the relationship.
  type: string
- contextPath: CVE.Relationships.EntityBType
  description: The type of the destination of the relationship.
  type: string
- contextPath: CVE.CVSS
  description: 'The CVSS of the CVE, for example: 10.0'
  type: String
- contextPath: CVE.Published
  description: The timestamp of when the CVE was published.
  type: Date
- contextPath: CVE.Modified
  description: The timestamp of when the CVE was last modified.
  type: Date
- contextPath: CVE.Description
  description: A description of the CVE.
  type: String

Rule

The following is the format for a Rule:

"Rule": {
    "Name": "STRING, The name of the rule.",
    "Condition": "STRING, The condition for the rule."
}

In YAML:

outputs:
    - contextPath: Rule.Name
      description: The name of the rule.
    - contextPath: Rule.Condition
      description: The condition of the rule.

DBot Score

The following is the format for a DBot Score entry:

"DBotScore": {
    "Indicator": "The indicator that was tested.",
    "Type": "The indicator type.",
    "Vendor": "The vendor used to calculate the score.",
    "Score": "The actual score.",
    "Reliability": "Reliability of the source providing the intelligence data."
}

In YAML

- contextPath: DBotScore.Indicator
  description: The indicator that was tested.
  type: String
- contextPath: DBotScore.Type
  description: The indicator type.
  type: String
- contextPath: DBotScore.Vendor
  description: The vendor used to calculate the score.
  type: String
- contextPath: DBotScore.Score
  description: The actual score.
  type: Number
- contextPath: DBotScore.Reliability
  description: Reliability of the source providing the intelligence data.
  type: String

Certificate

The following is the format for an X509 certificate:

"Certificate": {
        "Name": "STRING, Name (CN or SAN) appearing in the certificate.",
        "SubjectDN": "STRING,  The Subject Distinguished Name of the certificate. This field includes the Common Name of the certificate.",
        "PEM": "STRING, Certificate in PEM format.",
        "IssuerDN": "STRING, The Issuer Distinguished Name of the certificate.",
        "SerialNumber": "STRING, The Serial Number of the certificate.",
        "ValidityNotAfter": "DATE, End of certificate validity period.",
        "ValidityNotBefore": "DATE, Start of certificate validity period.",
        "SubjectAlternativeName": {
          "Type": "STRING, Type of the SAN.",
          "Value": "STRING, Name of the SAN."
        },
        "SHA512": "STRING, SHA512 Fingerprint of the certificate in DER format.",
        "SHA256": "STRING, SHA256 Fingerprint of the certificate in DER format.",
        "SHA1": "STRING, SHA1 Fingerprint of the certificate in DER format.",
        "MD5": "STRING, MD5 Fingerprint of the certificate in DER format.",
        "PublicKey": {
          "Algorithm": "STRING, Algorithm used for public key of the certificate.",
          "Length": "NUMBER, Length in bits of the public key of the certificate.",
          "Modulus": "STRING, Certificate.PublicKey.Modulus",
          "Exponent": "NUMBER, Exponent of the public key for RSA keys.",
          "PublicKey": "STRING, The public key for DSA/Unknown keys.",
          "P": "STRING, The P parameter for DSA keys.",
          "Q": "STRING, The Q parameter for DSA keys.",
          "G": "STRING, The G parameter for DSA keys.",
          "X": "STRING, The X parameter for EC keys.",
          "Y": "STRING, The Y parameter for EC keys.",
          "Curve": "STRING, Curve of the Public Key for EC keys.",
          "Y": "STRING, The Y parameter for EC keys."
        },
        "SPKISHA256": "STRING, SHA256 fingerprint of the certificate Subject Public Key Info.",
        "Signature": {
          "Algorithm": "STRING, Algorithm used in the signature of the certificate.",
          "Signature": "STRING, Signature of the certificate."
        },
        "Extension": {
          "Critical": "BOOL, Critical flag of the certificate extension.",
          "OID": "STRING,  OID of the certificate extension.",
          "Name": "STRING, Name of the certificate extension.",
          "Value": "STRING, Value of the certificate extension."
        },
        "Malicious": {
             "Vendor": "STRING, The vendor that reported the certificate as malicious.",
             "Description": "STRING, A description explaining why the certificate was determined to be malicious."
        }
}

In YAML

outputs:
- contextPath: Certificate.Name
  description: Name (CN or SAN) appearing in the certificate.
  type: String
- contextPath: Certificate.SubjectDN
  description: |
    The Subject Distinguished Name of the certificate.
    This field includes the Common Name of the certificate.
  type: String
- contextPath: Certificate.PEM
  description: Certificate in PEM format.
  type: String
- contextPath: Certificate.IssuerDN
  description: The Issuer Distinguished Name of the certificate.
  type: String
- contextPath: Certificate.SerialNumber
  description: The Serial Number of the certificate.
  type: String
- contextPath: Certificate.ValidityNotAfter
  description: End of certificate validity period.
  type: Date
- contextPath: Certificate.ValidityNotBefore
  description: Start of certificate validity period.
  type: Date
- contextPath: Certificate.SubjectAlternativeName.Type
  description: Type of the SAN.
  type: String
- contextPath: Certificate.SubjectAlternativeName.Value
  description: Name of the SAN.
  type: String
- contextPath: Certificate.SHA512
  description: SHA512 Fingerprint of the certificate in DER format.
  type: String
- contextPath: Certificate.SHA256
  description: SHA256 Fingerprint of the certificate in DER format.
  type: String
- contextPath: Certificate.SHA1
  description: SHA1 Fingerprint of the certificate in DER format.
  type: String
- contextPath: Certificate.MD5
  description: MD5 Fingerprint of the certificate in DER format.
  type: String
- contextPath: Certificate.PublicKey.Algorithm
  description: Algorithm used for public key of the certificate.
  type: String
- contextPath: Certificate.PublicKey.Length
  description: Length in bits of the public key of the certificate.
  type: Number
- contextPath: Certificate.PublicKey.Modulus
  description: Modulus of the public key for RSA keys.
  type: String
- contextPath: Certificate.PublicKey.Exponent
  description: Exponent of the public key for RSA keys.
  type: Number
- contextPath: Certificate.PublicKey.PublicKey
  description: The public key for DSA/Unknown keys.
  type: String
- contextPath: Certificate.PublicKey.P
  description: The P parameter for DSA keys.
  type: String
- contextPath: Certificate.PublicKey.Q
  description: The Q parameter for DSA keys.
  type: String
- contextPath: Certificate.PublicKey.G
  description: The G parameter for DSA keys.
  type: String
- contextPath: Certificate.PublicKey.X
  description: The X parameter for EC keys.
  type: String
- contextPath: Certificate.PublicKey.Y
  description: The Y parameter for EC keys.
  type: String
- contextPath: Certificate.PublicKey.Curve
  description: Curve of the Public Key for EC keys.
  type: String
- contextPath: Certificate.SPKISHA256
  description: SHA256 fingerprint of the certificate Subject Public Key Info.
  type: String
- contextPath: Certificate.Signature.Algorithm
  description: Algorithm used in the signature of the certificate.
  type: String
- contextPath: Certificate.Signature.Signature
  description: Signature of the certificate.
  type: String
- contextPath: Certificate.Extension.Critical
  description: Critical flag of the certificate extension.
  type: Bool
- contextPath: Certificate.Extension.OID
  description: OID of the certificate extension.
  type: String
- contextPath: Certificate.Extension.Name
  description: Name of the certificate extension.
  type: String
- contextPath: Certificate.Extension.Value
  description: Value of the certificate extension.
  type: Unknown
- contextPath: Certificate.Malicious.Vendor
  description: The vendor that reported the file as malicious.
  type: String
- contextPath: Certificate.Malicious.Description
  description: A description explaining why the file was determined to be malicious.
  type: String  

Recommended Cortex XSIAM context standards

The following are examples of how each entity should be formed in the entry context.

Ticket

"Ticket": {
    "ID": "STRING, The ID of the ticket.",
    "Creator": "STRING, The user who created the ticket.",
    "Assignee": "STRING, The user assigned to the ticket.",
    "State": "STRING, The status of the ticket. Can be "closed", "open", or "on hold".",
    "Description": "STRING The summary of the ticket."
}

In YAML

outputs:
- contextPath: Ticket.ID
  description: The ID of the ticket.
  type: String
- contextPath: Ticket.Creator
  description: The user who created the ticket.
  type: String
- contextPath: Ticket.Assignee
  description: The user assigned to the ticket.
  type: String
- contextPath: Ticket.State
  description: The status of the ticket. Can be "closed", "open", or "on hold".
  type: String
- contextPath: Ticket.Description
  description: The summary of the ticket.
  type: String

Account

"Account": {
    "Type": "STRING, The account type. The most common value is 'AD', but can be 'LocalOS', 'Google', 'AppleID', ... ",
    "ID": "STRING, The unique ID for the account (integration specific). For AD accounts this is the Distinguished Name (DN).",
    "Username": "STRING, The username in the relevant system.",
    "DisplayName": "STRING, The display name.",
    "Groups": "STRING, Groups to which the account belongs (integration specific). For example, for AD these are groups of which the account is memberOf.",
    "Domain": "STRING, The domain of the account.",
    "OrganizationUnit": "STRING, The Organization Unit (OU) of the account.",
    "Email": {
        "Address": "STRING, The email address of the account."
    },
    "TelephoneNumber": "STRING, The phone number associated with the account.",
    "Office": "STRING, The office where the person associated with the account works.",
    "JobTitle": "STRING, The job title of the account.",
    "Department": "STRING, The department of the account.",
    "Country": "STRING, The country associated with the account.",
    "State": "STRING, The state where the account works.",
    "City": "STRING, The city associated with the account.",
    "Street": "STRING, The street associated with the account.",
    "IsEnabled": "BOOL, Whether the account is enabled or disabled. 'True' means the account is enabled.",
    "CloudApplications": [
      {
        "ApplicationName": "STRING, Cloud application name that is assosciated with this account"
      }
    ],
    "ChangePasswordAtNextLogin": "BOOL, Whether this account should change its password at the next login",
    "IsInternal": "BOOL, Whether this account is internal or external to the organization",
    "Manager": {
      "Email": "STRING, The email address of the manager.",
      "DisplayName": "STRING, The display name of the manager."
    },
    "RiskLevel": "STRING, The risk level associated with the account. This could be 'LOW', 'MED' or 'HIGH'.",
}

In YAML

outputs:
- contextPath: Account.Type
  description: The account type. The most common value is 'AD', but can be 'LocalOS', 'Google', 'AppleID'
  type: String
- contextPath: Account.ID
  description: The unique ID for the account (integration specific). For AD accounts this is the Distinguished Name (DN).
  type: String
- contextPath: Account.Username
  description: The username in the relevant system.
  type: String
- contextPath: Account.DisplayName
  description: The display name.
  type: String
- contextPath: Account.Groups
  description: Groups to which the account belongs (integration specific). For example, for AD these are groups of which the account is memberOf.
  type: String
- contextPath: Account.Domain
  description: The domain of the account.
  type: String
- contextPath: Account.OrganizationUnit
  description: The Organization Unit (OU) of the account.
  type: String
- contextPath: Account.Email.Address
  description: The email address of the account.
  type: String
- contextPath: Account.TelephoneNumber
  description: The phone number associated with the account.
  type: String
- contextPath: Account.Office
  description: The office where the person associated with the account works.
  type: String
- contextPath: Account.JobTitle
  description: The job title of the account.
  type: String
- contextPath: Account.Department
  description: The department of the account.
  type: String
- contextPath: Account.Country
  description: The country associated with the account.
  type: String
- contextPath: Account.State
  description: The state where the account works.
  type: String
- contextPath: Account.City
  description: The city associated with the account.
  type: String
- contextPath: Account.Street
  description: The street associated with the account.
  type: String
- contextPath: Account.IsEnabled
  description: Whether the account is enabled or disabled. 'True' means the account is enabled.
  type: Bool
- contextPath: Account.CloudApplications.Application Name
  description: Cloud application name that is assosciated with this account.
  type: String
- contextPath: Account.ChangePasswordAtNextLogin
  description: Whether this account should change its password at the next login. 'True' means the account have to change its password.
  type: Bool
- contextPath: Account.IsInternal
  description: Whether the account is internal or external to the organization. 'True' means the account is internal.
  type: Bool
- contextPath: Account.Manager.Email
  description: The email address of the manager.
  type: String
- contextPath: Account.Manager.DisplayName
  description: The display name of the manager.
  type: String
- contextPath: Account.RiskLevel
  description: The risk level associated with the account. This could be 'LOW', 'MEDIUM', or 'HIGH'.
  type: String

Registry Key

"RegistryKey": {
    "Path": "STRING, The path to the registry key",
    "Name": "STRING, The name of registry key.",
    "Value": "STRING, The value at the given RegistryKey."
}