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.
If you have any questions or need support, reach out to us on the
#demisto-developers channel on our Slack DFIR Community.
This article is only for content contributions. For documentation contributions, refer to Documentation Contributions.
Contributions can be either officially supported (by Palo Alto Networks, or a Technology Partner), or community supported.
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, 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).
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.
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:
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.
For information about how to set up a development environment, see the dedicated Set Up Your Dev Environment tutorial.
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.
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.
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.
- Private content packs cannot be contributed this way.
Because of these limitations, we do not recommend using this method for large contributions, especially for XSOAR-supported packs.
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.
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.
- 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.
- Make sure you have all the contributing requirements satisfied.
- 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.
- Follow the content pack structure to build your contribution.
The "demisto-sdk init" command will help you create the basic structure.
- If you are updating an existing content pack, make you have the latest available version installed before proceeding.
- If you are creating integrations and / or scripts (aka automations), make sure that you:
- Use the proper directory structure. demisto-sdk init will help you create it.
If working on existing code that doesn't follow this structure, we require converting to this structure (as long as the changes aren't minor), as it allows running linting and unit-tests, and provides a smoother review process.
- Understand the structure of the YAML file, and the parameter types within it.
- Make sure your integration follows our logo guidelines.
- Read and follow the instructed Python code conventions, or PowerShell code conventions (advanced users only).
- If your integration generates incidents, follow the Fetch Incidents guidelines.
- Make proper use of the Context and DBotScore with your commands, and follow the Context Standards.
- Create unit-tests as documented here, and assure it passes the linting process.
- Document your contributed content by generating the README File.
- Use the proper directory structure. demisto-sdk init will help you create it.
- Create pack documentation.
Make sure you follow the documentation best practices.
- When creating new versions of your content pack, make sure to document your changes in a release notes file as detailed here.
- 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.
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.
Before submitting a Pull Request to the Cortex XSOAR GitHub Repository, the following requirements must be met:
- 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).
- Validate your content using demisto-sdk validate:
demisto-sdk validate -i Packs/YourPackName
- If your contribution has integrations or scripts, run linting (which also runs unit-tests) by running:
demisto-sdk lint -i Packs/YourPakName
- 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 new fork
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
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.
Before the review process begins, it is mandatory for you to complete two steps:
- Sign our Contributor License Agreement (CLA): Please read and sign our CLA.
- 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
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.
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.
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.