Integration description file - Developer Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM Developer Guide
Product
Cortex XSIAM
Creation date
2023-05-01
Last date published
2024-06-04
Category
Developer Guide
Abstract

The integration description file includes use case and integration instance configuration information.

The integration description file provides the supported integration use cases, and helps Cortex XSIAM users to easily configure an integration instance.

Tip

  • Give as much information as you think the user needs to succeed, including permission levels, credentials, and keys.

  • If there are permissions required on the integration level, list them.

  • If commands have separate permissions, mention that, but document the required permission on the command level.

  • Images can be added to integration description files.

Common use cases

  • How to get credentials

  • How to get API Key/secret

  • How to get Application ID

Integration description file location

The description file should be placed with the rest of the integration's files.

For example, if the pack name is HelloWorld and the integration name is also HelloWorld, the description file path is:

~/.../content/Packs/HelloWorld/Integrations/HelloWorld/HelloWorld_description.md

Integration description file data

The description file contains details on how to configure an integration instance, together with the relevant details needed from the product that are important for configuration. The file content can include troubleshooting tips and advanced details for different configuration cases.

Note

This file should not be confused with the integration README file.

Example

This is the content of the HelloWorld_description.md file:

## Hello World
- This section explains how to configure the instance of HelloWorld in Cortex XSIAM.
- You can use the following API Key: `43ea9b2d-4998-43a6-ae91-aba62a26868c`
Integration description file content in the UI

The content of the description file is displayed in the Help tab next to the integration instance settings configurations:

xsiam-integration-hlep-tab.png
Support level header YML metadata key

The supportlevelheader key can be set to one of the following values to set the support level header in the content description:

  • xsoar - The description specifies that Palo Alto Networks supports this integration.

  • partner - The description specifies that this integration is partner supported and list the partner's contact information.

  • community - The description specifies that this integration is community supported or lists the pack's author.

Set the support level header YML metadata key

To set the key, open the YAML file for the integration in the same folder where the description file is located and add the supportlevelheader key with of the supported values listed above.

If the key is not set in the integration YAML, the support level header is set to the support key in the pack_metadata.json file.