Integration metadata YAML file - Developer Guide - Cortex XSIAM - Cortex

Abstract

The YAML file includes all the metadata for integrations and scripts.

All the metadata of your integration is included in the YAML file. It is a key value set for your integration. When pushing content for public release, your YAML file must follow certain structural requirements to work properly. Scripts also have a metadata YAML file that follows a similar structure.

Common fields

The commonfields section contains information the Cortex XSIAM server uses to identify your integration.

commonfields:
  id: New Integration
  version: -1

This section contains the following information.

Name	Description
id	A unique identifier for your integration.
version	Setting the value to -1 locks the integration from being modified.

Basic information

This section contains integration metadata.

name: MaxMind GeoIP2
display: MaxMind GeoIP2
category: Data Enrichment & Threat Intelligence
image: data:image/png;base64,**Base64 of Image Here**
description: Enriches IP addresses
detaileddescription: 'The MaxMind GeoIP2 integration allows you to query the MaxMind
  API service and retrieve a JSON of all details. '

It includes the following parameters:

Name	Description
sectionOrder	A key to organize collection and connection related parameters in separate sections in the integration settings configuration page. Applied to each parameter as relevant.
name	The name of your integration. This may be different than the display name.
display	The display name for your integration.
category	The applicable pack category. See all available values.
image	The icon used for the integration. This image must be in Base64.
description	A brief description of what your integration does.
detaileddescription	More details about how your integration works..

Integration settings configuration

The configuration section specifies the integration settings configuration requirements that are necessary for the integration to operate.

configuration:
- display: API Key
  name: apikey
  defaultvalue: ""
  type: 0
  required: true
- display: Use system proxy
  name: proxy
  defaultvalue: ""
  type: 8
  required: false

It includes the following parameters.

Name	Description
display	The display name for the setting field.
name	The setting field name used within the integration.
defaultvalue	If there is a default for the field, it is indicated here.
type	An Integer representing the field type. Possible values 0 - Short text field 4 - Encrypted text field 8 - Boolean checkbox 9 - Authentication text - allows switching to credentials 12 - Long text block 13 - special use - automatically added - Incident type single select dropdown 15 - Single select dropdown 16 - Multiple select dropdown
required	Boolean value indicating whether the parameter is required.
additionalinfo	Additional info about the field, appears when clicking a question mark in the settings configuration panel.
fromlicense	Specifies to take the credentials from the Cortex XSIAM license. This is relevant for type 9 - Authentication text.
advanced	Whether to expose the configuration under the advanced settings. Possible values are true or false.
section	Which section the configuration setting will be under. Possible values are Collect or Connect.

Hiding integration settings parameters

To hide integration parameters from the UI in all Marketplaces, set the optional hidden field to true.

To hide the parameter in specific content Marketplace versions, provide a list of marketplace version names.

xsoar - Cortex XSOAR 6 and 8
xsoar_on_prem - Cortex XSOAR 6
xsoar_saas - Cortex XSOAR 8 Cloud and On-prem
marketplacev2 - Cortex XSIARM
xpanse - Cortex XPANSE

Script

The script section is where the code resides.

script:
  script: |
    import requests
    import collections

    def explain_yaml():
        if user.understands is False:
            re_read_documentation()

  type: python
  subtype: python3
  dockerimage: demisto/python3:3.7.5.3066

It includes the following parameters.

Name	Description
type	Indicates the language your integration is written in. Cortex XSIAM currently supports Python.t
subtype	When using Python, specifying subtype field is required. Use python3.
dockerimage	When using Python, dockerimage should be specified. If dockerimage is not specified a default python3 image is used. You can also specify any publicly available image found in DockerHub demisto account. If you need to need to generate a custom image with your own Python packages installed, see https://github.com/demisto/dockerfiles.

Name

Description

type

Indicates the language your integration is written in. Cortex XSIAM currently supports Python.t

subtype

When using Python, specifying subtype field is required. Use python3.

dockerimage

When using Python, dockerimage should be specified. If dockerimage is not specified a default python3 image is used.

You can also specify any publicly available image found in DockerHub demisto account.

If you need to need to generate a custom image with your own Python packages installed, see https://github.com/demisto/dockerfiles.

Commands

The command section tells Cortex XSIAM what arguments are required for your command as well as what the outputs are.

  commands:
  - name: command-name
    arguments:
    - name: command-argument
      required: true
      default: false
      isArray: false
      secret: true
      description: This is a description for the argument
    outputs:
    - contextPath: Example.Sample.Name
      description: The name of the sample
      type: string
    - contextPath: Example.Sample.ID
      description: The ID for the sample
      type: string
    description: Sample description for the command-name function
  runonce: false

It includes the following parameters.

Command

Name	Description	Standard
name	The name of the command.	`vendorname-command`
description	A description for the command.
runonce	Boolean. Whether the command runs repeatedly.

Command arguments

Name	Description	Standard
name	The name of the argument.	`argument_name`
required	Boolean. Whether the argument is required.
default	Boolean. If set to true, the user can pass a value for this argument without specifying the argument name. For example if an argument called `ip` is marked as default, running `!ip 1.1.1.1` will be equivalent to running `!ip ip=1.1.1.1`. Note Only one argument per command can be set as the default.
isArray	Boolean. Whether the argument accepts a CSV list of input values. If set to true, the command will run once instead for each input.
secret	Boolean. If set to true, the argument value will not be printed in the War Room when the command runs.
execution	Boolean. If set to true, the command will be marked as `Potentially harmful`.
description	A description of the argument.

Command outputs

Name	Description	Standard
contextPath	The dot notation representation of the context.	`Product.Entity.EntityDetails`
description	Description of the context item.
type	The type the context item will be formatted as.	Available options are: Unknown, String, Number, Date, Boolean.

Version and tests

The last section of the YAML file provides Cortex XSIAM with information regarding what version is supported and tests.

fromversion: 6.5.0
tests:
  - Sample Integration Test

It includes the following parameters.

Name	Description
fromversion	Indicates the server version that is supported with the integration. If the server version is below the `fromversion`, the integration will not display in the Settings area.
tests	Instructs the Cortex XSIAM CircleCI tool which test to run to verify that the integration is working. To run all of the tests, set `tests` to `Run all tests`. To not run any tests (not recommended), set `tests` to `No test - <reason>` . Note Both the automatic and the manual mechanisms run in parallel and do not override each other, and will not cause the same test to run more than once.

Name

Description

fromversion

Indicates the server version that is supported with the integration. If the server version is below the fromversion, the integration will not display in the Settings area.

tests

Instructs the Cortex XSIAM CircleCI tool which test to run to verify that the integration is working.

To run all of the tests, set tests to Run all tests.

To not run any tests (not recommended), set tests to No test - <reason> .

Note

Both the automatic and the manual mechanisms run in parallel and do not override each other, and will not cause the same test to run more than once.

Entry types

ID	Name	Details
1	Note	A text entry in the War Room.
2	Download Agent	Internal use only.
3	File	Displays a file and its metadata.
4	Error	Displayed with a red background, this indicates that a command did not run successfully.
5	Pinned	Internal use only.
6	User Management	Internal use only.
7	Image	Displays an image in the War Room.
8	Playground Error	Indicates an error has occurred in the playground.
9	Entry Info File	Used in the `FileResult` function in ServerCommon. Similar to the `file` entry type.
10-14	Reserved	For future entry types.
15	Map	Posts a map location in the War Room. This requires an API key from Google maps.

Integration metadata YAML file - Developer Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM Developer Guide

Common fields

Basic information

Integration settings configuration

Hiding integration settings parameters

Script

Commands

Command

Command arguments

Note

Command outputs

Version and tests

Note

Entry types