# runZero Python SDK
[](https://pypi.org/project/runzero-sdk/)
[](https://pypi.org/project/runzero-sdk/)
[](https://opensource.org/license/bsd-2-clause/)
This project is currently in beta and subject to change.
## Overview
This is a Python API client for [runZero](https://www.runzero.com/) - a product that provides asset discovery and
network visibility to help you build and maintain a comprehensive inventory of your cyber assets. runZero customers can use this project to interact with their environment using runZero and Python.
Note: the APIs used with this client require a [Platform license](https://www.runzero.com/product/pricing/).
This project seeks to do only what is necessary to make interactions with runZero in your own Python code feel more
like any other local, Pythonic API. It uses code generated from the runZero
[API](https://github.com/runZeroInc/runzero-api), lightly wraps parts of it, and makes Python objects and functions
discoverable, consistent, and easy to use. We want you to concentrate on working with runZero, not HTTP.
## Installation
This project is [published to PyPI](https://pypi.org/project/runzero-sdk/) and can be installed using your local Python package manager.
```console
pip install runzero-sdk
```
## Usage
There are several examples of using the SDK for common tasks under the `/examples` directory in the repo.
General usage of the SDK involves creating a `runzero.Client()` for handling authentication, then passing that `Client`
to resource managers, such as the `runzero.CustomAssets()`, `runzero.Sites()`, `runzero.OrgsAdmin()`, and more.
A typical code flow would look like the following:
```python
import runzero
import runzero.api as rz
client = runzero.Client()
client.oauth_login(MY_CLIENT_ID, MY_CLIENT_SECRET)
orgs = rz.OrgsAdmin(client=client).get_all()
print(f"retrieved {len(orgs)} from our runZero account")
```
## Modules
The runzero-sdk package contains the following modules to group functionality.
### runzero.api
The `api` module contains all the http handlers for interacting with runZero api resources such as Sites, Orgs, Tasks, Custom Integrations, etc.
### runzero.types
The `types` module contains all the pydantic classes required for interacting with the runZero API resources such as Import Assets, Sites, Tasks, etc.
## Custom Import Asset field mappings
The following fields are available to be set for custom integration asset imports. Any field which matches the below field
names, either directly or via remapping, will be inserted into the corresponding `ImportAsset` field and validated to
ensure it meets the outlined constraints.
Any field which does not match the fields below will be placed under the `custom_attributes` field. Please see the
`ImportAsset` schema definition for more details: #/components/schemas/ImportAsset
* `id` - this `str` field is ***required*** to be set for all custom integration assets and is the unique identifier for the asset. If your asset does not have a unique id then we recommend you create one using `uuid.uuid4()`.
* `runZeroID` - a `uuid` field representing the unique identifier of an existing runZero asset to merge into.
* `network_interfaces` - this field is an array of objects representing the network interfaces of the asset. Please see the API Schema for details. #/components/schemas/ImportAsset/properties/networkInterfaces.
* `hostnames` - a `List[str]` field of all the hostnames associated with the asset. Each hostname has a maximum length of 260 characters and the `list` has a maximum of 100 hostnames.
* `domain` - a `str` field representing the domain associated with the asset. Maximum length of 260 characters.
* `first_seen_ts` - a `datetime.datetime` field representing the first time an asset was seen.
* `last_seen_ts` - a `datetime.datetime` field representing the last time an asset was seen.
* `os` - a `str` field which describes the operating system on the asset. Maximum length of 1024 characters.
* `os_version` - a `str` field which describes the version of the operating system running on the asset. Maximum length of 1024 characters.
* `manufacturer` - a `str` field which declares the manufacturer of the asset. Maximum length of 1024 characters.
* `model` - a `str` field which describes the manufacturers model of the asset. Maximum length of 1024 characters.
* `tags` - a `List[str]` field for all the tags to be associated with the asset in the runZero platform. Maximum of 100 tags and each tag has a maximum length of 1024 characters.
* `device_type` - a `str` field declaring the device type of the asset. Maximum length of 1024 characters.
## Feature requests and bug reports
To report a bug or request a new feature in the SDK, please open a support request using the in-product link. This will let us deduplicate and prioritize requests in parallel to already planned enhancements.
When preparing to report a bug, please try to determine whether it's related to the SDK or the runZero product itself. For improvements to or issues with the SDK, please include as much detail as possible about the problem you're looking to solve. For improvements to or issues with the runZero platform, please explore our [documentation](https://www.runzero.com/docs/) to see if there's related guidance or to verify that something isn't working as intended before opening a support request.
## Contributing a bug fix or feature
We look forward to being able to accept contributions from the community! However, until the project is stable enough, we'd rather you open an issue and have a discussion with the maintainers. Since we're actively working on this project, the fix may be forthcoming, or the area being improved may have a lot of change planned.
## Related Projects and Resources
This project does not currently support the full runZero API. The broader runZero API
[documentation](https://www.runzero.com/docs/leveraging-the-api/) includes both human- and machine-generated
API documentation.
runZero's OpenAPI [spec](https://github.com/runZeroInc/runzero-api) is updated as the platform is expanded. The
information published there can help you generate code if you have a need to use parts of the API not covered
in this project.
Raw data
{
"_id": null,
"home_page": "https://runzero.com/",
"name": "runzero-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "runzero, api, sdk",
"author": "runZero",
"author_email": "support@runzero.com",
"download_url": "https://files.pythonhosted.org/packages/df/d1/a83c539c3f02212341d1a0eecfa11ce58acb629d87bc4a9633f76683cbe7/runzero_sdk-0.8.4.tar.gz",
"platform": null,
"description": "# runZero Python SDK\n[](https://pypi.org/project/runzero-sdk/)\n[](https://pypi.org/project/runzero-sdk/)\n[](https://opensource.org/license/bsd-2-clause/)\n\nThis project is currently in beta and subject to change.\n\n\n## Overview\n\nThis is a Python API client for [runZero](https://www.runzero.com/) - a product that provides asset discovery and\nnetwork visibility to help you build and maintain a comprehensive inventory of your cyber assets. runZero customers can use this project to interact with their environment using runZero and Python.\n\nNote: the APIs used with this client require a [Platform license](https://www.runzero.com/product/pricing/).\n\nThis project seeks to do only what is necessary to make interactions with runZero in your own Python code feel more\nlike any other local, Pythonic API. It uses code generated from the runZero\n[API](https://github.com/runZeroInc/runzero-api), lightly wraps parts of it, and makes Python objects and functions\ndiscoverable, consistent, and easy to use. We want you to concentrate on working with runZero, not HTTP.\n\n\n## Installation\n\nThis project is [published to PyPI](https://pypi.org/project/runzero-sdk/) and can be installed using your local Python package manager.\n\n```console\npip install runzero-sdk\n```\n\n## Usage\n\nThere are several examples of using the SDK for common tasks under the `/examples` directory in the repo.\n\nGeneral usage of the SDK involves creating a `runzero.Client()` for handling authentication, then passing that `Client`\nto resource managers, such as the `runzero.CustomAssets()`, `runzero.Sites()`, `runzero.OrgsAdmin()`, and more.\n\nA typical code flow would look like the following:\n\n```python\nimport runzero\nimport runzero.api as rz\n\nclient = runzero.Client()\nclient.oauth_login(MY_CLIENT_ID, MY_CLIENT_SECRET)\n\norgs = rz.OrgsAdmin(client=client).get_all()\nprint(f\"retrieved {len(orgs)} from our runZero account\")\n```\n\n## Modules\n\nThe runzero-sdk package contains the following modules to group functionality.\n\n### runzero.api\n\nThe `api` module contains all the http handlers for interacting with runZero api resources such as Sites, Orgs, Tasks, Custom Integrations, etc.\n\n### runzero.types\n\nThe `types` module contains all the pydantic classes required for interacting with the runZero API resources such as Import Assets, Sites, Tasks, etc.\n\n## Custom Import Asset field mappings\n\nThe following fields are available to be set for custom integration asset imports. Any field which matches the below field\nnames, either directly or via remapping, will be inserted into the corresponding `ImportAsset` field and validated to\nensure it meets the outlined constraints.\n\nAny field which does not match the fields below will be placed under the `custom_attributes` field. Please see the\n`ImportAsset` schema definition for more details: #/components/schemas/ImportAsset\n\n* `id` - this `str` field is ***required*** to be set for all custom integration assets and is the unique identifier for the asset. If your asset does not have a unique id then we recommend you create one using `uuid.uuid4()`.\n* `runZeroID` - a `uuid` field representing the unique identifier of an existing runZero asset to merge into.\n* `network_interfaces` - this field is an array of objects representing the network interfaces of the asset. Please see the API Schema for details. #/components/schemas/ImportAsset/properties/networkInterfaces.\n* `hostnames` - a `List[str]` field of all the hostnames associated with the asset. Each hostname has a maximum length of 260 characters and the `list` has a maximum of 100 hostnames.\n* `domain` - a `str` field representing the domain associated with the asset. Maximum length of 260 characters.\n* `first_seen_ts` - a `datetime.datetime` field representing the first time an asset was seen.\n* `last_seen_ts` - a `datetime.datetime` field representing the last time an asset was seen.\n* `os` - a `str` field which describes the operating system on the asset. Maximum length of 1024 characters.\n* `os_version` - a `str` field which describes the version of the operating system running on the asset. Maximum length of 1024 characters.\n* `manufacturer` - a `str` field which declares the manufacturer of the asset. Maximum length of 1024 characters.\n* `model` - a `str` field which describes the manufacturers model of the asset. Maximum length of 1024 characters.\n* `tags` - a `List[str]` field for all the tags to be associated with the asset in the runZero platform. Maximum of 100 tags and each tag has a maximum length of 1024 characters.\n* `device_type` - a `str` field declaring the device type of the asset. Maximum length of 1024 characters.\n\n## Feature requests and bug reports\n\nTo report a bug or request a new feature in the SDK, please open a support request using the in-product link. This will let us deduplicate and prioritize requests in parallel to already planned enhancements.\n\nWhen preparing to report a bug, please try to determine whether it's related to the SDK or the runZero product itself. For improvements to or issues with the SDK, please include as much detail as possible about the problem you're looking to solve. For improvements to or issues with the runZero platform, please explore our [documentation](https://www.runzero.com/docs/) to see if there's related guidance or to verify that something isn't working as intended before opening a support request.\n\n\n## Contributing a bug fix or feature\n\nWe look forward to being able to accept contributions from the community! However, until the project is stable enough, we'd rather you open an issue and have a discussion with the maintainers. Since we're actively working on this project, the fix may be forthcoming, or the area being improved may have a lot of change planned.\n\n\n## Related Projects and Resources\n\nThis project does not currently support the full runZero API. The broader runZero API\n[documentation](https://www.runzero.com/docs/leveraging-the-api/) includes both human- and machine-generated\nAPI documentation.\n\nrunZero's OpenAPI [spec](https://github.com/runZeroInc/runzero-api) is updated as the platform is expanded. The\ninformation published there can help you generate code if you have a need to use parts of the API not covered\nin this project.\n\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "The runZero platform sdk",
"version": "0.8.4",
"project_urls": {
"Documentation": "https://runzeroinc.github.io/runzero-sdk-py",
"Homepage": "https://runzero.com/",
"Repository": "https://github.com/runZeroInc/runzero-sdk-py"
},
"split_keywords": [
"runzero",
" api",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "418b535477c045e7917d914db376d80b899010d1d11129ba80678013d9104bfd",
"md5": "d1970513b61c6d7667e0d9006c9ea5bb",
"sha256": "19a1c3f2d9f01b73d38ff18879b5ed02f276f52cabb89bc2bd0e9cbf3a1d380b"
},
"downloads": -1,
"filename": "runzero_sdk-0.8.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d1970513b61c6d7667e0d9006c9ea5bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 56358,
"upload_time": "2024-05-23T14:41:28",
"upload_time_iso_8601": "2024-05-23T14:41:28.964415Z",
"url": "https://files.pythonhosted.org/packages/41/8b/535477c045e7917d914db376d80b899010d1d11129ba80678013d9104bfd/runzero_sdk-0.8.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dfd1a83c539c3f02212341d1a0eecfa11ce58acb629d87bc4a9633f76683cbe7",
"md5": "e1c94f09cfc78133332ab89cb4d3d87b",
"sha256": "e973f531c9e5cfeaad5c51dc42c013a187f0e6f715e958f7ecde0de95abdf0d6"
},
"downloads": -1,
"filename": "runzero_sdk-0.8.4.tar.gz",
"has_sig": false,
"md5_digest": "e1c94f09cfc78133332ab89cb4d3d87b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 47831,
"upload_time": "2024-05-23T14:41:30",
"upload_time_iso_8601": "2024-05-23T14:41:30.767624Z",
"url": "https://files.pythonhosted.org/packages/df/d1/a83c539c3f02212341d1a0eecfa11ce58acb629d87bc4a9633f76683cbe7/runzero_sdk-0.8.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-23 14:41:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "runZeroInc",
"github_project": "runzero-sdk-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "runzero-sdk"
}
JSON
