runzero.types._wrapped

Wrapped types are subclassed, method-free pydantic data types that expose additional fields or replace existing fields to occlude API detail.

These types may be declared here, and not in modules that expose functionality, when there is no constructor, method, or additional decision code on or related to the class. Every type is to be a pure Pydantic data classes with validations.

Each class should have a non-docstring comment in it describing why the REST type was insufficient.

Module Contents

Classes

CustomAttribute	DEPRECATION NOTICE:
CustomIntegration	CustomIntegration represents a custom asset data source for custom integrations use
Hostname	Hostname the dns name the asset is assigned or reachable at.
ImportAsset	Represents a custom asset to be created or merged after import.
NetworkInterface	Represents the Network Interface of an asset to be imported.
ScanOptions	Options which can be set to create or modify a scan.
ScanTemplate	A scan template object
ScanTemplateOptions	Options which can be set to create or modify a scan template.
Service	A service running on an asset.
ServiceProtocolData	ServiceProtocolData represents the attributes associated with a given service protocol
Software	Represents a piece of installed software on a particular asset.
Tag	Tag is an arbitrary string classifier applied to the asset.
Vulnerability	Represents a vulnerability present on a particular asset.

class runzero.types._wrapped.CustomAttribute(attr: str)

Bases: __CustomAttribute

DEPRECATION NOTICE:

This class is deprecated and will be removed in the 1.0 release of the SDK. You can now use a Dict[str, str] directly when setting the custom_attributes property. This class is replaced by simply using a string.

CustomAttribute is a string key / value pair from an external custom asset data source.

class Config

Config for pydantic model

class runzero.types._wrapped.CustomIntegration

Bases: runzero.types._data_models_gen.CustomIntegration

CustomIntegration represents a custom asset data source for custom integrations use

client_id: uuid.UUID

The unique ID of the runZero client/customer account that owns the object

created_at: datetime.datetime

A timestamp indicating creation time of the object

created_by_id: uuid.UUID

The unique ID of the entity that created the object

description: str | None

A text description of the custom integration

destroyed_at: datetime.datetime | None

A timestamp indicating deletion time of the object

icon: bytes | None

bytes of png formatted image with maximum size 32x32 pixels

id: uuid.UUID

The unique ID of the object

name: str

The unique name of the custom integration, without spaces.

updated_at: datetime.datetime

A timestamp indicating last modified time of the object

class runzero.types._wrapped.Hostname(hostname: str)

Bases: runzero.types._data_models_gen.Hostname

Hostname the dns name the asset is assigned or reachable at.

This can be a fully-qualified hostname with the domain name, or a short hostname.

class runzero.types._wrapped.ImportAsset

Bases: runzero.types._data_models_gen.ImportAsset

Represents a custom asset to be created or merged after import.

custom_attributes: Dict[str, str] | None

Flat map of arbitrary string key/value pairs representing custom attribute data not described in properties above. Note the maximum number of keys and length of values. Additionally, property names may only be 256 characters long.

domain: str | None

Represents a single domain name which could be applied to all non-fqdns in the hostnames field.

first_seen_ts: datetime.datetime | None

Represents the earliest time the asset was seen by the custom integration reporting it, using a date string as defined by RFC 3339, section 5.6.

hostnames: List[Hostname] | None

Represents hostnames the asset is assigned or reachable at. These can be fully-qualified hostnames with the domain name, or a short hostname.

id: str

Any value which can uniquely identify the asset within the custom integration.

manufacturer: str | None

The manufacturer of the operating system of the asset. It is advisable to keep the data clean by normalizing to existing values when possible.

model: str | None

The hardware model of the asset. It is advisable to keep the data clean by normalizing to existing values when possible.

network_interfaces: List[NetworkInterface] | None

The asset’s networking configuration.

os: str | None

The name of the asset’s operating system. It is advisable to keep the data clean by normalizing to existing values when possible.

os_version: str | None

The version of the asset’s operating system. It is advisable to keep the data clean by normalizing to existing values when possible.

run_zero_id: uuid.UUID | None

The unique identifier of the runZero asset to merge into.

services: List[Service] | None

The services running on an asset.

software: List[Software] | None

The installed software on an asset.

tags: List[Tag] | None

Arbitrary string tags applied to the asset.

vulnerabilities: List[Vulnerability] | None

The vulnerabilities associated with an asset.

class runzero.types._wrapped.NetworkInterface

Bases: runzero.types._data_models_gen.NetworkInterface

Represents the Network Interface of an asset to be imported.

ipv4_addresses: List[ipaddress.IPv4Address] | None

Represents IPV4 addresses. Addresses are ordered from most to least likely to uniquely identify the asset.

ipv6_addresses: List[ipaddress.IPv6Address] | None

Represents the IPV6 addresses. Addresses are ordered from most to least likely to uniquely identify the asset.

mac_address: str | None

Represents a MAC address in IEEE 802 MAC/EUI-48, or EUI-64 form in one of the following formats:

01:23:45:67:89:AB 01:23:45:67:89:ab:cd:ef 01-23-45-67-89-ab 01-23-45-67-89-ab-cd-ef 0123.4567.89ab 0123.4567.89ab.cdef 0123 4567 89ab cdEF

class runzero.types._wrapped.ScanOptions

Bases: runzero.types._data_models_gen.ScanOptions

Options which can be set to create or modify a scan.

host_ping_probes: str | None

Optional host ping probe list as comma separated strings. The example shows possibilities.

hosted_zone_id: str | None

The string ‘auto’ will use any available hosted zone. Otherwise, provide the string name (hostedzone1) or UUID (e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8) of a hosted zone.

hosted_zone_name: str | None

The string ‘auto’ will use any available hosted zone. Otherwise, provide the string name (hostedzone1) of the hosted zone.

probes: str | None

Optional probe list, otherwise all probes are used

scan_description: str | None

A description of the scan.

scan_frequency: ScanFrequency | None

A string time duration value representing execution frequency, if scheduled to repeat.

scan_start: str | None

Unix timestamp value indicating when the template was created.

subnet_ping_probes: str | None

Optional subnet ping probe list as comma separated strings. The example shows possibilities.

json(*args: Iterable[Any], **kwargs: Any) → str

Ensure kebab-case is kept when converting to JSON

Return type:

str

class runzero.types._wrapped.ScanTemplate

Bases: runzero.types._data_models_gen.ScanTemplate

A scan template object

acl: Dict[str, Any]

A map of IDs to strings which describe how the template may be accessed. Currently there is no authoritative list of in-use values. See existing templates for examples.

agent_id: uuid.UUID | None

ID of the explorer which may execute the template.

client_id: uuid.UUID | None

ID of the account which owns the template.

created_at: int | None

Unix timestamp value indicating when the template was created.

created_by: str | None

The username of the account which created the template.

created_by_user_id: uuid.UUID | None

The ID of the account which created the template.

cruncher_id: uuid.UUID | None

ID of the runZero cruncher the task is executing on.

custom_integration_id: uuid.UUID | None

The ID of the custom integration source, if the last task executed with this template was an import of Asset Data.

description: str | None

The description of the template.

error: str | None

The error message, if any, of the last task using the template.

global_: bool

Whether the template is globally available to all organizations.

grace_period: str | None

Additional time beyond hard expiration deadline by which the task may still be allowed to execute.

hidden: bool | None

A flag indicating whether the item is hidden from common view.

hosted_zone_id: uuid.UUID | None

The ID of the hosted zone that ran the last task the template was used with.

id: uuid.UUID

ID of the template.

linked_task_count: int | None

The number of tasks derived from the template.

name: str | None

The name of the template.

organization_id: uuid.UUID

ID of the organization the template is available in.

params: Dict[str, str] | None

A number of task parameter values. Currently there is no authoritative list of in-use values. See existing templates for examples.

parent_id: uuid.UUID | None

The ID of the parent entity of the task scheduled.

recur: bool | None

A flag representing whether derived tasks are scheduled to repeat.

recur_frequency: str | None

A string time duration value representing execution frequency, if scheduled to repeat. You may use values including as once, hourly, daily, weekly, monthly, continuous

recur_last: int | None

Unix timestamp representing the last execution if scheduled to repeat.

recur_last_task_id: uuid.UUID | None

The ID of the task that last executed if scheduled to repeat.

recur_next: int | None

Unix timestamp representing the next execution if scheduled to repeat.

site_id: uuid.UUID | None

ID of the site the template is being used in.

size_data: int | None

The total size of result data of the last task the template was used with.

size_results: int | None

The number of results in the last task the template was used with.

size_site: int | None

The size in assets of the site the last task the template was executed against.

source_id: str | None

The numeric ID of the data source, if the task executed with this template is a runZero scan or third party data connection import.

start_time: int | None

Unix timestamp representing the next execution time.

stats: Dict[str, Any] | None

A map of statistics about the last task executed with the template. Currently there is no authoritative list of in-use values. See existing templates for examples.

status: str | None

The status of the last task using the template.

template_id: uuid.UUID | None

The ID of the template.

type: str | None

The type of task the template creates.

updated_at: int | None

Unix timestamp value indicating when the template was last modified.

json(*args: Iterable[Any], **kwargs: Any) → str

Ensure kebab-case is kept when converting to JSON

Return type:

str

class runzero.types._wrapped.ScanTemplateOptions

Bases: runzero.types._data_models_gen.ScanTemplateOptions

Options which can be set to create or modify a scan template.

acl: Dict[str, Any]

A map of IDs to strings which describe how the template may be accessed. Currently there is no authoritative list of acceptable values. See existing templates for examples.

description: str | None

Description of the template.

global_: bool

Whether the template is globally available to all organizations.

name: str

Name of the template.

organization_id: uuid.UUID

The ID of the organization the template will be created in

params: Dict[str, str] | None

A number of scan parameter values. Currently there is no authoritative list of acceptable values. See existing templates for examples.

json(*args: Iterable[Any], **kwargs: Any) → str

Ensure kebab-case is kept when converting to JSON

Return type:

str

class runzero.types._wrapped.Service(**kwargs: Any)

Bases: runzero.types._data_models_gen.Service

A service running on an asset.

address: ipaddress.IPv4Address | ipaddress.IPv6Address

Represents the IPAddress (v4 or v6) that the service is available at.

custom_attributes: Dict[str, str] | None

Flat map of arbitrary string key/value pairs representing service level attributes not associated with a protocol. Note the maximum number of keys and length of values. Additionally, property names may only be 256 characters long.

port: int

The port that the service is listening on.

product: str | None

The name of the software product associated with the service.

transport: str

The communication protocol utilized by the service for its data protocols.

vendor: str | None

The name of the entity which created the service.

version: str | None

The version of the service present on the asset.

class runzero.types._wrapped.ServiceProtocolData(**kwargs: Any)

Bases: runzero.types._data_models_gen.ServiceProtocolData

ServiceProtocolData represents the attributes associated with a given service protocol

attributes: Dict[str, str] | None

A flat map of string key/value pairs which represent the properties associated with the named protocol. Note the maximum number of keys and length of values. Additionally, property names may only be 256 characters long.

name: str

The well known protocol name.

class runzero.types._wrapped.Software(**kwargs: Any)

Bases: runzero.types._data_models_gen.Software

Represents a piece of installed software on a particular asset.

cpe23: str | None

The Common Platform Enumeration v2.3 value describing the software.

custom_attributes: Dict[str, str] | None

Flat map of arbitrary string key/value pairs representing custom attribute data not described in properties above. Note the maximum number of keys and length of values. Additionally, property names may only be 256 characters long.

id: str

A value which can uniquely identify the software on an asset.

installed_at: datetime.datetime | None

The timestamp at which the software was installed on the asset, using a date string as defined by RFC 3339, section 5.6.

installed_from: str | None

The source of the installation for the software.

installed_size: int | None

The size of the software in bytes once installed on the asset.

language: str | None

Valid language tags as defined by [RFC5646].

other: str | None

Any other general descriptive or identifying information which is vendor- or product-specific and which does not logically fit in any other attribute value of a CPE.

product: str | None

Describes or identifies the most common and recognizable title or name of the product.

service_address: ipaddress.IPv4Address | ipaddress.IPv6Address | None

Represents the IPAddress (v4 or v6) that the software is available at.

service_port: int | None

The port that the software is available on.

service_transport: str | None

The transport type used to interact with the software.

software_edition: str | None

How the product is tailored to a particular market or class of end users.

target_hardware: str | None

Characterizes the instruction set architecture (e.g., x86)

target_software: str | None

A characterization of the software computing environment within which the product operates.

update: str | None

The particular update, service pack, or point release of the product.

vendor: str | None

Describes or identifies the person or organization that manufactured or created the product.

version: str | None

A vendor-specific alphanumeric strings characterizing the particular release version of the product.

class runzero.types._wrapped.Tag(tag: str)

Bases: runzero.types._data_models_gen.Tag

Tag is an arbitrary string classifier applied to the asset.

class runzero.types._wrapped.Vulnerability

Bases: runzero.types._data_models_gen.Vulnerability

Represents a vulnerability present on a particular asset.

category: str | None

A descriptive value which declares the type of vulnerability class.

cpe23: str | None

The Common Platform Enumeration v2.3 value describing the vulnerable service.

custom_attributes: Dict[str, str] | None

Flat map of arbitrary string key/value pairs representing custom attribute data not described in properties above. Note the maximum number of keys and length of values. Additionally, property names may only be 256 characters long.

cve: str | None

CVE represents the common vulnerability ID as assigned by an authority such as NIST and should be in the format of ‘CVE-YYYY-NNNNN’ where YYYY represents the year of the entry and NNNNN is the vulns unique number.

cvss2_base_score: float | None

The exploit-ability score of the vulnerability as assigned by the CVSS2 system.

cvss2_temporal_score: float | None

The current exploit-ability score (modified by ease of patching/impact of vuln/etc) of the vuln as assigned by the CVSS2 system.

cvss3_base_score: float | None

The exploit-ability score of the vulnerability as assigned by the CVSS3 system.

cvss3_temporal_score: float | None

The current exploit-ability score (modified by ease of patching/impact of vuln/etc) of the vuln as assigned by the CVSS3 system.

description: str | None

A human-understandable summary of a vulnerability.

exploitable: bool | None

Declares whether the vulnerability can be exploited on the asset.

first_detected_ts: datetime.datetime | None

Represents the Timestamp at which the vulnerability was first detected on the asset, using a date string as defined by RFC 3339, section 5.6.

id: str

A value which can uniquely identify the vulnerability on an asset.

last_detected_ts: datetime.datetime | None

Represents the Timestamp at which the vulnerability was last detected on the asset, using a date string as defined by RFC 3339, section 5.6.

name: str | None

A human-understandable name of a vulnerability.

published_ts: datetime.datetime | None

Represents the Timestamp at which the CVE was officially published, using a date string as defined by RFC 3339, section 5.6.

risk_rank: int | None

An integer representation of the risk of vuln exploitation where 0=NONE, 1=LOW, 2=MEDIUM, 3=HIGH, and 4=CRITICAL.

risk_score: float | None

The probability score of the vulnerability being exploited.

service_address: ipaddress.IPv4Address | ipaddress.IPv6Address | None

The IPAddress (v4 or v6) that the vulnerable service is available at.

service_port: int | None

The port that the vulnerable service is available on.

service_transport: str | None

The transport type used to interact with the vulnerable service.

severity_rank: int | None

An integer representation of the vuln severity where 0=NONE, 1=LOW, 2=MEDIUM, 3=HIGH, and 4=CRITICAL

severity_score: float | None

The impact score which might occur if the vulnerability were to be exploited.

solution: str | None

A human-understandable summary of the steps to take to resolve a vulnerability.