zanshinsdk


Namezanshinsdk JSON
Version 1.5.2 PyPI version JSON
download
home_pagehttps://github.com/tenchi-security/zanshin-sdk-python
SummaryPython SDK to access the Tenchi Security Zanshin API v1
upload_time2023-01-20 17:26:11
maintainer
docs_urlNone
authorTenchi Security
requires_python
licenseApache Software License
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            |Coverage badge| |PyPI version shields.io| |PyPI pyversions|

Zanshin Python SDK
==================

This Python package contains an SDK to interact with the `API of the
Zanshin SaaS service <https://api.zanshin.tenchisecurity.com>`__ from
`Tenchi Security <https://www.tenchisecurity.com>`__.

This SDK is used to implement a command-line utility, which is available
on `Github <https://github.com/tenchi-security/zanshin-cli>`__ and on
`PyPI <https://pypi.python.org/pypi/zanshincli/>`__.

Setting up Credentials
----------------------

There are three ways that the SDK handles credentials. The order of
evaluation is:

-  `1st Client Parameters <#client-parameters>`__
-  `2nd Environment Variables <#environment-variables>`__
-  `3rd Config File <#config-file>`__

Client Parameters
~~~~~~~~~~~~~~~~~

When calling the ``Client`` class, you can pass the values API Key, API
URL, Proxy URL and User Agent you want to use as below:

.. code:: python

   from zanshinsdk import Client

   client = Client(api_key="my_zanshin_api_key")

   print(client.get_me())

..

   ⚠️ These values will overwrite anything you set as Environment
   Variables or in the Config File.

Environment Variables
~~~~~~~~~~~~~~~~~~~~~

You can use the following Environment Variables to configure Zanshin
SDK:

-  ``ZANSHIN_API_KEY``: Will setup your Zanshin credentials
-  ``ZANSHIN_API_URL``: Will define the API URL. Default is
   ``https://api.zanshin.tenchisecurity.com``
-  ``ZANSHIN_USER_AGENT``: If you want to overwrite the User Agent when
   calling Zanshin API
-  ``HTTP_PROXY | HTTPS_PROXY``: Zanshin SDK uses HTTPX under the hood,
   checkout the `Environment
   Variables <https://www.python-httpx.org/environment_variables/#proxies>`__
   section of their documentation for more use cases

Usage
^^^^^

.. code:: shell

   export ZANSHIN_API_KEY="eyJhbGciOiJIU..."

..

   ⚠️ These Environment Variables will overwrite anything you set on the
   Config File.

Config File
~~~~~~~~~~~

Second is by using a configuration file in the format created by the
Python
`RawConfigParser <https://docs.python.org/3/library/configparser.html#configparser.RawConfigParser>`__
class.

The file is located at ``~/.tenchi/config``, where ``~`` is the `current
user's home
directory <https://docs.python.org/3/library/pathlib.html#pathlib.Path.home>`__.

Each section is treated as a configuration profile, and the SDK will
look for a section called ``default`` if another is not explicitly
selected.

These are the supported options:

-  ``api_key`` (required) which contains the Zanshin API key obtained at
   the `Zanshin web
   portal <https://zanshin.tenchisecurity.com/my-profile>`__.
-  ``user_agent`` (optional) allows you to override the default
   user-agent header used by the SDK when making API requests.
-  ``api_url`` (optional) directs the SDK to use a different API
   endpoint than the default
   (`https://api.zanshin.tenchisecurity.com <https://api.zanshin.tenchisecurity.com>`__).

This is what a minimal configuration file looks like:

.. code:: ini

   [default]
   api_key = abcdefghijklmnopqrstuvxyz

The SDK
-------

The SDK uses Python 3 type hints extensively. It attempts to abstract
API artifacts such as pagination by using Python generators, thus making
the service easier to interact with.

The network connections are done using the wonderful
`httpx <https://www.python-httpx.org/>`__ library.

Currently it focuses on returning the parsed JSON values instead of
converting them into native classes for higher level abstractions.

The ``zanshinsdk.Client`` class is the main entry point of the SDK. Here
is a quick example that shows information about the owner of the API key
in use:

.. code:: python

   from zanshinsdk import Client
   from json import dumps

   client = Client()   # loads API key from the "default" profile in ~/.tenchi/config
   me = client.get_me()    # calls /me API endpoint
   print(dumps(me, indent=4))

For more examples, checkout the `docs <zanshinsdk/docs/README.md>`__.

All operations call ``raise_for_status`` on the httpx `Response
object <https://www.python-httpx.org/api/#response>`__ internally, so
any 4xx or 5xx will raise
`exceptions <https://www.python-httpx.org/exceptions/>`__.

Installing
----------

To install the SDK, you can use ``pip``. You have two options to install
ZanshinSDK:

-  *Essentials*

Using ``pip install zanshinsdk`` will install the SDK with all features
exception ability to perform onboarding of new Scan Targets. For this,
you'll need to install boto3.

-  *With Boto3*

With ``pip install zanshinsdk[with_boto3]`` you'll automatically install
`boto3 <https://boto3.amazonaws.com/v1/documentation/api/latest/index.html>`__
along with ZanshinSDK. This will enable you to perform Onboard of new
Scan Targets via SDK.

Testing
-------

To run all tests call ``make test`` on the project root directory. Make
sure there's a ``[default]`` profile configured, else some tests will
fail. Also, be sure to install ``boto3`` and ``moto[all]`` or some
integration tests will fail.

Support
=======

If you are a Zanshin customer and have any questions regarding the use
of the service, its API or this SDK package, please get in touch via
e-mail at support {at} tenchisecurity {dot} com or via the support
widget on the `Zanshin Portal <https://zanshin.tenchisecurity.com>`__.

.. |Coverage badge| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/wiki/tenchi-security/zanshin-sdk-python/python-coverage-comment-action-badge.json
.. |PyPI version shields.io| image:: https://img.shields.io/pypi/v/zanshinsdk.svg
   :target: https://pypi.python.org/pypi/zanshinsdk/
.. |PyPI pyversions| image:: https://img.shields.io/pypi/pyversions/zanshinsdk.svg
   :target: https://pypi.python.org/pypi/zanshinsdk/

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/tenchi-security/zanshin-sdk-python",
    "name": "zanshinsdk",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "",
    "author": "Tenchi Security",
    "author_email": "contact@tenchisecurity.com",
    "download_url": "https://files.pythonhosted.org/packages/d0/99/e1fda761d2fe25c8909aa346ee207971dfa367e2cde229d6f3f6c5fcf034/zanshinsdk-1.5.2.tar.gz",
    "platform": "any",
    "description": "|Coverage badge| |PyPI version shields.io| |PyPI pyversions|\n\nZanshin Python SDK\n==================\n\nThis Python package contains an SDK to interact with the `API of the\nZanshin SaaS service <https://api.zanshin.tenchisecurity.com>`__ from\n`Tenchi Security <https://www.tenchisecurity.com>`__.\n\nThis SDK is used to implement a command-line utility, which is available\non `Github <https://github.com/tenchi-security/zanshin-cli>`__ and on\n`PyPI <https://pypi.python.org/pypi/zanshincli/>`__.\n\nSetting up Credentials\n----------------------\n\nThere are three ways that the SDK handles credentials. The order of\nevaluation is:\n\n-  `1st Client Parameters <#client-parameters>`__\n-  `2nd Environment Variables <#environment-variables>`__\n-  `3rd Config File <#config-file>`__\n\nClient Parameters\n~~~~~~~~~~~~~~~~~\n\nWhen calling the ``Client`` class, you can pass the values API Key, API\nURL, Proxy URL and User Agent you want to use as below:\n\n.. code:: python\n\n   from zanshinsdk import Client\n\n   client = Client(api_key=\"my_zanshin_api_key\")\n\n   print(client.get_me())\n\n..\n\n   \u26a0\ufe0f These values will overwrite anything you set as Environment\n   Variables or in the Config File.\n\nEnvironment Variables\n~~~~~~~~~~~~~~~~~~~~~\n\nYou can use the following Environment Variables to configure Zanshin\nSDK:\n\n-  ``ZANSHIN_API_KEY``: Will setup your Zanshin credentials\n-  ``ZANSHIN_API_URL``: Will define the API URL. Default is\n   ``https://api.zanshin.tenchisecurity.com``\n-  ``ZANSHIN_USER_AGENT``: If you want to overwrite the User Agent when\n   calling Zanshin API\n-  ``HTTP_PROXY | HTTPS_PROXY``: Zanshin SDK uses HTTPX under the hood,\n   checkout the `Environment\n   Variables <https://www.python-httpx.org/environment_variables/#proxies>`__\n   section of their documentation for more use cases\n\nUsage\n^^^^^\n\n.. code:: shell\n\n   export ZANSHIN_API_KEY=\"eyJhbGciOiJIU...\"\n\n..\n\n   \u26a0\ufe0f These Environment Variables will overwrite anything you set on the\n   Config File.\n\nConfig File\n~~~~~~~~~~~\n\nSecond is by using a configuration file in the format created by the\nPython\n`RawConfigParser <https://docs.python.org/3/library/configparser.html#configparser.RawConfigParser>`__\nclass.\n\nThe file is located at ``~/.tenchi/config``, where ``~`` is the `current\nuser's home\ndirectory <https://docs.python.org/3/library/pathlib.html#pathlib.Path.home>`__.\n\nEach section is treated as a configuration profile, and the SDK will\nlook for a section called ``default`` if another is not explicitly\nselected.\n\nThese are the supported options:\n\n-  ``api_key`` (required) which contains the Zanshin API key obtained at\n   the `Zanshin web\n   portal <https://zanshin.tenchisecurity.com/my-profile>`__.\n-  ``user_agent`` (optional) allows you to override the default\n   user-agent header used by the SDK when making API requests.\n-  ``api_url`` (optional) directs the SDK to use a different API\n   endpoint than the default\n   (`https://api.zanshin.tenchisecurity.com <https://api.zanshin.tenchisecurity.com>`__).\n\nThis is what a minimal configuration file looks like:\n\n.. code:: ini\n\n   [default]\n   api_key = abcdefghijklmnopqrstuvxyz\n\nThe SDK\n-------\n\nThe SDK uses Python 3 type hints extensively. It attempts to abstract\nAPI artifacts such as pagination by using Python generators, thus making\nthe service easier to interact with.\n\nThe network connections are done using the wonderful\n`httpx <https://www.python-httpx.org/>`__ library.\n\nCurrently it focuses on returning the parsed JSON values instead of\nconverting them into native classes for higher level abstractions.\n\nThe ``zanshinsdk.Client`` class is the main entry point of the SDK. Here\nis a quick example that shows information about the owner of the API key\nin use:\n\n.. code:: python\n\n   from zanshinsdk import Client\n   from json import dumps\n\n   client = Client()   # loads API key from the \"default\" profile in ~/.tenchi/config\n   me = client.get_me()    # calls /me API endpoint\n   print(dumps(me, indent=4))\n\nFor more examples, checkout the `docs <zanshinsdk/docs/README.md>`__.\n\nAll operations call ``raise_for_status`` on the httpx `Response\nobject <https://www.python-httpx.org/api/#response>`__ internally, so\nany 4xx or 5xx will raise\n`exceptions <https://www.python-httpx.org/exceptions/>`__.\n\nInstalling\n----------\n\nTo install the SDK, you can use ``pip``. You have two options to install\nZanshinSDK:\n\n-  *Essentials*\n\nUsing ``pip install zanshinsdk`` will install the SDK with all features\nexception ability to perform onboarding of new Scan Targets. For this,\nyou'll need to install boto3.\n\n-  *With Boto3*\n\nWith ``pip install zanshinsdk[with_boto3]`` you'll automatically install\n`boto3 <https://boto3.amazonaws.com/v1/documentation/api/latest/index.html>`__\nalong with ZanshinSDK. This will enable you to perform Onboard of new\nScan Targets via SDK.\n\nTesting\n-------\n\nTo run all tests call ``make test`` on the project root directory. Make\nsure there's a ``[default]`` profile configured, else some tests will\nfail. Also, be sure to install ``boto3`` and ``moto[all]`` or some\nintegration tests will fail.\n\nSupport\n=======\n\nIf you are a Zanshin customer and have any questions regarding the use\nof the service, its API or this SDK package, please get in touch via\ne-mail at support {at} tenchisecurity {dot} com or via the support\nwidget on the `Zanshin Portal <https://zanshin.tenchisecurity.com>`__.\n\n.. |Coverage badge| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/wiki/tenchi-security/zanshin-sdk-python/python-coverage-comment-action-badge.json\n.. |PyPI version shields.io| image:: https://img.shields.io/pypi/v/zanshinsdk.svg\n   :target: https://pypi.python.org/pypi/zanshinsdk/\n.. |PyPI pyversions| image:: https://img.shields.io/pypi/pyversions/zanshinsdk.svg\n   :target: https://pypi.python.org/pypi/zanshinsdk/\n",
    "bugtrack_url": null,
    "license": "Apache Software License",
    "summary": "Python SDK to access the Tenchi Security Zanshin API v1",
    "version": "1.5.2",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d099e1fda761d2fe25c8909aa346ee207971dfa367e2cde229d6f3f6c5fcf034",
                "md5": "d5d5758de96f2cc8a88bcf86801e09ec",
                "sha256": "3c859ff5a13e2c0ab590fda086ff6d578a6f6b6c8f6ad0f3335ca05a59986060"
            },
            "downloads": -1,
            "filename": "zanshinsdk-1.5.2.tar.gz",
            "has_sig": false,
            "md5_digest": "d5d5758de96f2cc8a88bcf86801e09ec",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 25761,
            "upload_time": "2023-01-20T17:26:11",
            "upload_time_iso_8601": "2023-01-20T17:26:11.143709Z",
            "url": "https://files.pythonhosted.org/packages/d0/99/e1fda761d2fe25c8909aa346ee207971dfa367e2cde229d6f3f6c5fcf034/zanshinsdk-1.5.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-01-20 17:26:11",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "tenchi-security",
    "github_project": "zanshin-sdk-python",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "requirements": [],
    "lcname": "zanshinsdk"
}
        
Elapsed time: 0.03194s