Contribution Checklist

This document includes a checklist that summarizes the list of files that you need in order to contribute to the Cortex XSOAR content repository. Please make sure you have everything before you open a Pull Request (unless stated otherwise).

Keep in mind that content packs can contain multiple types of entities, such as Integrations, Automations (Scripts), Playbooks, Incident Types, Incident Fields, and so on.

Depending on whether your content pack is aiming to be certified or not, there will be different requirements.

Happy contributing!

Content Pack Checklist

No matter what you include in your content pack or whether it's going to be certified, the pack must include the following:

  • Pack Metadata file (i.e. Packs/YourPackName/pack_metadata.json) : the information about your content pack. It should be compiled with all the required information, as explained here.
  • Pack README (i.e. Packs/YourPackName/README.md): the readme of the pack file. More information here.
  • Release Notes (i.e. Packs/YourPackName/ReleaseNotes/1_0_1.md): these are required only if you are updating an existing Content pack, not for the first. More information here.

Note: Please use PascalCase (YourPackName) for the names of the directories and files that include your company, integration and playbook names (see the examples below).

As a reference, you can check the tree of the Hello World pack on GitHub.

To create a new content pack directory tree and structure, you should use the demisto-sdk init , as described in the tutorial.

Where do I get all these files?

Integrations and Scripts should be written with your favorite IDE (see here and here for details on how to set up your dev environment)

All other entity types (Playbooks, Test Playbooks, Incidents/Indicators Fields and Types, Layouts, Classifiers and Mappers, Widgets, Dashboards) should be created in the Cortex XSOAR UI and exported using demisto-sdk download (using the -fmt argument). You can also export the files manually via the Cortex XSOAR UI (either individually using the download icons, or using the Export Custom Content feature) but, in that case, you'll need to format them using demisto-sdk format.

Integrations

If your pack contains an Integration, the integration directory should contain the following:

  • Code file (i.e. Packs/YourPackName/YourIntegrationName/Integrations/YourIntegrationName.py): your integration implementation code.
  • YML file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/YourIntegrationName.yml): YML file with integration metadata.
  • Description file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/YourIntegrationName_description.md): markdown file with instructions on how a customer can configure the integration instance (example). It shows up as a snippet when the user clicks the question mark icon in the integration configuration panel.
  • Image file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/YourIntegrationName_image.png): the integration logo.
  • README file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/README.md): the integration documentation, mostly autogenerated (see here).
  • Command examples file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/command_examples): are needed to autogenerate the documentation
  • Unit tests file (i.e. Packs/YourPackName/Integrations/YourIntegrationName/YourIntegrationName_test.py): must be included to automatically test the code during the review phase. More details here
  • Unit tests data (i.e. Packs/YourPackName/Integrations/YourIntegrationName/test_data/*.json): contain example responses from your product API and are used in Unit tests. Examples from Hello World.

Note: if you use PowerShell and not Python, the extension of the code files will be .ps1 instead of .py.

Additional requirements Certified packs

If your integration is going to be certified, you also have the following requirements (optional for non-certified):

  • Test Playbook (i.e. Packs/YourPackName/TestPlaybooks/playbook-YourIntegrationName_Test.yml): required for nightly builds. More information here. We'll also need access credentials to a test/demo environment against which we can run the Test Playbook every night. For details, please contact the Cortex XSOAR Alliances Team.
  • Custom Incident Types, Fields, Classifiers, Mappers and Layouts: if your integration has the ability to fetch incidents, most likely you need to provide custom Incident Types and the related entities. This is usually covered during the Design phase: work with your Palo Alto Networks alliance contact if in doubt.

... and of course your adherence to our best practices and code conventions will be evaluated in a stricter way.

Playbooks

If your pack contains at least a playbook, the playbook directory must contain the following files:

  • Playbook file (i.e. Packs/YourPackName/Playbooks/playbook-YourPlaybookName.yml): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.
  • README file (i.e. Packs/YourPackName/Playbooks/playbook-YourPlaybookName_README.md): documentation file for the Playbook, mostly autogenerated
  • Image file (i.e. Packs/YourPackName/doc_files/YourPlaybookName.png): image of the Playbook as exported from the XSOAR UI. Its link should be added to the README file as explained here

Note: the playbook README file must be updated with the correct image link after the Pull Request is opened, as explained in the documentation here

Incident or Indicator Fields

If your pack contains at least a custom Incident or Indicator field, you'll need:

  • Incident or Indicator field JSON file (i.e. Packs/YourPackName/IncidentFields/YourIncidentFieldName.json or Packs/YourPackName/IndicatorFields/YourIndicatorFieldName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.

Incident or Indicator Types

If your pack contains at least a custom Incident or Indicator type, you'll need:

  • Incident or Indicator type JSON file (i.e. Packs/YourPackName/IncidentTypes/YourIncidentTypeName.json or Packs/YourPackName/IndicatorType/YourIndicatorTypeName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.

If you have a custom Incident or Indicator type, most probably you'll also have to include corresponding Classifiers, Mappers and Layouts:

Classifiers and Mappers

  • Classifier JSON file (i.e. Packs/YourPackName/Classifiers/classifier-YourIntegrationName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format. If exported from Cortex XSOAR 5.x, it must also be converted to 6.0 format.
  • Mapper JSON file (i.e. Packs/YourPackName/Classifiers/classifier-mapper-incoming-YourIntegrationName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format. If exported from Cortex XSOAR 5.x, it must also be converted to 6.0 format.

If you want your pack to be also compatible with version 5.x of Cortex XSOAR (5.0 and 5.5), you'll also need:

  • 5.x Classifier & Mapper JSON file (i.e. Packs/YourPackName/Classifiers/classifier-YourIntegrationName_5_9_9.json)

Incidents or Indicator Layouts

  • Layout JSON file (i.e. Packs/YourPackName/Layouts/layoutscontainer-YourIncidentTypeName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format. If exported from Cortex XSOAR 5.x, it must also be converted to 6.0 format.

If you want your pack to be also compatible with version 5.x of Cortex XSOAR (5.0 and 5.5), you'll also need:

  • 5.x Layout JSON File (one file for each Layout type, i.e. Packs/YourPackName/Layouts/layouts-details-YourIncidentTypeName.json)

Scripts (Automations)

If your pack contains at least an automation script, the automation directory should contain the following:

  • Code file (i.e. Packs/YourPackName/YourScriptName/Scripts/YourScriptName.py): your script implementation code.
  • YML file (i.e. Packs/YourPackName/Scripts/YourScriptName/YourScriptName.yml): YML file with script metadata.
  • README file (Packs/YourPackName/Scripts/YourScriptName/README.md): the script documentation, mostly autogenerated (see here).
  • Unit tests file (i.e. Packs/YourPackName/Scripts/YourScriptName/YourScriptName_test.py): must be included to automatically test the code during the review phase. More details here
  • Unit tests data files (i.e. Packs/YourPackName/Scripts/YourScriptName/test_data/*.json): contain example responses from your product API and are used in Unit tests.

Note: if you use PowerShell and not Python, the extension of the code files will be .ps1 instead of .py.

Additional requirements Certified packs

If your integration is going to be certified, you also have the following requirements (optional for non-certified):

  • Test Playbook (i.e. Packs/YourPackName/TestPlaybooks/playbook-YourScriptName_Test.yml): required for nightly builds. More information here.

... and of course your adherence to our best practices and code conventions will be evaluated in a stricter way.

Note: if your pack contains both integrations and scripts, you can use a single Test Playbook to test both.

Widgets

If your pack contains at least a custom widget, you'll need:

  • Widget JSON file (i.e. Packs/YourPackName/Widgets/widget-YourWidgetName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.

Dashboards

If your pack contains at least a custom dashboard, you'll need:

  • Dashboard JSON file (i.e. Packs/YourPackName/Dashboard/dashboard-YourDashboardName.json): if exported directly from the XSOAR UI, it must be formatted with demisto-sdk format.

Checklist Table

The requirements above are also summarized in the following table:

Entity TypeNon-certified and certifiedCertified only
Pack
  • Pack metadata
  • Pack readme
  • Release Notes
Design
  • Must follow use case guidelines and review the design document with the Alliances team
Integration
  • Code file
  • YML file
  • Description file
  • Image file
  • README file
  • Command examples file
  • Unit tests file
  • Unit tests data
  • Test Playbook
  • Custom Incidents (if fetch_incidents is supported)
  • Instance Credentials
Playbook
  • Playbook file
  • README file
  • Image file
Incident/Indicator Field
  • Incident/Indicator field JSON file
Incident/Indicator Type
  • Incident/Indicator type JSON file
Classifier and Mapper
  • Classifier JSON file (for XSOAR 6.0 and above)
  • Mapper JSON file (for XSOAR 6.0 and above)
  • 5.x Classifier JSON file (for XSOAR 5.x)
Incident/Indicator Layout
  • Layout JSON files (for XSOAR 6.0 and above)
  • 5.x Layout JSON file(for XSOAR 5.x)
Script
  • Code file
  • YML file
  • README file
  • Unit tests file
  • Unit tests data
  • Test Playbook
Widget
  • Widget JSON file
Dashboard
  • Dashboard JSON file
Last updated on