What is a YAML file?
A YAML file is a form of structured data. It is visually similar to a JSON tree, however is less strict with syntax. Think of it as key, value set for your integration.
When pushing an integration for public release, your YAML file must follow certain structural requirements in order to work properly. In this section we will review the various parts of the Cortex XSOAR YAML file.
The Common Fields section contains information that the Cortex XSOAR server will use to identify your integration. See the example below:
commonfields:id: New Integrationversion: -1
This section accepts the following information:
|id||A unique identifier for your integration|
|version||Setting the value to -1 will lock the integration from being modified|
Observe the following:
name: MaxMind GeoIP2display: MaxMind GeoIP2category: Data Enrichment & Threat Intelligenceimage: data:image/png;base64,**Base64 of Image Here**description: Enriches IP addressesdetaileddescription: 'The MaxMind GeoIP2 integration allows you to query the MaxMindAPI service and retrieve a JSON of all details. '
The following is an explanation of these fields:
|name||The name of your integration. This may be different than the display name|
|display||This is the display name for your integration|
|category||The applicable category|
|image||The Icon that will be used for the integration. Please note that this image must be in Base64. Ask the design team to provide you with a compatible image|
|description||A brief description of what your integration will do|
|detaileddescription||This description should go into more detail about how your integration works as well as requirements for the integration to work|
In this section, we specify the configuration requirements that are necessary for the integration to operate.
configuration:- display: API Keyname: apikeydefaultvalue: ""type: 0required: true- display: Use system proxyname: proxydefaultvalue: ""type: 8required: false
An explanation of these fields is as follows:
|display||The display name for the field.|
|name||The parameter which is used within the integration|
|defaultvalue||If there is a default for the field, it should be located here|
|type||An Integer that represents the type for the field.|
|Type 0 - Short text field|
|Type 4 - Encrypted text field|
|Type 8 - Boolean checkbox|
|Type 9 - Authentication text - allows switching to credentials|
|Type 12 - Long text block|
|Type 13 - special use - automatically added - Incident type single select dropdown|
|Type 15 - Single select dropdown|
|Type 16 - Multiple select dropdown|
|required||Boolean value to indicate that the parameter is required|
This section is where your code will reside. Review the example below:
script:script: |import requestsimport collectionsdef explain_yaml():if user.understands is False:re_read_documentation()type: pythonsubtype: python3dockerimage: demisto/python3:220.127.116.1166
subtype field is required (either:
python3). Additionally, when using Python
dockerimage should be specified. If
dockerimage is not specified a default Python 2 image will be used.
The command section tells Cortex XSOAR what arguments are required for your command as well as what the outputs are.
commands:- name: command-namearguments:- name: command-argumentrequired: truedefault: falseisArray: falsedescription: This is a description for the argumentoutputs:- contextPath: Example.Sample.Namedescription: The name of the sampletype: string- contextPath: Example.Sample.IDdescription: The ID for the sampletype: stringdescription: Sample description for the command-name functionrunonce: false
An explanation of these fields is as follows:
|name||The name of the command|
|arguments: name||The name of the argument|
|arguments: required||Boolean for if the argument is required|
|arguments: default||Boolean for if the argument is the one chosen when argument values are passed to a command without specifying the command argument's name. Note that only one command argument can be set as the default per command|
|arguments: isArray||Boolean for if the argument accepts a CSV list of input values|
|arguments: description||A description of the argument|
|outputs: contextPath||The dot notation representation of the context|
|outputs: description||Description of the context item|
|outputs: type||The type which the context item will be formatted|
|description||A description for the command|
|runonce||Boolean to indicate if the function runs repeatedly|
Version and Tests
The last section of the YAML file provides Cortex XSOAR with information regarding what version is supported and tests. See the example below:
fromversion: 4.1.0tests:- Sample Integration Test
From version 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 XSOAR CircleCI tool which test to run to verify that the integration is working.
If you want to run all of the tests you will need to add to the tests section
Run all tests as the test you would like to run.
If you want to live a life of shame and disappoint your team, you can opt to not run any tests by adding
No test - <reason> as a test you would like to run. You can attempt to earn back the respect of your team by writing a reason for skipping the test and we may consider it.
Please take into consideration that both the automatic and the manual mechanisms are working side by side and don't override each other, and don't worry it will not cause the same test to run more than once.
|1||Note||A note is a text entry in the war room.|
|2||Download Agent||Internal use only|
|3||File||A file and it's metadata will be displayed|
|4||Error||Observed 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||An image will be displayed in the war room.|
|8||Playground Error||An error has occurred in the playground|
|9||Entry Info File||Used in the |
|10-14||Reserved||This is for future entry types|
|15||Map||Posts a map location in the war room. Please note: This will require an API key from Google maps.|