Getting Started Guide

This guide will provide you with some pointers to jumpstart your development journey. After reading it, you’ll have a great background for creating content and integrations for the Cortex XSOAR platform.

Prerequisites to start development

Please make sure you have completed the following before proceeding:

  1. Python 3.x programming experience (intermediate level)
  2. A copy of the Cortex XSOAR Platform (if you are not a Partner, you can obtain the Community Edition here
  3. Access to our Support Portal
  4. Access to the Palo Alto Networks DFIR Slack Community and join the #demisto-integrations-help channel
  5. API or SDK access to your product or solution.

If you are a Technology Partner, make sure that you also:

  1. Read the Become a Technology Partner page and sign up
  2. Complete the Technical Partnership Agreement
  3. Work with your Business Development contacts to make sure your use cases has been validated

If you have trouble with any of these items, please contact us via Slack or email.

Setting up & installing Cortex XSOAR

Note: Requires Support Center login access.

If you need to install Cortex XSOAR, please read the following Support Center article:

Installing Cortex XSOAR

Learning the Cortex XSOAR platform

The platform comes with a rich set of features and functionality that allow for a high degree of customization, so we recommend that you familiarize yourself with the different aspects of the platform as listed below.

Note: Requires Support Center login access

Cortex XSOAR Concepts, and Terminology

  • The Cortex XSOAR CLI - Think of this like an operating system CLI that is built into the product, and connects to every tool that you need. It allows the user to test and run integration commands, run automations, and more.
  • Incidents - From third party systems, email, etc., or created manually. Its the combination of a ticket and real time data.
  • Integrations - Product integrations (or apps) are mechanisms through which security orchestration platforms communicate with other products. These integrations can be executed through REST APIs, webhooks, and other techniques. An integration can be unidirectional or bidirectional, with the latter allowing both products to execute cross-console actions.
  • Playbooks - Playbooks (or runbooks) are task-based graphical workflows that help visualize processes across security products. These playbooks can be fully automated, fully manual, or anywhere in between.
  • Automations - Single purpose automations that generally manipulate data in the system, or used to wrap multiple integrations, or develop single purpose tools that are not complete products. Maybe you have some library that is not a full product that you want to utilize, automations are a good use for this.
  • Playground - The place you go in order to test integration commands, automations, and other tools from the Cortex XSOAR CLI.
  • The Cortex XSOAR Context - All of the above are tied together by way of something called the Cortex XSOAR Context. Every incident and playbook has a place to store data called the Context. The context stores the results from every integration command and every automation script that is run. 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. Simply put, if you have a command like !whois query="" it would return the data and store the results into the context.
  • Indicators - Indicators are any type of data that you want to match using regular expressions, or add to the system. Indicators can be assigned certain integration commands, and automations in order to determine reputation, take action, enrich, the list goes on here.
  • Try the product walkthroughs. You can access these by clicking the ‘Ask DBot’ icon on the bottom-right of the Cortex XSOAR console screen.

Development Guidelines

Please read the following guidelines. Following these guidelines will maximize the chances for a fast, easy and effective review process for everyone involved. If something is not clear, please don't hesitate to reach out to us via GitHub, Slack, or email

  • Setup a development environment by following the Dev Setup Guide.
  • Use the Content Pack format to add your contribution.
  • Use Integration and Script Directory Structure for all Python code based entities. If working on existing code, beyond trivial changes, we require converting to this structure as it allows running linting, unit tests and provides a clearer review process.
  • Make sure to read and follow code conventions.
  • Run and verify that the various linters we support pass as detailed here.
  • For Scripts/Integrations written in Python, make sure to create unit tests as documented here
  • Create a test playbook as documented here. Note: for simple Scripts that have unit tests, a test playbook is optional.
  • Validate that our validation hooks pass. If you used .hooks/bootstrap as documented in the [Dev Setup Guide] (dev-setup) the validation hook will run automatically upon commit. You can also run the validation hooks manually by running .hooks/pre-commit. If you want to validate specific files please use the demisto-sdk commands validate or lint
  • Document your integration as detailed here.
  • Document your changes in the relevant changelog file as detailed here

At this point you should be ready to submit a Pull Request! For more details, refer to our Contributing page.

Note: if you are a technology partner, make sure you have reviewed the use cases with your Business Development contacts and that you have a Partner ID to associate your Pull Request to.

Last updated on