Contributing

Thanks for being interested in contributing to Cortex XSOAR. This document describes the Contribution process.

Contributing allows you to make the content that you build on Cortex XSOAR available to every client through the Marketplace. Content can be either Partner or Community supported, Free or Paid.

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.

In order to setup a developing environment that will help you create your content, you can use the Set Up Your Dev Environment tutorial. The tutorial contains several parts including an elaborated process, you don't have to complete the entire tutorial you can just use it as a guide and to get real examples.

After you have created your content, you must submit your content for our team to review and approve.

There are three ways to submit your work:

  • In the majority of the cases and you want to provide a Content Pack that you want to support, you must open a GitHub Pull Request.

  • Starting from version 6.0, Cortex XSOAR supports a simplified flow to Contribute directly from the product UI: use this flow only if you are an individual contributor and your Content Pack is going to be community supported.

  • Only if you are providing a Premium (aka Paid) Content Pack, the GitHub process is slightly different and is described here.

    This document describes the main flow that covers most of the cases and summarizes everything you must do before and after opening a Pull Request on GitHub to contribute your pack.

Before proceeding, sure to check the content contribution checklist to make sure you have created everything you need.

Before opening a Pull Request

In order to be able to submit a Pull Request to the Cortex XSOAR GitHub Repository, you need to:

  • Have a GitHub account that you'll use to create the fork and open the Pull Request.
  • Create a fork of the repo in your own Github account. You can follow the instruction described GitHub docs and use the examples from the Development environment tutorial.
  • Create a new branch that will contain all of your contributed content. You can reference the Create a branch step in the development setup toturial.
  • If you're an XSOAR partner, have your partner-id (this should have been communicated to you over the onboarding emails from the Alliance team).
  • Join our our Slack DFIR Community, this is the place to ask questions, consult about use-case and raise issues regarding the Cortex XSOAR platform (use the #demisto-developers channel).
  • Design Document: we encourage you to prepare a Design Document that describes the capabilities of your Pack. Usually it's a Google Doc shared with you by the Alliances team. Click here to see a compiled example of a Design Document.
  • 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.
  • Pass the linters demisto-sdk lint: if you have an Integration or Script, your code must pass the tests.
  • Pass the validation demisto-sdk validate: make sure you run demisto-sdk validate -i Packs/YourPackName and all the checks are passed before opening the Pull Request. If unsure, ask for help on the #demisto-developers channel on our Slack DFIR Community.

Open a Pull Request

After you have completed all the requirements and ready to open your Pull Request commit and push your work to the a 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.

Important Note

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.

After opening a Pull Request

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.
  • 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. 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.

For more details on how to handle the Pull Request, check out our Pull Request Conventions.

Last updated on