A checklist of all the files you need to contribute to the Cortex XSIAM content repository.
Before contributing and opening a pull request, verify you prepared all the files you need to contribute to the Cortex XSIAM content repository. Note that content packs can contain multiple types of entities, such as integrations, scripts, playbooks, incident types, and incident fields.
Content pack checklist
All content packs must include the following:
Pack metadata file. For example,
Packs/YourPackName/pack_metadata.jsoncontains the information about your content pack. It should be compiled with all the required information.Pack README. For example,
Packs/YourPackName/README.md) - the README of the pack file.
If you are updating an existing content pack, the content pack must include release notes. For example, Packs/YourPackName/ReleaseNotes/1_0_1.md.
Note
Use PascalCase (e.g. YourPackName) for the name of the pack, its directories and its entities (integrations, scripts, playbooks, etc.) For reference, view the tree of the Hello World pack on GitHub.
How do I create these files?
To create a new content pack directory tree and structure, you should use the demisto-sdk init command , as described in the tutorial for setting up your development environment.
Integrations and scripts should be written with your favorite IDE.
All other entity types (playbooks, test playbooks, incident/indicator fields and types, layouts, classifiers and mappers, widgets, and dashboards) should be created in the Cortex XSIAM UI and exported using the demisto-sdk download command (using the -fmt argument). You can also export the files manually via the Cortex XSIAM UI (either individually using the download icons, or using the Export Custom Content feature. If you export the files instead of using demisto-sdk download command, you'll need to format them using demisto-sdk format.
Integrations
If your pack contains an integration, the integration directory must contain the following:
File | Sample Path and Description |
|---|---|
Code |
Integration implementation code |
YAML |
YAML file with integration metadata. |
Description |
Markdown file with instructions for the customer to configure the integration instance. The Markdown file shows up as a snippet when the user clicks the question mark icon in the integration configuration panel. |
Image |
The integration logo. |
README |
The integration documentation, mostly autogenerated. |
Command Examples |
Required to autogenerate the documentation. |
Unit Tests |
This file must be included to automatically test the code during the review phase. Although we encourage extensive testing, we do not enforce testing each and every function in the code. We recommend you focus on the most important functions and the helper functions. |
Unit Tests Data |
Contains example responses from your product API, to be used in unit tests. See examples from Hello World. |
Custom Incident Types, Fields, Classifiers, Mappers and Layouts | If your integration has the ability to fetch incidents, you usually need to provide custom incident types and related entities. You should plan for this during the design phase, and speak with your Palo Alto Networks Alliance contact person if you have any questions. |
Note
If you use PowerShell instead of Python, the code files extension will be .ps1 instead of .py.
Playbooks
File | Sample Path and Description |
|---|---|
Playbook |
If the file is exported directly from the Cortex XSIAM UI, it must be formatted with |
README |
Documentation file for the playbook, mostly autogenerated. |
Image |
Image of the playbook as exported from the Cortex XSIAM UI. Its link should be added to the README file. |
Note
The playbook README file must be updated with the correct image link after the pull request is opened, as explained in README files for content entities.
Incident or indicator fields
If your pack contains at least one custom incident or indicator field, it must contain a incident field or indicator field JSON file. For example, Packs/YourPackName/IncidentTypes/YourIncidentTypeName.json or Packs/YourPackName/IndicatorType/YourIndicatorTypeName.json. If the file is exported directly from the Cortex XSIAM UI, it must be formatted with demisto-sdk format.
Incident or indicator types
If your pack contains at least one custom incident or indicator type, it must contain a incident type or indicator type JSON file. For example, Packs/YourPackName/IncidentFields/YourIncidentFieldName.json or Packs/YourPackName/IndicatorFields/YourIndicatorFieldName.json. If the file is exported directly from the Cortex XSIAM UI, it must be formatted with demisto-sdk format.
If you have a custom incident or indicator type, in most sitituations you also need to include corresponding classifiers, mappers and layouts.
Classifiers and mappers
File | Sample Path and Description |
|---|---|
Classifier |
If the file is exported directly from the Cortex XSIAM UI, it must be formatted with |
Mapper |
If the file is exported directly from the Cortex XSIAM UI, it must be formatted with |
Incident or indicator layouts
If your pack contains at least one custom incident or indicator layout, it must contain a incident layout or indicator layout JSON file. For example, Packs/YourPackName/Layouts/layoutscontainer-YourIncidentTypeName.json. If the file is exported directly from the Cortex XSIAM UI, it must be formatted with demisto-sdk format.
Scripts
If your content pack contains at least one automation script, the scripts directory must contain the following:
File | Sample Path and Description |
|---|---|
Code |
Script implementation code |
YAML |
YAML file with script metadata. |
README |
The script documentation, mostly autogenerated. |
Unit Tests |
This file must be included to automatically test the code during the review phase. |
Unit Tests Data |
Contains example responses from your product API, to be used in unit tests. |
Note
If you use PowerShell instead of Python, the code files extension will be .ps1 instead of .py.
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 one custom widget, it must contain a widget JSON file. For example, Packs/YourPackName/Widgets/widget-YourWidgetName.json. If the file is exported directly from the Cortex XSIAM UI, it must be formatted with demisto-sdk format.
Dashboards
If your pack contains at least one custom dashboard, it must contain a dashboard JSON file. For example, Packs/YourPackName/Dashboard/dashboard-YourDashboardName.json. If the file is exported directly from the Cortex XSIAM UI, it must be formatted with demisto-sdk format.
Checklist table
The requirements above are also summarized in the following table:
Entity Type | All Contributions | Partner/Cortex XSIAM Only |
|---|---|---|
Pack |
| |
Design | Must follow use case guidelines and review the design document with the Alliances team. | |
Integration |
|
|
Playbook | Playbook file |
|
Incident/Indicator Field | Incident and/or indicator field JSON file | |
Incident/Indicator Type | Incident and/or indicator type JSON file | |
Classifier and Mapper |
| |
Incident/Indicator Layout | Layout JSON files | |
Script |
|
|
Widget | Widget JSON file | |
Dashboard | Dashboard JSON file |