Skip to main content

Contributing XSOAR Content

This article describes the contribution process for Cortex XSOAR content.

Contributing allows clients and partners who created new content, or modified existing content (enhancements, bug-fixes, etc.), to share their work with the community by making it publicly available in Cortex XSOAR Marketplace.
Content can be Cortex XSOAR, partner, or community supported.

All content is open source, and is hosted on the Cortex XSOAR Content GitHub Repository, licensed under the MIT license.

If you have any questions or need support, reach out to us on the #demisto-developers channel on our Slack DFIR Community.

note

This article is only for content contributions. For documentation contributions, refer to Documentation Contributions.

Content Support Types#

Contributions can be either officially supported (by Palo Alto Networks, or a Technology Partner), or community supported.

Officially Supported Packs#

Officially supported packs have a stricter quality-control process, and provide an email address or a website of their owner that customers can reach out to (and will be referred to) in case of an issue.

Community Supported Packs#

Community supported packs, do not have a support contact (customers will be able to ask questions on our Live Community Forum), and will have a lesser strict quality-control process (in comparison to officially supported packs).

info

Contributed content for Palo Alto Networks products (e.g., PAN-OS, Cortex XDR, etc.) will be adopted and supported by the Cortex XSOAR Content team.

Contribution Methods#

After creating new content, in order to contribute it, you will need to submit it for the Cortex XSOAR Content team to review. Once approved, it will become available for all customers to download. Before starting to work on a contribution, it is recommended to go over the Contribution SLA article.

There are several ways to submit contributions:

1. Cortex XSOAR Content GitHub Repository (Pull Request)#

Contribute by creating a fork and opening a pull request on the Cortex XSOAR Content GitHub repository.
Use this method in the following scenarios:

  • You are a Technology Partner contributing with partner supported new content.
  • Your contribution is large and contains lots of different parts (integrations, scripts, playbooks, layouts, etc.) that are likely to lead to a complex review process.
  • You are proficient with GitHub.
info

For information about how to set up a development environment, see the dedicated Set Up Your Dev Environment tutorial.

tip

For contributing through GitHub, we recommend to use a GitHub Codespace, which will provide you with a pre-configured ready-to-use development environment.
This method is still experimental, but will make the contribution, development, and review processes much easier.

For more information and a step-by-step guide, see the dedicated GitHub Codespace Setup tutorial.

2. Cortex XSOAR Marketplace#

Contribute from within Cortex XSOAR's UI using Marketplace.
This method is more simple, and doesn't require you to set up a development environment or be familiar with Git.

We recommend using this method in the following scenarios:

  • Individual contributors, contributing content that is community supported.

  • Small contributions (e.g., a bug fix, or a new integration command) to an existing content pack (whether it's XSOAR-supported or partner-supported).

  • For more information and a step-by-step guide, see Contributing Through Cortex XSOAR Marketplace.

caution

Contributing from Marketplace has several limitations:

  • The built-in editor has limitations, and does not support some of the features that can be found in a full-fledged IDE.
  • Documentation files (README, integration's description, etc.) cannot be created or edited.
  • Unit tests cannot be created or edited.

Because of these limitations, we do not recommend using this method for large contributions, especially for XSOAR-supported packs.

note

The following sections are necessary only for officially supported contributions, but we still recommend to read them even if you are contributing community supported content in order to be aware of the best practices.

The Pull Request Process section is not relevant for contributions that were created from Marketplace.

Guidelines#

Carefully review the following guidelines, as they will greatly enhance the likelihood of a swift, streamlined, and efficient review process for all parties involved. If you have any questions or require clarification, feel free to contact us through the Slack platform using the #demisto-developers channel.

  1. Begin by designing your contribution. We recommend to follow the design guidelines to identify what you want to build and make sure it is aligned with our best practices. Also check out the design tutorial.
  2. Make sure you have all the contributing requirements satisfied.
  3. Set up a development environment by following the short development setup guide and the more detailed tutorial, or use a pre-configured GitHub Codespace environment.
  4. Follow the content pack structure to build your contribution.
    The "demisto-sdk init" command will help you create the basic structure.
  5. If you are updating an existing content pack, make you have the latest available version installed before proceeding.
  6. If you are creating integrations and / or scripts (aka automations), make sure that you:
  7. Create pack documentation.
    Make sure you follow the documentation best practices.
  8. When creating new versions of your content pack, make sure to document your changes in a release notes file as detailed here.
  9. Go over the contributions checklist, and make sure you have all the required files in your content pack.

Once these steps are completed, you should be ready to submit your contribution and open a Pull Request.

tip

The Hello World content pack is a good example that implements all of the above guidelines and can be used as a reference (alongside the Hello World Design Document).

note

If you are an XSOAR Technology Partner, make sure the Cortex XSOAR Alliances Team has reviewed your planned contribution, and that you have a Partner ID to associate your Pull Request to.

Pull Request Submission Process#

Prerequisites#

Before submitting a Pull Request to the Cortex XSOAR GitHub Repository, the following requirements must be met:

  1. Create a GitHub fork of the XSOAR Content repository, and submit your changes on a new branch (do not push your changes to the master branch).
  2. Validate your content using demisto-sdk validate:
    demisto-sdk validate -i Packs/YourPackName
  3. If your contribution has integrations or scripts, run linting (which also runs unit-tests) by running:
    demisto-sdk lint -i Packs/YourPakName
  4. Create a short demo video presenting the product and your pack, and link it.
    This will help our reviewers to better understand what the product is used for, and how the newly contributed content integrates with it.

Creating a fork Creating a new fork

Pull Request Creation#

After all the prerequisites are met, and you are ready to create your pull request, commit and push your work to the branch you created in your forked repository (if you haven't already done so).

After pushing your changes to the remote branch on GitHub, GitHub should automatically detect the changes, and a green Compare & pull request button will appear at the top.

Click it, and then on the opened form, update the title and the description (using the pre-existing template), and click "Create pull request".

For additional information on how to create a Pull Request from a fork, refer to the official GitHub documentation.

Creating a new pull request Creating a new pull request

note

There will be a setting at the top of the form to determine where the pull request will be opened.
By default, it will open the pull request from your fork on the branch you created, to the master branch of the base Cortex XSOAR Content repository.
Then within a few minutes, the target branch will be replaced from master to a different custom one. This is on purpose, and should not be changed.

Post-Submission#

Before the review process begins, it is mandatory for you to complete two steps:

  1. Sign our Contributor License Agreement (CLA): Please read and sign our CLA.
  2. Fill out the registration form.

Once you have created your pull request, an automated comment will be posted on your pull request with a link to the registration form, and a tag of a member of our contribution team who will review your code.

An example for a message by our bot on a PR An example for a message by our bot on a PR

Once these requirements are fulfilled, our assigned contributions team member will start reviewing your code.

During or near the completion of the review process, we may request scheduling a meeting for an interactive demo.
Prepare for it, and make sure you have a working instance of Cortex XSOAR, with your contributed pack fully configured and ready to be presented.
Check out our Contribution Demo Page for additional information about the demo process.

info

In order to establish a proper release timeframe for your contribution, you are required to respond (and apply requested changes, if any) within 14 days.
Stale pull requests with no response within this timeframe will be closed.

tip

If after signing the CLA, you still see a message saying it's unsigned on your PR, refer to the FAQ for possible solutions.

For additional information on how to properly create and manage your pull request, see the dedicated Pull Request Conventions article.

Edit this page
Last updated on
Report an Issue