generate-integration

Generate a Cortex XSOAR or Cortex XSIAM integration from an integration configuration JSON file.

Use the generate-integration command to generate a Cortex XSIAM/Cortex XSOAR integration from an integration config JSON file. The JSON config file can be generated from a Postman collection via the postman-codegen command.

Arguments

Argument	Description
-h, --help	Provides detailed information about the command.
-i, --input	The input configuration JSON file. You can generate this file using postman-codegen.
-o, --output	(Optional) The output directory. The current directory is the default.

Example

demisto-sdk generate-integration -i config-VirusTotal.json -o /output/path

The above command generates the integration-VirusTotal.yml file under the /output/path directory.

Integration config JSON file

Example File: URLScan generated config file

name	string	The integration name. The command sets the integration ID the same as the name. Spaces and special characters will be removed.	VirusTotal	Required
display_name	string	The display name for the integration. This may be different than the name.	VirusTotal	Required
description	string	A brief description of what the integration does.	Analyzes suspicious hashes, URLs, domains, and IP addresses.	Required
category	string	The field/subject the integration relates to, at a high level.	Data Enrichment & Threat Intelligence	Required
command\_prefix	string	The prefix to all the commands. The prefix should be lower cased- separated with dashes.	vt,virustotal	Required
docker\_image	string	Docker image full name with version.	demisto/python3:3.9.2.17957	Required
url	string	The default value for integration Server URL parameter.	https://www.virustotal.com	Optional
base\_url\_path	string	Suffix for the integration Server URL parameter. If the API url contains constant suffix like /vtapi/v2.	vtapi/v2	Optional
auth	string	Determines which authentication method is used to connect. See the Authentication section below for more detail.		Optional
context\_path	string	Prefix for every command outputs. Must not contain spaces nor special characters.	VirusTotal -> VirusTotal.IP.source	Required
code\_type	string	The code the integration is written in.	python	Required
code\_subtype	string	The subtype of the code.	python3	Required
is\_fetch	Boolean	Whether the integration should run periodically to ingest events and create incidents.	false	Optional
fix\_code	Boolean	If true, run autopep8 to format the Python code. The default and the recommended value is true.	true	Optional

Authentication

This section defines the way the integration authenticates with a third-party product/service. Supported authentication types:

• API Key as part of the header example

  Generates api_key integration parameter.

  "auth": {
       "type": "apikey",
       "apikey": [
           {
               "key": "in",
               "value": "header",
               "type": "string"
           },
           {
               "key": "key",
               "value": "Authorization",
               "type": "string"
           }
       ]
   }

• API Key as part of the query example

  Generates api_key integration parameter.

  "auth": {
       "type": "apikey",
       "apikey": [
           {
               "key": "in",
               "value": "query",
               "type": "string"
           },
           {
               "key": "key",
               "value": "apikey",
               "type": "string"
           }
       ]
   }

• Basic authentication example

  The command generates the credentials parameter of type Authentication.

  "auth": {
       "type": "basic"
   }

• API Token bearer

  The command generates the api_key integration parameter. The parameter is passed in "Authorization": "Bearer TOKEN_HERE" in the request header.

  "auth": {
       "type": "bearer"
  }

Parameters

Supported parameter types:

• STRING
• NUMBER
• ENCRYPTED
• BOOLEAN
• AUTH
• DOWNLOAD_LINK
• TEXT_AREA
• INCIDENT_TYPE
• TEXT_AREA_ENCRYPTED
• SINGLE_SELECT
• MULTI_SELECT

"params": [
     {
         "name": "url",
         "display": "Server URL",
         "defaultvalue": "https://www.virustotal.com",
         "type_": "STRING",
         "required": true
     },
     {
         "name": "proxy",
         "display": "Use system proxy settings",
         "defaultvalue": "",
         "type_": "BOOLEAN",
         "required": false
     },
     {
         "name": "apikey",
         "display": "API Key",
         "defaultvalue": "",
         "type_": "ENCRYPTED",
         "required": true
     }
 ]

Command Fields

Name	Field type	Description	Examples	Required
commands	list	List of integration commands.		Required
commands.name	string	Command name. Should be lower case and should not contain spaces or special characters.	scan-file	Required
commands.context_path	string	Context path object for this specific command. For example, if the command returns a Report object, then set this field to Report.	Report, IP, Event	Required
commands.root_object	string	If you don't want to return the whole response, but rather a specific field of it. Note: Only a single nested layer is supported - for example if the response is {layer1:{layer2:{...}}} it is possible to access layer1 but not layer2.	result, scan	Optional
commands.unique_key	string	Unique/Identifier key field from the response/outputs.	id, sha1, name	Optional
commands.headers	list	Request headers.	[{"Content-Type": "application/json"},{"Accept": "application/json"}]	Optional
commands.body_format	object	Defines the structure and the format of the request body. In case the request contains a body, this field must be passed. Keys wrapped with {} will be replaced with command args.	{"user": {"name": "{user}", "id": "{id}", "status": "create"}"{name}" and "{id}" will be replaced with name and id command input args.	Optional

Example

 "commands": [
     {
         "name": "url-report",
         "url_path": "vtapi/v2/url/report",
         "http_method": "GET",
         "description": "URL Report description",
         "context_path": "",
         "root_object": "",
         "headers": null,
         "unique_key": "",
         "body_format": null,
         "upload_file": false,
         "returns_file": false,
         "returns_entry_file": false,
         "arguments": [
             {
                 "name": "resource",
                 "description": "",
                 "required": false,
                 "is_array": false,
                 "default_value": "",
                 "predefined_values": [],
                 "ref": null,
                 "type_": null,
                 "in_": "query",
                 "in_object": null
             }
         ],
         "outputs": [
             {
                 "name": "scan_id",
                 "description": "",
                 "type_": "String"
             },
             {
                 "name": "response_code",
                 "description": "",
                 "type_": "Number"
             }
         ]
     }
 ]

Command Field Arguments

Field name	Field type	Description	Examples	Required
commands.arguments	list	List of command arguments. These arguments are passed as part of the request.		Optional
commands.arguments.in\_	string	Possible values are query, url, body. If set to query, the argument will be passed in the request url query in the following format: ?resource={resource}. If set to body, the argument will be passed in the request body. If set to url, the argument will be passed as part of the url in the following format: /vtapi/v2/url/{resource}.	query, url, body	Required
commands.arguments.description	string	Argument description.	Machine ID to be used to stop the isolation. e.g., 0a3250e0693a109f1affc9217be9459028aa8426	Optional
commands.arguments.required	boolean	Set to true if the argument is mandatory.	false	Optional
commands.arguments.is\_array	boolean	Set to true if the argument is of type array.	xdr-get-incidents receives an argument of type array incident_id_list. When a list of IDs is passed, the command returns all the incidents with the corresponding IDs.	Optional
commands.arguments.default\_value	string	Argument initial value.	size/limit arguments usually will have default values like 50.	Optional
commands.arguments.predefined\_values	list	List of strings. If the argument has a predefined list of possible values, then set this field.	['low','medium','high']	Optional
commands.arguments.type\_	string	Argument casting and conversion.	int -> size = int(size), array -> scan_ids = argToList(scan_ids)	Optional
commands.arguments.in\_object	list	Not supported yet.		Optional

Example

"arguments": [
    {
        "name": "size",
        "description": "Number of incidents to return.",
        "required": false,
        "is_array": false,
        "default_value": "10",
        "predefined_values": [],
        "ref": null,
        "type_": null,
        "in_": "query",
        "in_object": null
    }
]

Outputs

Field name	Field type	Description	Example	Required
commands.outputs	list	List of command outputs.		Optional
commands.outputs.name	string	JSON path to this field/output.	scan_id, alerts.severity	Required
commands.outputs.description	string	Describe what this field is.	Severity of the alert, possible values are low, medium, and high.	Optional
commands.outputs.type\_	string	Field/output type.	String, Number, Date, Unknown	Optional

Example

 "outputs": [
    {
        "name": "scan_id",
        "description": "",
        "type_": "String"
    },
    {
        "name": "response_code",
        "description": "",
        "type_": "Number"
    }
]

Request body

Defines the structure and the format of the request body. body_format must contain a value if the request contains a body. Keys that wrapped with {} will be replaced with command args. Request example:

• POST request with body.
• User creates the command with two arguments, name and id.
• In the body_format they are passed as "{name}" and {"id"}.

Request body:

{
   "profile": {
      "name": "some name",
      "id": "some id",
      "status": "created"
   }
}

In config file:

"body_format": {
   "profile": {
      "name": "{name}",
      "id": "{id}",
      "status": "created"
   }
}

Will generate code like:

def create_profile(self, name, id):
    ...

    data = {
       "profile": {
          "name": name,
          "id": id,
          "status": "created"
       }
    }

    response = self._http_request('POST', 'api/v1/profile', params=params, json_data=data, headers=headers)

    return response

Example files

• URLScan Postman Collection v2.1
• URLScan generated config file
• URLScan generated integration yml