This article is focused on contributing Cortex XSOAR Content. If you want to contribute fixes/suggestions to our development and reference Content docs (the site you are currently browsing) go to: Documentation Contributions.
Thanks for being interested in contributing to Cortex XSOAR. This document describes the Contribution process. If you are not sure whether you should read this, make sure you read the Getting Started Guide first.
All the free content (i.e. everything excluding Paid Content Packs) is open source and lives in the Cortex XSOAR GitHub Repository, with a MIT license.
Contributions can be either officially supported (by Palo Alto Networks, a Technology Partner, or an individual developer), or community supported: the former means that when a customer has a problem with the content, they will have an email address or web site to reach out to, and they will expect an answer. When the contribution is community supported, it's not required to provide support (customers will ask questions on our Live Community Forum) and the quality requirements for the contribution to be accepted will be lower.
For more information about the different support levels, check the official documentation.
After you have created your content, you must submit your content to Palo Alto Networks: the Cortex XSOAR Content Team will review and approve it before it becomes available to customers.
There are three ways to submit your work:
- Contribute from the Cortex XSOAR UI Marketplace. This flow is simpler and doesn't require to set up a development environment or be familiar with git. However, it is recommended only in the following scenarios:
- You are an individual contributor, contributing new content that is community supported.
- You are making small changes to existing content, even if it's xsoar or partner supported (usually a bug fix or adding a new command to an Integration).
- Contribute through a GitHub Pull Request on the public XSOAR Content Repository. Use this flow in the following scenarios:
- You are a Technology Partner contributing with partner supported new content.
- Your contribution is big and contains lots of different parts (Integrations, Scripts, Playbooks, Layouts, etc) that is likely to lead to a complex review process.
- You are proficient with GitHub.
- Contribute through a private GitHub repository: this is required if you are providing a Premium (aka Paid) Content Pack. The requirements are the same of supported Packs, and the contribution process is described here.
This document describes the main flow that covers supported and free contributions(i.e. item 2. in the above list) and summarizes everything you must do before and after opening a Pull Request on GitHub to contribute your pack.
If you are contributing community supported content, feel free to skip the rest of this document (although it's still recommended to read it to be aware of the best practices).
Please read the following guidelines carefully: following them 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 Slack on the
- 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.
- Setup a development environment by following the brief Dev Setup Guide or the more detailed Tutorial.
- Follow the Content Pack Structure to build your contribution. demisto-sdk init will help you create it.
- If you are updating an existing content pack, make sure it is updated with the latest version available in the marketplace before proceeding.
- Depending on the content entities you need to build, navigate to the specific section of this website for details. If you are creating Integrations and/or Scripts (aka Automations), make sure that you:
- Use the proper Integration/Script Directory Structure. demisto-sdk init will help you create it. If working on existing code, beyond trivial changes, we require converting to this structure as it allows running linting and unit tests and provides a clearer review process.
- Understand the YAML file structure and the Parameter Types.
- Make sure your integration follows our Logo Guidelines.
- Read and follow Python code conventions (recommended) or Powershell code conventions (advanced users only).
- If your integration generates Incidents, follow the Fetch Incidents guidelines.
- Make sure your commands make proper use of the Context, including Context Standards and DBotScore.
- Make sure to create unit tests as documented here and that the various linters we support pass as detailed here.
- Document your integration and automation by generating the README File.
- Create the appropriate Content Pack Documentation.
- Make sure you follow the Documentation Best Practices.
- As you build newer versions of your Content Pack, document your changes in a relevant release notes file as detailed here.
At this point you should be ready to submit a Pull Request! Check out our Contributing Checklist to make sure you have all the parts you need.
XSOAR Technology Partners
If you are an XSOAR Technology Partner, make sure you have reviewed the use cases with your Cortex XSOAR Alliances Team and that you have a Partner ID to associate your Pull Request to.
This guide doesn't cover all the topics: please browse the left sidebar and use the search bar to find what you need, and reach out for help over Slack on the
#demisto-developers channel when in doubt.
In order to be able to submit a Pull Request to the Cortex XSOAR GitHub Repository, you need to:
- Make sure to check the content contribution checklist to make sure you have created everything you need.
- Make sure you are working on a GitHub fork of the XSOAR content repository, and create a branch for your contribution (do NOT work on master).
- Validate your content: the validation hook should run automatically every time you run
git commit. You can also run the validation manually by using demisto-sdk validate:
demisto-sdk validate -i Packs/YourPackName. If you get an error that is unclear, ask for help on the
#demisto-developerschannel on our Slack DFIR Community.
- (Only if your contribution has Integrations or Scripts): Pass lint checks and unit tests with
demisto-sdk lint -i Packs/YourPakName.
- Create a short video to demo your product and your pack, and link it: this will be used by our reviewers to understand what your product does and how the content pack work.
After you have completed all the requirements and are ready to open your Pull Request, commit and push your work to the branch you have created in your forked repo.
Now you can go ahead an open your Pull Request, you can use this article to do so. When creating the pull request make sure to fill in the different section in the pull request template.
After opening the Pull Request, make sure that you:
- Sign the CLA: every contributor must sign our Contributor License Agreement in order for their contribution to be added to our content. In case of CLA issues check out our FAQs.
- Monitor your Pull Request on GitHub and be ready for a demo: our Content team will add comments to the Pull Request, asking questions and requesting changes. In order to establish a decent release process for your contribution, you are kindly asked to respond to the reviewer's code review and apply the required changes within 14 days. Stale Pull Requests might be closed.
- At some point, we'll ask you to schedule a meeting to see an interactive demo. Make sure you have a working installation of Cortex XSOAR with your pack fully configured.
As part of the Pull Request template, you will be asked to fill in the contribution registration form, make sure to do so, without it we cannot review your contribution.
For more details on how to handle the Pull Request, check out our Pull Request Conventions.