Package: demisto-py
Demisto Client for PythonA Python library for the Demisto API.Version 2.x is compatible with Demisto server version 4.5 and later.Demisto for Python UsageThis section covers the steps you need to take to get the client configured.1. Get a Demisto API KeyFollow these instructions to generate your Demisto API Key.In Demisto, navigate toSettings > API Keys.Click theGenerate Your Keybutton.To avoid hard coding configurations in your code, it is possible to specify configuration params
as the following environment variables (env variables will be used if parameters are not specified):DEMISTO_BASE_URLDEMISTO_API_KEYDEMISTO_ADVANCED_API_KEYDEMISTO_USERNAMEDEMISTO_PASSWORDDEMISTO_HTTP_HEADERS (must be in the form of: header1=value1,header2=value2,header3=value3,...headerN=valueN)DEMISTO_VERIFY_SSL (true/false. Default: true)DEMISTO_API_KEY_ID (for Cortex XSIAM only. If set, Cortex XSIAM API will be used)SSL_CERT_FILE (specify an alternate certificate bundle)2. Create a Demisto client instance with the api-key and server-urlimportdemisto_client# Also possible to set env variables: DEMISTO_API_KEY and DEMISTO_BASE_URLapi_key='YOUR_API_KEY'host='https://YOUR_DEMISTO_HOST'api_instance=demisto_client.configure(base_url=host,api_key=api_key)For Cortex XSIAM, we need to set the auth_idimportdemisto_client# Also possible to set env variables: DEMISTO_API_KEY, DEMISTO_BASE_URL and DEMISTO_API_KEY_IDapi_key='YOUR_API_KEY'auth_id='THE AUTHORIZATION ID'host='https://YOUR_XSIAM_HOST'api_instance=demisto_client.configure(base_url=host,api_key=api_key,auth_id=auth_id)Alternatively, you can login with username and password (only in xsoar):importdemisto_client# Also possible to set env variables: DEMISTO_USERNAME DEMISTO_PASSWORD and DEMISTO_BASE_URLhost='https://YOUR_DEMISTO_HOST'username='YOUR_USERNAME'password='YOUR_PASSWORD'api_instance=demisto_client.configure(base_url=host,username=username,password=password)3. Create incidentsimportdemisto_client.demisto_apifromdemisto_client.demisto_api.restimportApiExceptionapi_key='YOUR_API_KEY'host='https://YOUR_DEMISTO_HOST'api_instance=demisto_client.configure(base_url=host,api_key=api_key,debug=False)create_incident_request=demisto_client.demisto_api.CreateIncidentRequest()create_incident_request.name='Sample Simulation Incident'create_incident_request.type='Simulation'create_incident_request.owner='Admin'try:api_response=api_instance.create_incident(create_incident_request=create_incident_request)print(api_response)exceptApiExceptionase:print("Exception when calling DefaultApi->create_incident:%s\n"%e)Additional examples available in thedocsand under theexamples folder.API DocumentationAPI Documentation based upon the Demisto Server Swagger API is availablehereTroubleshootingAPI KeyIf when using an API key you encounter a response similar to the following:{"id":"forbidden","status":403,"title":"Forbidden","detail":"Issue with CSRF code","error":"http: named cookie not present","encrypted":false,"multires":null}It means your API key is invalid. Make sure you are using a valid API key. You can check your API key by using curl with the following request:curl-i-k-H'Authorization: YOUR_API_KEY'https://your-demisto.server.url/aboutFor a valid API key you will receive a response similar to the following:HTTP/1.1200OK
Strict-Transport-Security:max-age=10886400000000000;includeSubDomains
X-Content-Type-Options:nosniff
X-Frame-Options:DENY
X-Xss-Protection:1;mode=block
Date:Thu,04Jun202009:27:53GMT
Content-Length:189Content-Type:text/plain;charset=utf-8{"demistoVersion":"5.5.0",...}ContributingContributions are welcome and appreciated. To contribute follow the instructions below and submit a PR.Before merging any PRs, we need all contributors to sign a contributor license agreement. By signing a contributor license agreement, we ensure that the community is free to use your contributions.When you open a new pull request, a bot will evaluate whether you have signed the CLA. If required, the bot will comment on the pull request, including a link to accept the agreement. The CLA document is also available for review as aPDF.If thelicense/clastatus check remains onPending, even though all contributors have accepted the CLA, you can recheck the CLA status by visiting the following link (replace[PRID]with the ID of your PR):https://cla-assistant.io/check/demisto/demisto-py?pullRequest=[PRID] .Dev Environment SetupWe will now setup a quick virtualenv in which we will install thedemisto-pyversion you are currently working on.
This will be used as your testing environment, you do not need to update it again or re-run in any way.Make sure you have python3 installed.Make sure you havePoetryinstalled.runpoetry installFor further reading about Poetry, you can refer toPoetry documentation.You have now setup the yourdemisto-pydev environment!To activate it simply run:poetry shell.To deactivate the virtual environment and return simply run:exit.Running unit-tests using PytestWe usepytestto run unit tests.Simply usepoetryto run your tests on a relevant folder. For example:poetry run python -m pytest testsTo run with a specific python version (see thedemisto-py PyPi pagefor the current supported versions), usepoetry environmentsto switch to a different env with a different python version.Code GenerationLibrary code was generated using the Demisto Server 4.5.0 Swagger definition with modifications to support later Server versions.Important:All code underdemisto_client/demisto_apiis generated using the swagger code generation tool. Do not modify this code directly.We use a script to run the generate tool and then modify as needed.
If you would like to contributeDO NOTmodify the generated code directly, modify the script:gen-code.shand then re-generate the code.To generate the code run (requires bash, sed and docker):./gen-code.shPublishing a Release (demisto devs)After merging tomaster, a test deployment will be pushed to:https://test.pypi.org/project/demisto-py/.
You can test the test package by following the pip install instructions.
For example:pipinstall-ihttps://test.pypi.org/simple/demisto-pySteps to publish a production release:Make sureCHANGELOG.mdis up to date.Update the version number in thepyproject.tomlfile to the new version.Create and push a tag with the release version using git.
For example:gittagv2.0.19
gitpushoriginv2.0.19Check that the circleci build completes successfully. Once done, the release will be pushed to:https://pypi.org/project/demisto-py/.Update GitHub releases: go totags pageand for the relevant tag choose from the right drop down menu:Create release. Name the release the same as the tag. Copy the text from previous releases for the description.Congratulations! The release is now public.LicenseApache 2.0 - SeeLICENSEfor more information.