The runZero platform sdk
Project description
runZero Python SDK
This project is currently in beta and subject to change.
Overview
This is a Python API client for runZero - 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 are only available to customers of the Professional and Enterprise editions of runZero.
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, 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 and can be installed using your local Python package manager.
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:
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
- thisstr
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 usinguuid.uuid4()
.runZeroID
- auuid
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
- aList[str]
field of all the hostnames associated with the asset. Each hostname has a maximum length of 260 characters and thelist
has a maximum of 100 hostnames.domain
- astr
field representing the domain associated with the asset. Maximum length of 260 characters.first_seen_ts
- adatetime.datetime
field representing the first time an asset was seen.last_seen_ts
- adatetime.datetime
field representing the last time an asset was seen.os
- astr
field which describes the operating system on the asset. Maximum length of 1024 characters.os_version
- astr
field which describes the version of the operating system running on the asset. Maximum length of 1024 characters.manufacturer
- astr
field which declares the manufacturer of the asset. Maximum length of 1024 characters.model
- astr
field which describes the manufacturers model of the asset. Maximum length of 1024 characters.tags
- aList[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
- astr
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 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 includes both human- and machine-generated API documentation.
runZero's OpenAPI spec 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for runzero_sdk-0.5.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ebe2c0147a4f4bd632f81f81e1859e63a975ad7c540aff39f751242c243365a8 |
|
MD5 | 8d38c8ecd241624dfd2b6c65af04226f |
|
BLAKE2b-256 | 989aa7f880d2fa0fc7c98136f1ba5a23c2f41281cf26b5aad1cd8f142be50b04 |