# Demisto Client for Python
[![PyPI version](https://badge.fury.io/py/demisto-py.svg)](https://badge.fury.io/py/demisto-py)
[![CircleCI](https://circleci.com/gh/demisto/demisto-py/tree/master.svg?style=svg)](https://circleci.com/gh/demisto/demisto-py/tree/master)
A Python library for the Demisto API.
Version 2.x is compatible with Demisto server version 4.5 and later.
## Demisto for Python Usage
This section covers the steps you need to take to get the client configured.
### 1. Get a Demisto API Key
Follow these instructions to generate your Demisto API Key.
1. In Demisto, navigate to **Settings > API Keys**.
2. Click the **Generate Your Key** button.
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_URL
* DEMISTO_API_KEY
* DEMISTO_ADVANCED_API_KEY
* DEMISTO_USERNAME
* DEMISTO_PASSWORD
* DEMISTO_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-url
```python
import demisto_client
# Also possible to set env variables: DEMISTO_API_KEY and DEMISTO_BASE_URL
api_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_id**
```python
import demisto_client
# Also possible to set env variables: DEMISTO_API_KEY, DEMISTO_BASE_URL and DEMISTO_API_KEY_ID
api_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):**
```python
import demisto_client
# Also possible to set env variables: DEMISTO_USERNAME DEMISTO_PASSWORD and DEMISTO_BASE_URL
host = 'https://YOUR_DEMISTO_HOST'
username = 'YOUR_USERNAME'
password = 'YOUR_PASSWORD'
api_instance = demisto_client.configure(base_url=host, username=username, password=password)
```
### 3. Create incidents
```python
import demisto_client.demisto_api
from demisto_client.demisto_api.rest import ApiException
api_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)
except ApiException as e:
print("Exception when calling DefaultApi->create_incident: %s\n" % e)
```
Additional examples available in the [docs](docs/README.md) and under the [examples folder](examples/).
---
## API Documentation
API Documentation based upon the Demisto Server Swagger API is available [here](docs/README.md)
---
## Troubleshooting
### API Key
If when using an API key you encounter a response similar to the following:
```json
{"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:
```bash
curl -i -k -H 'Authorization: YOUR_API_KEY' https://your-demisto.server.url/about
```
For a valid API key you will receive a response similar to the following:
```BASH
HTTP/1.1 200 OK
Strict-Transport-Security: max-age=10886400000000000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-Xss-Protection: 1; mode=block
Date: Thu, 04 Jun 2020 09:27:53 GMT
Content-Length: 189
Content-Type: text/plain; charset=utf-8
{"demistoVersion":"5.5.0", ...}
```
---
## Contributing
Contributions 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 a [PDF](https://github.com/demisto/content/blob/master/docs/cla.pdf).
If the `license/cla` status check remains on *Pending*, 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 Setup
We will now setup a quick virtualenv in which we will install the `demisto-py` version 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.
1. Make sure you have python3 installed.
2. Make sure you have [Poetry](https://python-poetry.org/) installed.
3. run `poetry install`
4. For further reading about Poetry, you can refer to [Poetry documentation](https://python-poetry.org/).
You have now setup the your `demisto-py` dev environment!
To activate it simply run: `poetry shell`.
To deactivate the virtual environment and return simply run: `exit`.
---
## Running unit-tests using Pytest
We use [pytest](https://github.com/pytest-dev/pytest) to run unit tests.
Simply use `poetry` to run your tests on a relevant folder. For example:
```
poetry run python -m pytest tests
```
To run with a specific python version (see the [demisto-py PyPi page](https://pypi.org/project/demisto-py/) for the current supported versions), use [poetry environments](https://python-poetry.org/docs/managing-environments/) to switch to a different env with a different python version.
---
## Code Generation
Library code was generated using the Demisto Server 4.5.0 Swagger definition with modifications to support later Server versions.
**Important:** All code under [demisto_client/demisto_api](demisto_client/demisto_api) is 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 contribute **DO NOT** modify the generated code directly, modify the script: [gen-code.sh](gen-code.sh) and then re-generate the code.
To generate the code run (requires bash, sed and docker):
```bash
./gen-code.sh
```
---
## Publishing a Release (demisto devs)
After merging to `master`, 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:
```bash
pip install -i https://test.pypi.org/simple/ demisto-py
```
Steps to publish a production release:
* Make sure [CHANGELOG.md](CHANGELOG.md) is up to date.
* Update the version number in the `pyproject.toml` file to the new version.
* Create and push a tag with the release version using git.
For example:
```bash
git tag v2.0.19
git push origin v2.0.19
```
* Check that the circleci build completes successfully. Once done, the release will be pushed to: <https://pypi.org/project/demisto-py/> .
* Update GitHub releases: go to [tags page](https://github.com/demisto/demisto-py/tags) and 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.
---
## License
Apache 2.0 - See [LICENSE](LICENSE) for more information.
Raw data
{
"_id": null,
"home_page": "https://github.com/demisto/demisto-py",
"name": "demisto-py",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<=3.12",
"maintainer_email": "",
"keywords": "Swagger,Demisto API",
"author": "Demisto",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/7c/20/60d7eed587ebd0954e849b88e38cbb1ddc369f60345ee508a1be6fabc7c0/demisto_py-3.2.14.tar.gz",
"platform": null,
"description": "# Demisto Client for Python\n\n[![PyPI version](https://badge.fury.io/py/demisto-py.svg)](https://badge.fury.io/py/demisto-py)\n[![CircleCI](https://circleci.com/gh/demisto/demisto-py/tree/master.svg?style=svg)](https://circleci.com/gh/demisto/demisto-py/tree/master)\n\n\nA Python library for the Demisto API.\n\nVersion 2.x is compatible with Demisto server version 4.5 and later.\n\n## Demisto for Python Usage\n\nThis section covers the steps you need to take to get the client configured.\n\n### 1. Get a Demisto API Key\n\nFollow these instructions to generate your Demisto API Key.\n\n1. In Demisto, navigate to **Settings > API Keys**.\n2. Click the **Generate Your Key** button.\n\nTo avoid hard coding configurations in your code, it is possible to specify configuration params\nas the following environment variables (env variables will be used if parameters are not specified):\n\n* DEMISTO_BASE_URL\n* DEMISTO_API_KEY\n* DEMISTO_ADVANCED_API_KEY\n* DEMISTO_USERNAME\n* DEMISTO_PASSWORD\n* DEMISTO_HTTP_HEADERS (must be in the form of: header1=value1,header2=value2,header3=value3,...headerN=valueN)\n* DEMISTO_VERIFY_SSL (true/false. Default: true)\n* DEMISTO_API_KEY_ID (for Cortex XSIAM only. If set, Cortex XSIAM API will be used)\n* SSL_CERT_FILE (specify an alternate certificate bundle)\n\n### 2. Create a Demisto client instance with the api-key and server-url\n\n```python\nimport demisto_client\n\n# Also possible to set env variables: DEMISTO_API_KEY and DEMISTO_BASE_URL\napi_key = 'YOUR_API_KEY'\nhost = 'https://YOUR_DEMISTO_HOST'\n\napi_instance = demisto_client.configure(base_url=host, api_key=api_key)\n\n```\n\n**For Cortex XSIAM, we need to set the auth_id**\n```python\nimport demisto_client\n\n# Also possible to set env variables: DEMISTO_API_KEY, DEMISTO_BASE_URL and DEMISTO_API_KEY_ID\napi_key = 'YOUR_API_KEY'\nauth_id = 'THE AUTHORIZATION ID'\nhost = 'https://YOUR_XSIAM_HOST'\n\napi_instance = demisto_client.configure(base_url=host, api_key=api_key, auth_id=auth_id)\n\n```\n\n**Alternatively, you can login with username and password (only in xsoar):**\n\n```python\nimport demisto_client\n\n# Also possible to set env variables: DEMISTO_USERNAME DEMISTO_PASSWORD and DEMISTO_BASE_URL\nhost = 'https://YOUR_DEMISTO_HOST'\nusername = 'YOUR_USERNAME'\npassword = 'YOUR_PASSWORD'\n\napi_instance = demisto_client.configure(base_url=host, username=username, password=password)\n```\n\n### 3. Create incidents\n\n```python\nimport demisto_client.demisto_api\nfrom demisto_client.demisto_api.rest import ApiException\n\n\napi_key = 'YOUR_API_KEY'\nhost = 'https://YOUR_DEMISTO_HOST'\n\napi_instance = demisto_client.configure(base_url=host, api_key=api_key, debug=False)\ncreate_incident_request = demisto_client.demisto_api.CreateIncidentRequest()\n\ncreate_incident_request.name = 'Sample Simulation Incident'\ncreate_incident_request.type = 'Simulation'\ncreate_incident_request.owner = 'Admin'\n\ntry:\n api_response = api_instance.create_incident(create_incident_request=create_incident_request)\n print(api_response)\nexcept ApiException as e:\n print(\"Exception when calling DefaultApi->create_incident: %s\\n\" % e)\n\n```\n\nAdditional examples available in the [docs](docs/README.md) and under the [examples folder](examples/).\n\n---\n\n## API Documentation\n\nAPI Documentation based upon the Demisto Server Swagger API is available [here](docs/README.md)\n\n---\n\n## Troubleshooting\n\n### API Key\n\nIf when using an API key you encounter a response similar to the following:\n\n```json\n{\"id\":\"forbidden\",\"status\":403,\"title\":\"Forbidden\",\"detail\":\"Issue with CSRF code\",\"error\":\"http: named cookie not present\",\"encrypted\":false,\"multires\":null}\n```\n\nIt 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:\n\n```bash\n curl -i -k -H 'Authorization: YOUR_API_KEY' https://your-demisto.server.url/about\n```\n\nFor a valid API key you will receive a response similar to the following:\n\n```BASH\nHTTP/1.1 200 OK\nStrict-Transport-Security: max-age=10886400000000000; includeSubDomains\nX-Content-Type-Options: nosniff\nX-Frame-Options: DENY\nX-Xss-Protection: 1; mode=block\nDate: Thu, 04 Jun 2020 09:27:53 GMT\nContent-Length: 189\nContent-Type: text/plain; charset=utf-8\n\n{\"demistoVersion\":\"5.5.0\", ...}\n```\n\n---\n\n## Contributing\n\nContributions are welcome and appreciated. To contribute follow the instructions below and submit a PR.\n\nBefore 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.\n\nWhen 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 a [PDF](https://github.com/demisto/content/blob/master/docs/cla.pdf).\n\nIf the `license/cla` status check remains on *Pending*, 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>] .\n\n---\n\n## Dev Environment Setup\n\nWe will now setup a quick virtualenv in which we will install the `demisto-py` version you are currently working on.\nThis will be used as your testing environment, you do not need to update it again or re-run in any way.\n\n1. Make sure you have python3 installed.\n\n2. Make sure you have [Poetry](https://python-poetry.org/) installed.\n\n3. run `poetry install`\n\n4. For further reading about Poetry, you can refer to [Poetry documentation](https://python-poetry.org/).\n\nYou have now setup the your `demisto-py` dev environment!\n\nTo activate it simply run: `poetry shell`.\n\nTo deactivate the virtual environment and return simply run: `exit`.\n\n---\n\n## Running unit-tests using Pytest\n\nWe use [pytest](https://github.com/pytest-dev/pytest) to run unit tests.\n\nSimply use `poetry` to run your tests on a relevant folder. For example:\n```\npoetry run python -m pytest tests\n```\n\nTo run with a specific python version (see the [demisto-py PyPi page](https://pypi.org/project/demisto-py/) for the current supported versions), use [poetry environments](https://python-poetry.org/docs/managing-environments/) to switch to a different env with a different python version.\n\n---\n\n\n## Code Generation\n\nLibrary code was generated using the Demisto Server 4.5.0 Swagger definition with modifications to support later Server versions.\n\n**Important:** All code under [demisto_client/demisto_api](demisto_client/demisto_api) is generated using the swagger code generation tool. Do not modify this code directly.\n\nWe use a script to run the generate tool and then modify as needed.\nIf you would like to contribute **DO NOT** modify the generated code directly, modify the script: [gen-code.sh](gen-code.sh) and then re-generate the code.\n\nTo generate the code run (requires bash, sed and docker):\n\n```bash\n./gen-code.sh\n```\n\n---\n\n## Publishing a Release (demisto devs)\n\nAfter merging to `master`, a test deployment will be pushed to: <https://test.pypi.org/project/demisto-py/> .\nYou can test the test package by following the pip install instructions.\nFor example:\n\n```bash\npip install -i https://test.pypi.org/simple/ demisto-py\n```\n\nSteps to publish a production release:\n\n* Make sure [CHANGELOG.md](CHANGELOG.md) is up to date.\n* Update the version number in the `pyproject.toml` file to the new version.\n* Create and push a tag with the release version using git.\nFor example:\n\n ```bash\n git tag v2.0.19\n git push origin v2.0.19\n ```\n\n* Check that the circleci build completes successfully. Once done, the release will be pushed to: <https://pypi.org/project/demisto-py/> .\n* Update GitHub releases: go to [tags page](https://github.com/demisto/demisto-py/tags) and 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.\n\nCongratulations! The release is now public.\n\n---\n## License\n\nApache 2.0 - See [LICENSE](LICENSE) for more information.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "\"A Python library for the Demisto API\"",
"version": "3.2.14",
"project_urls": {
"Homepage": "https://github.com/demisto/demisto-py"
},
"split_keywords": [
"swagger",
"demisto api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8cdefaed39d4c2356cb997371845e664dbfce71408380f4fd87a02740e24c537",
"md5": "2235be285bcf9409cc1345fefb95ffed",
"sha256": "aa6bf1fa3ff93f30de53f0a145840c50bd25cd9b471dc93257c2603862047e0a"
},
"downloads": -1,
"filename": "demisto_py-3.2.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2235be285bcf9409cc1345fefb95ffed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<=3.12",
"size": 506203,
"upload_time": "2024-02-12T13:07:31",
"upload_time_iso_8601": "2024-02-12T13:07:31.488018Z",
"url": "https://files.pythonhosted.org/packages/8c/de/faed39d4c2356cb997371845e664dbfce71408380f4fd87a02740e24c537/demisto_py-3.2.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7c2060d7eed587ebd0954e849b88e38cbb1ddc369f60345ee508a1be6fabc7c0",
"md5": "818366cbcf0e4df198f53ab1c2f66756",
"sha256": "4d6af4e89b5232bffe7f0a48bd3c187ef58f9f494af049c2dbd27e10fccc3f62"
},
"downloads": -1,
"filename": "demisto_py-3.2.14.tar.gz",
"has_sig": false,
"md5_digest": "818366cbcf0e4df198f53ab1c2f66756",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<=3.12",
"size": 201636,
"upload_time": "2024-02-12T13:07:33",
"upload_time_iso_8601": "2024-02-12T13:07:33.707457Z",
"url": "https://files.pythonhosted.org/packages/7c/20/60d7eed587ebd0954e849b88e38cbb1ddc369f60345ee508a1be6fabc7c0/demisto_py-3.2.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-12 13:07:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "demisto",
"github_project": "demisto-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "demisto-py"
}