Package: runzero-sdk
runZero Python SDKThis project is currently in beta and subject to change.OverviewThis is a Python API client forrunZero- 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 aPlatform license.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 runZeroAPI, 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.InstallationThis project ispublished to PyPIand can be installed using your local Python package manager.pip install runzero-sdkUsageThere are several examples of using the SDK for common tasks under the/examplesdirectory in the repo.General usage of the SDK involves creating arunzero.Client()for handling authentication, then passing thatClientto resource managers, such as therunzero.CustomAssets(),runzero.Sites(),runzero.OrgsAdmin(), and more.A typical code flow would look like the following:importrunzeroimportrunzero.apiasrzclient=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")ModulesThe runzero-sdk package contains the following modules to group functionality.runzero.apiTheapimodule contains all the http handlers for interacting with runZero api resources such as Sites, Orgs, Tasks, Custom Integrations, etc.runzero.typesThetypesmodule contains all the pydantic classes required for interacting with the runZero API resources such as Import Assets, Sites, Tasks, etc.Custom Import Asset field mappingsThe 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 correspondingImportAssetfield and validated to
ensure it meets the outlined constraints.Any field which does not match the fields below will be placed under thecustom_attributesfield. Please see theImportAssetschema definition for more details: #/components/schemas/ImportAssetid- thisstrfield isrequiredto 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- auuidfield 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 thelisthas a maximum of 100 hostnames.domain- astrfield representing the domain associated with the asset. Maximum length of 260 characters.first_seen_ts- adatetime.datetimefield representing the first time an asset was seen.last_seen_ts- adatetime.datetimefield representing the last time an asset was seen.os- astrfield which describes the operating system on the asset. Maximum length of 1024 characters.os_version- astrfield which describes the version of the operating system running on the asset. Maximum length of 1024 characters.manufacturer- astrfield which declares the manufacturer of the asset. Maximum length of 1024 characters.model- astrfield 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- astrfield declaring the device type of the asset. Maximum length of 1024 characters.Feature requests and bug reportsTo 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 ourdocumentationto 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 featureWe 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 ResourcesThis project does not currently support the full runZero API. The broader runZero APIdocumentationincludes both human- and machine-generated
API documentation.runZero's OpenAPIspecis 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.