> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/demisto-sdk-development-guide/demisto-sdk-guide/demisto-sdk-commands/generate-integration.md). # generate-integration 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](/demisto-sdk-development-guide/demisto-sdk-guide/demisto-sdk-commands/postman-codegen.md) command.
Arguments | `-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](https://github.com/demisto/demisto-sdk/blob/master/demisto_sdk/commands/postman_codegen/resources/config-urlscanio.json) | `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. | | 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. ```programlisting "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. ```programlisting "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`. ```programlisting "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. ```programlisting "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` ```programlisting "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 ```programlisting  "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 ```programlisting "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 ```programlisting  "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: ```programlisting {   "profile": {      "name": "some name",      "id": "some id",      "status": "created"   } } ``` In config file: ```programlisting "body_format": {   "profile": {      "name": "{name}",      "id": "{id}",      "status": "created"   } } ``` Will generate code like: ```programlisting 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](https://github.com/demisto/demisto-sdk/blob/master/demisto_sdk/commands/postman_codegen/resources/urlscan.io.postman_collection.json) * [URLScan generated config file](https://github.com/demisto/demisto-sdk/blob/master/demisto_sdk/commands/postman_codegen/resources/config-urlscanio.json) * [URLScan generated integration yml](https://github.com/demisto/demisto-sdk/blob/master/demisto_sdk/commands/postman_codegen/resources/integration-urlscanio.yml)
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/demisto-sdk-development-guide/demisto-sdk-guide/demisto-sdk-commands/generate-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.