The Demisto SDK library can be used to manage your Cortex XSOAR content with ease and efficiency.
Requirements:
- Python 3.9, 3.10 or 3.11.
- git installed.
- A linux, mac or WSL2 machine.
Windows machines are not supported - use WSL2 or run in a container instead.
-
Install -
pip3 install demisto-sdk
-
Upgrade -
pip3 install --upgrade demisto-sdk
-
Connect demisto-sdk with Cortex XSOAR server - In order that demisto-sdk and Cortex XSOAR server communicate, perform the following steps:
-
Get an API key for Cortex XSOAR/XSIAM-server -
Settings
->Integrations
->API keys
->Get your Key
(copy it) -
Set the following environment variables, or place an .env file at the root of the content pack:
export DEMISTO_BASE_URL=<http or https>://<demisto-server url or ip>:<port> export DEMISTO_API_KEY=<API key>
To use on Cortex XSIAM or Cortex XSOAR 8.x the
XSIAM_AUTH_ID
environment variable should also be set.export XSIAM_AUTH_ID=<auth id>
for example:
export DEMISTO_BASE_URL=http://127.0.0.1:8080 export DEMISTO_API_KEY=XXXXXXXXXXXXXXXXXXXXXX
As long as
XSIAM_AUTH_ID
environment variable is set, SDK commands will be configured to work with an XSIAM instance. In order to set Demisto SDK to work with Cortex XSOAR instance, you need to delete the XSIAM_AUTH_ID parameter from your environment.unset XSIAM_AUTH_ID
In case the primary git branch is not master, or the upstream is not named origin, set them with environment variables:
export DEMISTO_DEFAULT_BRANCH = <branch name here> export DEMISTO_DEFAULT_REMOTE = <upstream name here>
For more configurations, check the demisto-py repo (the SDK uses demisto-py to communicate with Cortex XSOAR).
-
For the Validate and Format commands to work properly:
- Install node.js, and make sure
@mdx-js/mdx
,fs-extra
andcommander
are installed in node-modules folder (npm install ...
). - Set the
DEMISTO_README_VALIDATION
environment variable to True.
MDX is used to validate markdown files, and make sure they render properly on XSOAR and xsoar.pan.dev.
- Install node.js, and make sure
-
Reload your terminal.
-
The demisto-sdk is made to work with Cortex content, structured similar to the official Cortex content repo.
Demisto-SDK commands work best when called from the content directory or any of its subfolders.
To run Demisto-SDK commands from other folders, you may set the DEMISTO_SDK_CONTENT_PATH
environment variable.
We recommend running all demisto-SDK commands from a folder with a git repo, or any of its subfolders. To suppress warnings about running commands outside of a content repo folder, set the DEMISTO_SDK_IGNORE_CONTENT_WARNING
environment variable.
You can use the SDK in the CLI as follows:
demisto-sdk <command> <args>
For more information, run demisto-sdk -h
.
For more information on a specific command execute demisto-sdk <command> -h
.
demisto-sdk
will check against the GitHub repository releases for a new version every time it runs and will issue a warning if you are not using the latest and greatest. If you wish to skip this check you can set the environment variable: DEMISTO_SDK_SKIP_VERSION_CHECK
. For example:
export DEMISTO_SDK_SKIP_VERSION_CHECK=yes
Supported commands:
- init
- Validate
- Lint
- Secrets
- Prepare-Content
- Split
- Format
- Run
- Run-playbook
- Upload
- Download
- Generate-docs
- Generate-test-playbook
- Generate-outputs
- Update-release-notes
- Zip-packs
- openapi-codegen
- postman-codegen
- generate-integration
- generate-yml-from-python
- generate-unit-tests
- pre-commit (experimental)
- setup-env
Log files are generated and stored automatically by default in the user's home directory:
Linux / macOS: $HOME/.demisto-sdk/logs
Windows: %USERPROFILE%\.demisto-sdk\logs
The default directory can be overriden using the --log-file-path
flag, or the DEMISTO_SDK_LOG_FILE_PATH
environment variable.
You can create your own configuration for the demisto-sdk
commands by creating a file named .demisto-sdk-conf
within the directory from which you run the commands.
This file will enable you to set a default value to the existing command flags that will take effect whenever the command is run.
This can be done by entering the following structure into the file:
[command_name]
flag_name=flag_default_value
Note: Make sure to use the flag's full name and input _
instead of a -
if it exists in the flag name (e.g. instead of no-docker-checks
use no_docker_checks
).
Here are a few examples:
-
As a user, I would like to not use the
mypy
linter in my environment when using thelint
command. In the.demisto-sdk-conf
file I'll enter:[lint] no_mypy=true
-
As a user, I would like to include untracked git files in my validation when running the
validate
command. In the.demisto-sdk-conf
file I'll enter:[validate] include_untracked=true
-
As a user, I would like to automatically use minor version changes when running the
update-release-notes
command. In the.demisto-sdk-conf
file I'll enter:[update-release-notes] update_type=minor
MIT - See LICENSE for more information.
Follow the guide found here to setup your demisto-sdk
dev environment.
The development environment is connected to the branch you are currently using in the SDK repository.
Contributions are welcome and appreciated. For information regarding contributing, press here.
An internet connection is required for the following commands to work properly:
Note that the following commands may work partially without an internet connection:
- Download - will fail when using the '-fmt, --run-format' argument.
- Lint - will fail when creating the image.
-
When working offline (or in an airgapped environment), set the
DEMISTO_SDK_OFFLINE_ENV
environment variable totrue
:export DEMISTO_SDK_OFFLINE_ENV=TRUE
When set, Demisto-SDK features requiring an internet connection will not be run, often saving some time and avoiding errors.
Docker is required to run certain commands.
The following command requires Docker:
However, some commands can be executed partially without Docker:
- Format - To run without Docker, use the
--no-graph
flag. - Lint - Docker is needed to run
pylint
,pytest
,powershell - test
, andpowershell - analyze
. - Generate-docs - To run without Docker, use the
--no-graph
flag. - Validate - To skip Docker validation, use the
--no-docker-checks
flag. - pre-commit - To run without Docker hooks, use the
--no-docker
flag.
For information regarding XSOAR CI/CD, please see this article
By default, the demisto-sdk
will use dockerhub
as the container registry to pull the integrations and scripts docker image.
In order configure a custom container registry, the following environment variables must be set:
DEMISTO_SDK_CONTAINER_REGISTRY
: the URL of the container registry.DEMISTO_SDK_CR_USER
: the username to use in the container registry.DEMISTO_SDK_CR_PASSWORD
: the password to use in the container registry.